Docs: Vulkan Updates for N, part 2
      Adding Ian's feedback

Bug: 27621285

Change-Id: I7018af9e0b924b68900e4b92af464c900860a9d0
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