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>
diff --git a/src/devices/graphics/arch-vulkan.jd b/src/devices/graphics/arch-vulkan.jd
index 417873d..45c3d34 100644
--- a/src/devices/graphics/arch-vulkan.jd
+++ b/src/devices/graphics/arch-vulkan.jd
@@ -43,7 +43,7 @@
 execute commands on the GPU with significantly reduced overhead. Vulkan also
 provides a more direct mapping to the capabilities found in current graphics
 hardware, minimizing opportunities for driver bugs and reducing developer
-testing time (e.g. less time required to troubleshoot OpenGL bugs).</p>
+testing time (e.g. less time required to troubleshoot Vulkan bugs).</p>
 
 <p>For general information on Vulkan, refer to the
 <a href="http://khr.io/vulkanlaunchoverview">Vulkan Overview</a> or see the list
@@ -52,9 +52,18 @@
 <h2 id=vulkan_components>Vulkan components</h2>
 <p>Vulkan support includes the following components:</p>
 <p><img src="{@docRoot}devices/graphics/images/ape_graphics_vulkan.png"></p>
-<p class=caption>Figure 1: Vulkan components</p>
+<p class=img-caption>Figure 1: Vulkan components</p>
 
 <ul>
+<li><strong>Vulkan Validation Layers</strong> (<em>provided in the Android
+NDK</em>). A set of libraries used by developers during the development of
+Vulkan apps. The Vulkan runtime library and the Vulkan driver from graphics
+vendors do not contain runtime error-checking to keep Vulkan runtime efficient.
+Instead, the validation libraries are used (only during development) to find
+errors in an application's use of the Vulkan API. The Vulkan Validation
+libraries are linked into the app during development and perform this error
+checking. After all API usage issues are found, the aplication no longer needs
+to include these libraries in the app.</li>
 <li><strong>Vulkan Runtime </strong><em>(provided by Android)</em>. A native
 library <code>(libvulkan.so</code>) that provides a new public native API
 called <a href="https://www.khronos.org/vulkan">Vulkan</a>. Most functionality
@@ -64,8 +73,7 @@
 dependencies such as BufferQueue.</li>
 <li><strong>Vulkan Driver </strong><em>(provided by SoC)</em>. Maps the Vulkan
 API onto hardware-specific GPU commands and interactions with the kernel
-graphics driver. It is expected the same single kernel driver will service both
-the Vulkan and OpenGL ES API drivers.</li>
+graphics driver.</li>
 </ul>
 
 <h2 id=modified_components>Modified components</h2>
@@ -89,20 +97,35 @@
 ES</a>).
 
 <h2 id=apis>Vulkan API</h2>
-<p>Vulkan support also includes a new public native (NDK) Vulkan API; details at
-<a href="https://www.khronos.org/vulkan/">https://www.khronos.org/vulkan/</a>.
-No system UI or extensions are required.</p>
+<p>The Android platform includes an
+<a href="https://developer.android.com/ndk/guides/graphics/index.html">Android-specific
+implementation</a> of the <a href="https://www.khronos.org/vulkan/">Vulkan API
+specification</a> from the Khronos Group. Android applications must use the
+<a href="{@docRoot}devices/graphics/implement-vulkan.html#wsi">Window System
+Integration (WSI) extensions</a> to output their rendering.</p>
 
 <h2 id=resources>Resources</h2>
-<p>Use the following resources to learn more about Vulkan</p>
+<p>Use the following resources to learn more about Vulkan:</p>
 <ul>
+
 <li>
-<a href="https://partner-android.googlesource.com/platform/frameworks/native/+/nyc-dev/vulkan/">Vulkan
-Loader </a>(libvulkan.so) on Partner repo (platform/frameworks/native/vulkan)</li>
-<li>
-<a href="https://partner-android.googlesource.com/platform/frameworks/native/+/4e89bf211e668a4e47c9a70d10d03c4b9dd5b97d/vulkan/doc">Vulkan Developer's
-Guide</a></li>
+<a href="https://googleplex-android.git.corp.google.com/platform/frameworks/native/+/nyc-dr1-release/vulkan/#">Vulkan
+Loader </a>(libvulkan.so) at <code>platform/frameworks/native/vulkan</code>.
+Contains Android's Vulkan loader, as well as some Vulkan-related tools useful to
+platform developers.</li>
+
+<li><a href="https://android.googlesource.com/platform/frameworks/native/+/master/vulkan/doc/implementors_guide/implementors_guide.html">Vulkan
+Implementor's Guide</a>. Intended for GPU IHVs writing Vulkan drivers for
+Android and OEMs integrating those drivers for specific devices. It describes
+how a Vulkan driver interacts with the system, how GPU-specific tools should be
+installed, and Android-specific requirements.</li>
+
 <li><a href="https://developer.android.com/ndk/guides/graphics/index.html">Vulkan
-Graphics API</a></li>
-<li><a href="https://www.khronos.org/#slider_vulkan">Vulkan News</a></li>
+Graphics API Guide</a>. Includes information on getting started with using
+Vulkan in an Android app, details on Vulkan design guidelines on the Android
+platform, how to use Vulkan's shader compilers, and how to use use validation
+layers to help assure stability in apps using Vulkan.</li>
+
+<li><a href="https://www.khronos.org/#slider_vulkan">Vulkan News</a>. Covers
+events, patches, tutorials, and more Vulkan-related news articles.</li>
 </ul>
diff --git a/src/devices/graphics/images/ape_graphics_vulkan.png b/src/devices/graphics/images/ape_graphics_vulkan.png
index d25ac5d..b9910cf 100644
--- a/src/devices/graphics/images/ape_graphics_vulkan.png
+++ b/src/devices/graphics/images/ape_graphics_vulkan.png
Binary files differ
diff --git a/src/devices/graphics/implement-vulkan.jd b/src/devices/graphics/implement-vulkan.jd
index 7a3dee3..dcc2efc 100644
--- a/src/devices/graphics/implement-vulkan.jd
+++ b/src/devices/graphics/implement-vulkan.jd
@@ -39,21 +39,22 @@
 
 <p>To implement Vulkan, a device:</p>
 <ul>
-<li>Must include Vulkan Loader (provided by Android) in the build.</li>
-<li>May optionally enumerate a Vulkan Driver (provided by SoCs such as GPU IHVs)
-that implements the
+<li>Must include the Vulkan Loader (provided by Android) in the build.</li>
+<li>Must include a Vulkan driver (provided by SoCs such as GPU IHVs) that
+implements the
 <a href="https://www.khronos.org/registry/vulkan/specs/1.0-wsi_extensions/xhtml/vkspec.html">Vulkan
-API</a>. The driver is required to support Vulkan functionality in the presence
-of capable GPU hardware. Consult your SoC vendor to request driver support.</li>
+API</a>. To support Vulkan functionality, the Android device needs capable GPU
+hardware and the associated driver. Consult your SoC vendor to request driver
+support.</li>
 </ul>
-<p>If a Vulkan driver is enumerated, the device must have the
+<p>If a Vulkan driver is available on the device, the device needs to declare
 <code>FEATURE_VULKAN_HARDWARE_LEVEL</code> and
 <code>FEATURE_VULKAN_HARDWARE_VERSION</code> system features, with versions that
 accurately reflect the capabilities of the device.</p>
 
 <h2 id=vulkan_loader>Vulkan Loader</h2>
 <p>The primary interface between Vulkan applications and a device's Vulkan
-driver is the loader, which is part of AOSP
+driver is the Vulkan loader, which is part of Android Open Source Project (AOSP)
 (<code>platform/frameworks/native/vulkan</code>) and installed at
 <code>/system/lib[64]/libvulkan.so</code>. The loader provides the core Vulkan
 API entry points, as well as entry points of a few extensions that are required
@@ -63,14 +64,17 @@
 can expose additional extensions and/or intercept core API calls on their way to
 the driver.</p>
 
-<p>The NDK includes a stub <code>libvulkan.so</code> exporting the same symbols
-as the loader. Calling the Vulkan functions exported from
-<code>libvulkan.so</code> enters trampoline functions in the loader, which then
-dispatch to the appropriate layer or driver based on their first argument. The
-<code>vkGet*ProcAddr</code> calls return the function pointers to which the
-trampolines would dispatch, so calling through these function pointers (rather
-than the exported symbols) is slightly more efficient as it skips the trampoline
-and dispatch.</p>
+<p>The NDK includes a stub <code>libvulkan.so</code> library that exports the
+same symbols as the loader and which is used for linking. When running on a
+device, applications call the Vulkan functions exported from
+<code>libvulkan.so</code> (the real library, not the stub) to enter trampoline
+functions in the loader (which then dispatch to the appropriate layer or driver
+based on their first argument). The <code>vkGetDeviceProcAddr</code> calls
+return the function pointers to which the trampolines would dispatch (i.e. it
+calls directly into the core API code), so calling through these function
+pointers (rather than the exported symbols) is slightly more efficient as it
+skips the trampoline and dispatch. However, <code>vkGetInstanceProcAddr</code>
+must still call into trampoline code.</p>
 
 <h2 id=driver_emun>Driver enumeration and loading</h2>
 <p>Android expects the GPUs available to the system to be known when the system
@@ -80,7 +84,8 @@
 drivers are:</p>
 
 <p>
-<pre>/vendor/lib/hw/vulkan.&lt;ro.product.platform&gt;.so
+<pre>
+/vendor/lib/hw/vulkan.&lt;ro.product.platform&gt;.so
 /vendor/lib64/hw/vulkan.&lt;ro.product.platform&gt;.so
 </pre>
 </p>
@@ -109,8 +114,7 @@
 <p>The Vulkan loader supports enumerating and loading layers that can expose
 additional extensions and/or intercept core API calls on their way to the
 driver. Android 7.0 does not include layers on the system image; however,
-applications may include layers in their APK and SoC developer tools (ARM DS-5,
-Adreno SDK, PowerVR Tools, etc.) may also include layers.</p>
+applications may include layers in their APK.</p>
 <p>When using layers, keep in mind that Android's security model and policies
 differ significantly from other platforms. In particular, Android does not allow
 loading external code into a non-debuggable process on production (non-rooted)
@@ -136,10 +140,10 @@
 application; different applications using the same layer may still use
 different versions. Developers choose which of these layers to ship in their
 application package.</li>
-<li><strong>Injected layers</strong>. Includes layers such as framerate, social
-network, or game launcher overlays provided by the user or some other
-application without the application's knowledge or consent. These violate
-Android's security policies and will not be supported.</li>
+<li><strong>Injected (implicit) layers</strong>. Includes layers such as
+framerate, social network, or game launcher overlays provided by the user or
+some other application without the application's knowledge or consent. These
+violate Android's security policies and are not supported.</li>
 </ul>
 
 <p>In the normal state, the loader searches for layers only in the application's
@@ -149,11 +153,12 @@
 reasons to avoid loading libraries before enabling them don't apply.</p>
 
 <p>Android allows layers to be ported with build-environment changes between
-Android and other platforms. The interface between layers and the loader must
-match the interface used by the
-<a href="http://lunarg.com/vulkan-sdk/">LunarG</a> loader used on Windows and
-Linux. Versions of the LunarG validation layers that have been verified to build
-and work on Android are hosted in the android_layers branch of the
+Android and other platforms. For details on the interface between layers and the
+loader, refer to
+<a href="https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/loader/LoaderAndLayerInterface.md">Vulkan
+Loader Specification and Architecture Overview</a>. Versions of the LunarG
+validation layers that have been verified to build and work on Android are
+hosted in the android_layers branch of the
 <a href="https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/tree/android_layers">KhronosGroup/Vulkan-LoaderAndValidationLayers</a>
 project on GitHub.</p>
 
@@ -161,9 +166,9 @@
 <p>The Window System Integration (WSI) extensions <code>VK_KHR_surface</code>,
 <code>VK_KHR_android_surface</code>, and <code>VK_KHR_swapchain</code> are
 implemented by the platform and live in <code>libvulkan.so</code>. The
-<code>VkSwapchain</code> object and all interaction with
-<code>ANativeWindow</code> is handled by the platform and not exposed to
-drivers. The WSI implementation relies on the
+<code>VkSurfaceKHR</code> and <code>VkSwapchainKHR</code> objects and all
+interaction with <code>ANativeWindow</code> is handled by the platform and is
+not exposed to drivers. The WSI implementation relies on the
 <code>VK_ANDROID_native_buffer</code> extension (described below) which must be
 supported by the driver; this extension is only used by the WSI implementation
 and will not be exposed to applications.</p>
@@ -185,8 +190,8 @@
 </pre>
 </p>
 
-<p>The format and <code>imageUsage</code> parameters are taken from the
-<code>VkSwapchainCreateInfoKHR</code> structure. The driver should fill
+<p>The <code>format</code> and <code>imageUsage</code> parameters are taken from
+the <code>VkSwapchainCreateInfoKHR</code> structure. The driver should fill
 <code>*grallocUsage</code> with the gralloc usage flags required for the format
 and usage (which are combined with the usage flags requested by the swapchain
 consumer when allocating buffers).</p>
@@ -235,7 +240,6 @@
   .pQueueFamilyIndices = VkSwapChainCreateInfoWSI::pQueueFamilyIndices
 </pre></p>
 
-
 <h3 id=acquire_image>Aquiring images</h3>
 <p><code>vkAcquireImageANDROID</code> acquires ownership of a swapchain image
 and imports an externally-signalled native fence into both an existing
@@ -291,8 +295,6 @@
 <code>*pNativeFenceFd</code> to -1. The file descriptor returned in
 *<code>pNativeFenceFd</code> is owned and will be closed by the caller.</p>
 
-
-
 <h3 id=update_drivers>Updating drivers</h3>
 
 <p>Many drivers can ignore the image parameter, but some may need to prepare