Docs: Camera hardening updates for N
Adding Clay's feedback
Bug: 27702676
Change-Id: Ia05d1f4273e3f11851def46b8bb15144831fe0d5
diff --git a/src/devices/camera/images/ape_camera_n_api1_hal1.png b/src/devices/camera/images/ape_camera_n_api1_hal1.png
new file mode 100644
index 0000000..8898379
--- /dev/null
+++ b/src/devices/camera/images/ape_camera_n_api1_hal1.png
Binary files differ
diff --git a/src/devices/camera/images/ape_camera_n_api1_hal3.png b/src/devices/camera/images/ape_camera_n_api1_hal3.png
new file mode 100644
index 0000000..c366512
--- /dev/null
+++ b/src/devices/camera/images/ape_camera_n_api1_hal3.png
Binary files differ
diff --git a/src/devices/camera/images/ape_camera_n_api2_hal3.png b/src/devices/camera/images/ape_camera_n_api2_hal3.png
new file mode 100644
index 0000000..9451cb5
--- /dev/null
+++ b/src/devices/camera/images/ape_camera_n_api2_hal3.png
Binary files differ
diff --git a/src/devices/camera/versioning.jd b/src/devices/camera/versioning.jd
index 7c4d1b3..402684b 100644
--- a/src/devices/camera/versioning.jd
+++ b/src/devices/camera/versioning.jd
@@ -24,82 +24,101 @@
</div>
</div>
-<p>The Android 5.0 (Lollipop) platform release adds a new app-level camera framework. This
-document outlines some logistical details that OEMs and SoC vendors need to
-know.</p>
+<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>Terms</h2>
+<h2 id=glossary>Terminology</h2>
-<p>The following terms are used in this document:</p>
+<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</em>: The app-level camera framework on KitKat and earlier devices, exposed
-through the <code>android.hardware.Camera</code> class.
- <li><em>Camera API2</em>: The app-level camera framework on 5.0 and later
-devices, exposed through the<code> android.hardware.camera2</code> package.
- <li><em>Camera HAL</em>: The camera module layer that SoC vendors implement. The app-level public
-frameworks are built on top of the camera HAL.
- <li><em>Camera HAL3.2</em>: The version of the camera device HAL that is
-being released with Lollipop. KitKat launched with an earlier version (Camera HAL3.1).
- <li><em>Camera API1 CTS</em>: The set of camera Compatibility Test Suite (CTS) tests that run on top of
-Camera API1.
- <li><em>Camera API2 CTS</em>: An additional set of camera CTS tests that run on top of Camera API2.
+<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>
-<h2 id=camera_api2_overview>Camera API2 overview</h2>
+<h3 id=camera_api2>Camera API2</h3>
-<p>The new camera frameworks expose lower-level camera control to the app,
+<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. See this <a
-href="https://www.youtube.com/watch?v=92fgcUNCHic&feature=youtu.be&t=29m50s">brief
-video overview from the Google I/O 2014 conference</a> for additional details.
-</p>
+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>
-<h2 id=camera_api1_availability_and_deprecation_in_l>Camera API1 availability and deprecation in Android 5.0</h2>
-
-<p>The Camera API1 interfaces are still available for apps to use on Android
-5.0 and later devices, and camera apps built on top of Camera API1 should work
-as before. Camera API1 is being marked as deprecated in Lollipop, indicating that it
-will be phased out over time and new platform development will focus on Camera
-API2. However, we expect this phase-out period to be lengthy, and Camera API1
-apps will continue to be supported in Android for some time to come.</p>
-
-<p>All earlier camera HAL versions, including Camera HAL1.0, will also continue to
-be supported.</p>
-
-<h2 id=camera_api2_capabilities_and_support_levels>Camera API2 capabilities and support levels</h2>
-
-<p>Android 5.0 and later devices feature Camera API2, however they may not fully support all of
-the new features of Camera API2. The
+<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 report one of three support levels:
-<code>LEGACY</code>, <code>FULL</code>, and <code>LIMITED</code>.</p>
+through the Camera API2 interfaces reports one of the following support
+levels:</p>
-<p><em>Legacy</em> devices expose a level of capabilities through the Camera API2 interfaces that
-are approximately the same as is exposed to apps through the Camera API1
-interfaces; the legacy frameworks code conceptually translates Camera API2
-calls into Camera API1 calls under the hood. Legacy devices do not support
-the new Camera API2 features including per-frame controls.</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><em>Full</em> devices support all of the major capabilities of Camera API2. Full devices by
-necessity must have a Camera HAL version of 3.2 (shipping with Android 5.0) or later.</p>
+<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><em>Limited</em> devices are in between: They support some of the new Camera API2 capabilities,
-but not all of them, and must also comprise a Camera HAL version of 3.2 or later.</p>
-
-<p>Individual capabilities are exposed via the<code>
-android.request.availableCapabilities</code> property in the Camera API2
-interfaces. Full devices require both the <code>MANUAL_SENSOR</code> and
-<code>MANUAL_POST_PROCESSING</code> capabilities, among others. There is also a
-<code>RAW</code> capability that is optional even for full devices. Limited
-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
-Play Store filtering of Camera API2 camera apps; a device must define the
-feature flag if any of its attached camera devices supports the feature.</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>
@@ -110,35 +129,127 @@
<h2 id=cts_requirements>CTS requirements</h2>
-<p>Android 5.0 and later devices must pass both Camera API1 CTS and Camera API2
-CTS. And as always, devices are required to pass the CTS Verifier camera
-tests.</p>
+<p>Android 5.0 and later devices must pass the Camera API1 CTS, Camera API2 CTS,
+and CTS Verifier camera tests.</p>
-<p>To add some context: For devices that don’t feature a Camera HAL3.2
-implementation and are not capable of supporting the full Camera API2
-interfaces, the Camera API2 CTS tests must still be passed. However, in this
-case the device will be running in Camera API2 <em>legacy</em> mode (in which
-the Camera API2 calls are conceptually just mapped to Camera
-API1 calls); and any Camera API2 CTS tests that relate to features or
-capabilities beyond Camera API1 have logic that will skip them in the case of
-old (legacy) devices.</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 a legacy device, the Camera API2 CTS tests that are not skipped are purely
-using the existing public Camera API1 interfaces and capabilities (with no new
-requirements), and any bugs that are exposed (which will in turn cause a Camera
-API2 CTS failure) are bugs that were already present in the device’s existing
-Camera HAL and would also be a bug that could be easily hit by existing Camera
-API1 apps. The expectation is that there should be very few bugs of this
-nature. Nevertheless, any such bugs will need to be fixed.</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="version-history">Version history</h2>
+<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. Please use get_vendor_tag_ops in
+<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>
