src/devices/camera/versioning.jd

page.title=Camera version support
@jd:body

<!--
    Copyright 2014 The Android Open Source Project

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<div id="qv-wrapper">
  <div id="qv">
    <h2>In this document</h2>
    <ol id="auto-toc">
    </ol>
  </div>
</div>

<p>This page details version differences in Camera HALs, APIs, and associated
Android Compatibility Test Suite (CTS) tests. It also covers several
architectural changes made to harden and secure the camera framework in Android
7.0 and the updates vendors must make to support these changes in their camera
implementations.</p>

<h2 id=glossary>Terminology</h2>

<p>The following terms are used on this page:</p>

<dl>

<dt>Camera API1</dt>
<dd>The app-level camera framework on Android 4.4 and earlier devices, exposed
through the <code>android.hardware.Camera</code> class.</dd>

<dt>Camera API2</dt>
<dd>The app-level camera framework on Android 5.0 and later devices, exposed
through the<code> android.hardware.camera2</code> package.</dd>

<dt>Camera HAL</dt>
<dd>The camera module layer implemented by SoC vendors. The app-level public
frameworks are built on top of the camera HAL.</dd>

<dt>Camera HAL3.1</dt>
<dd>Version of the camera device HAL released with Android 4.4.</dd>

<dt>Camera HAL3.2</dt>
<dd>Version of the camera device HAL released with Android 5.0.</dd>

<dt>Camera API1 CTS</dt>
<dd>Set of camera Compatibility Test Suite (CTS) tests that run on top of Camera
API1.</dd>

<dt>Camera API2 CTS</dt>
<dd>Additional set of camera CTS tests that run on top of Camera API2.</dd>

</dl>


<h2 id=camera_apis>Camera APIs</h2>


<h3 id=camera_api1>Camera API1</h3>

<p>Android 5.0 deprecated Camera API1, which continues to be phased out as new
platform development focuses on Camera API2. However, the phase-out period will
be lengthy, and Android releases will continue to support Camera API1 apps for
some time. Specifically, support continues for:</p>

<ul>
<li><em>Camera API1 interfaces for apps</em>. Camera apps built on top of Camera API1
should work as they do on devices running earlier Android release versions.</li>
<li><em>Camera HAL versions</em>. Includes support for Camera HAL1.0.</li>
</ul>

<h3 id=camera_api2>Camera API2</h3>

<p>The Camera API2 framework exposes lower-level camera control to the app,
including efficient zero-copy burst/streaming flows and per-frame controls of
exposure, gain, white balance gains, color conversion, denoising, sharpening,
and more. For details, watch the
<a href="https://www.youtube.com/watch?v=92fgcUNCHic&feature=youtu.be&t=29m50s">Google
I/O video overview</a>.</p>

<p>Android 5.0 and later includes Camera API2; however, devices running Android
5.0 and later may not support all Camera API2 features. The
<code>android.info.supportedHardwareLevel</code> property that apps can query
through the Camera API2 interfaces reports one of the following support
levels:</p>

<ul>
<li><code>LEGACY</code>. These devices expose capabilities to apps through the
Camera API2 interfaces that are approximately the same capabilities as those
exposed to apps through the Camera API1 interfaces. The legacy frameworks code
conceptually translates Camera API2 calls into Camera API1 calls; legacy devices
do not support Camera API2 features such as per-frame controls.</li>
<li><code>FULL</code>. These devices support all of major capabilities of Camera
API2 and must use Camera HAL 3.2 or later and Android 5.0 or later.</li>
<li><code>LIMITED</code>. These devices support some Camera API2 capabilities
(but not all) and must use Camera HAL 3.2 or later.</li>
</ul>

<p>Individual capabilities are exposed via the
<code>android.request.availableCapabilities</code> property in the Camera API2
interfaces. <code>FULL</code> devices require the <code>MANUAL_SENSOR</code> and
<code>MANUAL_POST_PROCESSING</code> capabilities, among others. The
<code>RAW</code> capability is optional even for <code>FULL</code> devices.
<code>LIMITED</code> devices can advertise any subset of these capabilities,
including none of them. However, the <code>BACKWARD_COMPATIBLE</code> capability
must always be defined.</p>

<p>The supported hardware level of the device, as well as the specific Camera
API2 capabilities it supports, are available as the following feature flags to
allow Google Play filtering of Camera API2 camera apps.</p>

<ul>
  <li><code>android.hardware.camera.hardware_level.full</code>
  <li><code>android.hardware.camera.capability.raw</code>
  <li><code>android.hardware.camera.capability.manual_sensor</code>
  <li><code>android.hardware.camera.capability.manual_post_processing</code>
</ul>

<h2 id=cts_requirements>CTS requirements</h2>

<p>Android 5.0 and later devices must pass the Camera API1 CTS, Camera API2 CTS,
and CTS Verifier camera tests.</p>

<p>Devices that do not feature a Camera HAL3.2 implementation and are not
capable of supporting the full Camera API2 interfaces must still pass the Camera
API2 CTS tests. However, the device will be running in Camera API2
<code>LEGACY</code> mode (in which the Camera API2 calls are conceptually mapped
to Camera API1 calls) so any Camera API2 CTS tests related to features or
capabilities beyond Camera API1 will be automatically skipped.</p>

<p>On legacy devices, Camera API2 CTS tests that are not skipped use the
existing public Camera API1 interfaces and capabilities with no new
requirements. Bugs that are exposed (and which cause a Camera API2 CTS failure)
are bugs already present in the device’s existing Camera HAL, and thus would
be found by existing Camera API1 apps. We do not expect many bugs of this nature
(however, any such bugs must be fixed to pass the Camera API2 CTS tests).</p>

<h2 id=hardening>Camera framework hardening</h2>

<p>To harden media and camera framework security, Android 7.0 moves camera
service out of mediaserver. Vendors may need to make changes in the camera HAL
depending on the API and HAL versions in use. The following sections detail
architectural changes in AP1 and AP2 for HAL1 and HAL3, as well as general
requirements.</p>

<h3 id=hardening_api1>Architectural changes for API1</h3>
<p>API1 video recording may assume camera and video encoder live in the same
process. When using API1 on:</p>

<ul>
<li>HAL3, where camera service uses BufferQueue to pass buffers between
processes, <strong>no vendor update</strong> is necessary.
<p><img src="images/ape_camera_n_api1_hal3.png" alt="Android 7.0 camera and media
stack in API1 on HAL3" id="figure1" /></p>
<p class="img-caption"><strong>Figure 1.</strong>Android 7.0 camera and media
stack in API1 on HAL3.</p>
</li>
<li>HAL1, which supports passing metadata in video buffers, <strong>vendors must
update the HAL to allow camera and video encoder in different processes</strong>
(e.g., the HAL cannot store virtual addresses in the metadata).
<p><img src="images/ape_camera_n_api1_hal1.png" alt="Android 7.0 camera and media
stack in API1 on HAL1" id="figure1" /></p>
<p class="img-caption"><strong>Figure 2.</strong>Android 7.0 camera and media
stack in API1 on HAL1.</p>
</li>
</ul>

<h3 id=hardening_api2>Architectural changes for API2</h3>
<p>For API2 on HAL1 or HAL3, BufferQueue passes buffers so those paths continue
to work. The Android 7.0 architecture for API2 on:</p>

<ul>
<li>HAL1 is not affected by the cameraservice move, and <strong>no vendor
update</strong> is necessary.</li>
<li>HAL3 <em>is</em> affected, but <strong>no vendor update</strong> is
necessary:
<p><img src="images/ape_camera_n_api2_hal3.png" alt="Android 7.0 camera and
media stack in API2 on HAL2" id="figure1" /></p>
<p class="img-caption"><strong>Figure 3.</strong>Android 7.0 camera and media
stack in API2 on HAL3.</p>
</li>
</ul>

<h3 id=hardening_general>Additional requirements</h3>
<p>The architectural changes made for hardening media and camera framework
security include the following additional device requirements.</p>

<ul>
<li><strong>General</strong>. Devices require additional bandwidth due to IPC,
which may affect time-sensitive camera use cases such as high-speed video
recording. Vendors can measure actual impact by running
<code>android.hardware.camera2.cts.PerformanceTest</code> and the Google Camera
App for 120/240 FPS high speed video recording. Devices also require a small
amount of additional RAM to create the new process.</li>
<li><strong>Pass metadata in video buffers</strong>(<em>HAL1 only</em>). If HAL1
stores metadata instead of real YUV frame data in video buffers, the HAL must
not store anything that is invalid across process boundaries, including native
handles. If HAL passes native handles in the metadata in video buffers, you must
update it to use <code>kMetadataBufferTypeNativeHandleSource</code> as the
metadata buffer type and pass <code>VideoNativeHandleMetadata</code> in video
buffers.
<p>With <code>VideoNativeHandleMetadata</code>, camera and media frameworks are
able to pass the video buffers between processes by serializing and
deserializing the native handles properly. If HAL chooses to continue using
<code>kMetadataBufferTypeCameraSource</code> as the metadata buffer type, the
metadata must be able to be passed between processes as plain values.</p>
</li>
<li><strong>Buffer handle address does not always store same buffer</strong>
(<em>HAL3 only</em>). For each capture request, HAL3 gets addresses of buffer
handles. HAL cannot use the addresses to identify buffers because the addresses
may store another buffer handle after HAL returns the buffer. You must update
the HAL to use buffer handles to identify the buffers. For example: HAL receives
a buffer handle address A, which stores buffer handle A. After HAL returns
buffer handle A, buffer handle address A may store buffer handle B next time the
HAL receives it.</li>
<li><strong>Update SELinux policies for cameraserver</strong>. If
device-specific SELinux policies give mediaserver permissions to run the camera,
you must update the SELinux policies to give cameraserver proper permissions. We
do not encourage replicating the mediaserver's SELinux policies for cameraserver
(as mediaserver and cameraserver generally require different resources in the
system). Cameraserver should have only the permissions needed to perform camera
functionalities and any unnecessary camera-related permissions in mediaserver
should be removed.</p>

<h3 id=hardening_validation>Validation</h3>
<p>For all devices that include a camera and run Android 7.0, verify the
implementation by running Android 7.0 CTS. Although Android 7.0 does not include
new CTS tests that verify camera service changes, existing CTS tests will fail
if you have not made the updates indicated above.</p>

<h2 id="version-history">Camera HAL version history</h2>
<p>For a list of tests available for evaluating the Android Camera HAL, see the
<a href="{@docRoot}compatibility/cts/camera-hal.html">Camera HAL Testing
Checklist</a>.</p>

<h3 id="32">3.2</h3>

<p>Second revision of expanded-capability HAL:</p>

<ul>
<li>Deprecates get_metadata_vendor_tag_ops. Use get_vendor_tag_ops in
camera_common.h instead.</li>
<li>register_stream_buffers deprecated. All gralloc buffers provided by
framework to HAL in process_capture_request may be new at any time.</li>
<li>Add partial result support. process_capture_result may be called multiple
times with a subset of the available result before the full result is available.</li>
<li>Add manual template to camera3_request_template. The applications may use
this template to control the capture settings directly.</li>
<li>Rework the bidirectional and input stream specifications.</li>
<li>Change the input buffer return path. The buffer is returned in
process_capture_result instead of process_capture_request.</li>
</ul>

<h3 id="31">3.1</h3>

<p>Minor revision of expanded-capability HAL:</p>

<ul>
<li>configure_streams passes consumer usage flags to the HAL.</li>
<li>flush call to drop all in-flight requests/buffers as fast as possible.</li>
</ul>

<h3 id="30">3.0</h3>

<p>First revision of expanded-capability HAL:</p>

<ul>
<li>Major version change since the ABI is completely different. No change to the
required hardware capabilities or operational model from 2.0.</li>
<li>Reworked input request and stream queue interfaces: Framework calls into HAL
with next request and stream buffers already dequeued. Sync framework support
is included, necessary for efficient implementations.</li>
<li>Moved triggers into requests, most notifications into results.</li>
<li>Consolidated all callbacks into framework into one structure, and all setup
methods into a single initialize() call.</li>
<li>Made stream configuration into a single call to simplify stream management.
Bidirectional streams replace STREAM_FROM_STREAM construct.</li>
<li>Limited mode semantics for older/limited hardware devices.</li>
</ul>

<h3 id="20">2.0</h3>

<p>Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:</p>

<ul>
<li>Sufficient for implementing existing android.hardware.Camera API.</li>
<li>Allows for ZSL queue in camera service layer</li>
<li>Not tested for any new features such manual capture control, Bayer RAW
capture, reprocessing of RAW data.</li>
</ul>

<h3 id="10">1.0</strong></h3>

<p>Initial Android camera HAL (Android 4.0) [camera.h]:</p>

<ul>
<li>Converted from C++ CameraHardwareInterface abstraction layer.</li>
<li>Supports android.hardware.Camera API.</li>
</ul>