Docs: Changes to source.android.com

  - 202498507 Devsite localized content from translation request 944914. by Android Partner Docs <noreply@android.com>
  - 202368991 Document seccomp crashes. by Android Partner Docs <noreply@android.com>
  - 202365193 Devsite localized content from translation request 941016. by Android Partner Docs <noreply@android.com>
  - 202334002 Devsite localized content from translation request 944913. by Android Partner Docs <noreply@android.com>
  - 202333988 Devsite localized content from translation request 944152. by Android Partner Docs <noreply@android.com>
  - 202307420 Update Implementing Vulkan page. by Android Partner Docs <noreply@android.com>
  - 202218233 The -j64 seems unrealistic for most users.  Bumped it dow... by Gina Dimino <gdimino@google.com>
  - 202200614 Moving Treble content to main file (and removing treble f... by Heidi von Markham <hvm@google.com>
  - 202192748 Clarify HIDL threading documentation. by Android Partner Docs <noreply@android.com>
  - 202148581 Publish localized bulletins by Danielle Roberts <daroberts@google.com>
  - 202141713 Devsite localized content from translation request 937937. by Android Partner Docs <noreply@android.com>
  - 202141703 Devsite localized content from translation request 941621. by Android Partner Docs <noreply@android.com>
  - 202141693 Devsite localized content from translation request 936854. by Android Partner Docs <noreply@android.com>
  - 202070722 Automated g4 rollback of changelist 182578621. by Christina Nguyen <cqn@google.com>
  - 202039586 Noting the need for upstream patches to some projects. by Clay Murphy <claym@google.com>
  - 202035931 Devsite localized content from translation request 942523. by Android Partner Docs <noreply@android.com>
  - 201978491 Devsite localized content from translation request 940149. by Android Partner Docs <noreply@android.com>
  - 201749091 UpdatingHAL references/adding HIDL references by Android Partner Docs <noreply@android.com>
  - 201700681 Devsite localized content from translation request 940151. by Android Partner Docs <noreply@android.com>
  - 201700650 Devsite localized content from translation request 941012. by Android Partner Docs <noreply@android.com>
  - 201700579 Devsite localized content from translation request 942527. by Android Partner Docs <noreply@android.com>
  - 201700572 Devsite localized content from translation request 940150. by Android Partner Docs <noreply@android.com>
  - 201700538 Devsite localized content from translation request 932858. by Android Partner Docs <noreply@android.com>
  - 201700524 Devsite localized content from translation request 943117. by Android Partner Docs <noreply@android.com>
  - 201700504 Devsite localized content from translation request 943114. by Android Partner Docs <noreply@android.com>
  - 201537155 Devsite localized content from translation request 937234. by Android Partner Docs <noreply@android.com>
  - 201537147 Devsite localized content from translation request 941017. by Android Partner Docs <noreply@android.com>
  - 201532584 HAL to HIDL (change to "master" directory) by Android Partner Docs <noreply@android.com>
  - 201376845 Devsite localized content from translation request 910444. by Android Partner Docs <noreply@android.com>
  - 201371305 Devsite localized content from translation request 925769. by Android Partner Docs <noreply@android.com>
  - 201371295 Devsite localized content from translation request 938920. by Android Partner Docs <noreply@android.com>
  - 201264243 Removing version from VTS Codelab and O references. by Heidi von Markham <hvm@google.com>
  - 201207845 Add measurements for version 8.x on Nexus 5X, Nexus 6P, P... by Android Partner Docs <noreply@android.com>
  - 201195333 Devsite localized content from translation request 937940. by Android Partner Docs <noreply@android.com>
  - 201028550 Changed "Functional patches" table description in Pixel b... by Android Partner Docs <noreply@android.com>
  - 201021773 Devsite localized content from translation request 939440. by Android Partner Docs <noreply@android.com>
  - 201021757 Devsite localized content from translation request 939442. by Android Partner Docs <noreply@android.com>
  - 200732813 Devsite localized content from translation request 934614. by Android Partner Docs <noreply@android.com>
  - 200732804 Devsite localized content from translation request 910442. by Android Partner Docs <noreply@android.com>
  - 200625210 Updating warning about Valgrind deprecation by Heidi von Markham <hvm@google.com>
  - 200618019 Simple fix to removing misleading Git images by Heidi von Markham <hvm@google.com>
  - 200581373 Partner Security Updates and Resources Page has wrong OS ... by Android Partner Docs <noreply@android.com>
  - 200553261 Devsite localized content from translation request 936855. by Android Partner Docs <noreply@android.com>
  - 200553240 Devsite localized content from translation request 928419. by Android Partner Docs <noreply@android.com>
  - 200553234 Devsite localized content from translation request 928433. by Android Partner Docs <noreply@android.com>
  - 200553227 Devsite localized content from translation request 938813. by Android Partner Docs <noreply@android.com>
  - 200428587 Add link to CTS downloads page. by Kenneth Lau <kennethlau@google.com>
  - 200422176 Update CTS/CTS-Verifier downloads for CTS-Jun-2018 Releases by Android Partner Docs <noreply@android.com>
  - 200409107 Devsite localized content from translation request 931899. by Android Partner Docs <noreply@android.com>
  - 200289107 Android 7 -> Android 7.x and earlier; Android 8 -> Androi... by Android Partner Docs <noreply@android.com>
  - 200275031 Replace index.html with _index.yaml. by Android Partner Docs <noreply@android.com>
  - 200263644 Replace HAL paths with HIDL (B/78915061): In URLs, change... by Android Partner Docs <noreply@android.com>
  - 200159329 Hide star ratings to fix layout. by Android Partner Docs <noreply@android.com>
  - 200062417 Devsite localized content from translation request 915905. by Android Partner Docs <noreply@android.com>
  - 200062406 Devsite localized content from translation request 932855. by Android Partner Docs <noreply@android.com>
  - 200062403 Devsite localized content from translation request 936857. by Android Partner Docs <noreply@android.com>
  - 200062395 Devsite localized content from translation request 924210. by Android Partner Docs <noreply@android.com>
  - 199872446 add a 1 to the end of researchers twitter handle by Android Partner Docs <noreply@android.com>
  - 199852050 Change Nexus > Pixel/ Nexus by Danielle Roberts <daroberts@google.com>
  - 199829857 Devsite localized content from translation request 932861. by Android Partner Docs <noreply@android.com>
  - 199829853 Devsite localized content from translation request 931901. by Android Partner Docs <noreply@android.com>
  - 199829847 Devsite localized content from translation request 928418. by Android Partner Docs <noreply@android.com>
  - 199826612 Add stayres@ to bulletin localization file by Danielle Roberts <daroberts@google.com>

PiperOrigin-RevId: 202498507
Change-Id: I3cf1b347a519ecff7960a159cdc57b35306435cf

1 files changed, 75 insertions, 20 deletions

diff --git a/en/devices/graphics/implement-vulkan.html b/en/devices/graphics/implement-vulkan.html
index b2a5c283..509ce7fd 100644
--- a/en/devices/graphics/implement-vulkan.html
+++ b/en/devices/graphics/implement-vulkan.html
@@ -66,13 +66,12 @@ the driver.</p>
 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
+functions in the loader, which 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 (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>
+skips the trampoline and dispatch.</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
@@ -102,12 +101,12 @@ driver, though that driver can support multiple physical devices. The
 <code>vkGetInstanceProcAddr</code> functions. The loader can find all other
 <code>VkInstance</code>, <code>VkPhysicalDevice</code>, and
 <code>vkGetDeviceProcAddr</code> functions by calling
-<code>vkGetInstanceProcAddr</code>.</p>
+the <code>hw_device_t</code>'s <code>vkGetInstanceProcAddr</code>.</p>
 
 <h2 id=layer_discover>Layer discovery and loading</h2>
 <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,
+driver. Android does not include layers on the system image; however,
 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
@@ -170,23 +169,48 @@ and will not be exposed to applications.</p>
 <h3 id=gralloc_usage_flags>Gralloc usage flags</h3>
 <p>Implementations may need swapchain buffers to be allocated with
 implementation-defined private gralloc usage flags. When creating a swapchain,
-the platform asks the driver to translate the requested format and image usage
+Android 8.0 asks the driver to translate the requested format and image usage
 flags into gralloc usage flags by calling:</p>
 
 <pre class="devsite-click-to-copy">
+typedef enum VkSwapchainImageUsageFlagBitsANDROID {
+    VK_SWAPCHAIN_IMAGE_USAGE_SHARED_BIT_ANDROID = 0x00000001,
+    VK_SWAPCHAIN_IMAGE_USAGE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
+} VkSwapchainImageUsageFlagBitsANDROID;
+typedef VkFlags VkSwapchainImageUsageFlagsANDROID;
+
+VkResult VKAPI vkGetSwapchainGrallocUsage2ANDROID(
+    VkDevice                          device,
+    VkFormat                          format,
+    VkImageUsageFlags                 imageUsage,
+    VkSwapchainImageUsageFlagsANDROID swapchainUsage,
+    uint64_t*                         grallocConsumerUsage,
+    uint64_t*                         grallocProducerUsage
+);
+</pre>
+
+<p>The <code>format</code> and <code>imageUsage</code> parameters are taken from
+the <code>VkSwapchainCreateInfoKHR</code> structure. The driver should fill
+<code>*grallocConsumerUsage</code> and <code>*grallocProducerUsage</code> with
+the gralloc usage flags required for the format
+and usage. The usage returned by the driver will be combined with the usage flags
+requested by the swapchain consumer when allocating buffers.</p>
+
+<p>An earlier version of this function is called by Android 7.x. In Android 8.0
+it is deprecated but will still be called if
+<code>vkGetSwapchainGrallocUsage2ANDROID</code> isn't provided by the driver:
+
+<pre class="devsite-click-to-copy">
 VkResult VKAPI vkGetSwapchainGrallocUsageANDROID(
     VkDevice            device,
     VkFormat            format,
     VkImageUsageFlags   imageUsage,
     int*                grallocUsage
 );
-</pre>
+<pre>
 
-<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>
+<p>This earlier version does not support swapchain usage flags or extended gralloc
+usage flags.</p>
 
 <h3 id=gralloc_usage_flags>Gralloc-backed images</h3>
 
@@ -211,6 +235,15 @@ typedef struct {
     // Gralloc format and usage requested when the buffer was allocated.
     int                         format;
     int                         usage;
+    // Beginning in Android 8.0, the usage field above is deprecated and the
+    // usage2 struct below was added. The usage field is still filled in for
+    // compatibility with Android 7.0 drivers. Drivers for Android 8.0
+    // should prefer the usage2 struct, especially if the
+    // android.hardware.graphics.allocator HAL uses the extended usage bits.
+    struct {
+        uint64_t                consumer;
+        uint64_t                producer;
+    } usage2;
 } VkNativeBufferANDROID;
 </pre>
 
@@ -232,7 +265,22 @@ the following data:</p>
   .pQueueFamilyIndices = VkSwapChainCreateInfoWSI::pQueueFamilyIndices
 </pre>
 
-<h3 id=acquire_image>Aquiring images</h3>
+In Android 8.0 and later, the platform will provide a
+<code>VkSwapchainImageCreateInfo</code> extension structure in the
+<code>VkImageCreateInfo</code> chain provided to <code>vkCreateImage</code>
+when any swapchain image usage flags are required for the swapchain.
+The extension structure contains the swapchain image usage flags:
+
+<pre class="devsite-click-to-copy">
+typedef struct {
+    VkStructureType                        sType; // must be VK_STRUCTURE_TYPE_SWAPCHAIN_IMAGE_CREATE_INFO_ANDROID
+    const void*                            pNext;
+
+    VkSwapchainImageUsageFlagsANDROID      usage;
+} VkSwapchainImageCreateInfoANDROID;
+</pre>
+
+<h3 id=acquire_image>Acquiring images</h3>
 <p><code>vkAcquireImageANDROID</code> acquires ownership of a swapchain image
 and imports an externally-signalled native fence into both an existing
 <code>VkSemaphore</code> object and an existing <code>VkFence</code> object:</p>
@@ -267,34 +315,41 @@ it is as if the native fence was already signalled.</p>
 
 <h3 id=acquire_image>Releasing images</h3>
 <p><code>vkQueueSignalReleaseImageANDROID</code> prepares a swapchain image for
-external use, and creates a native fence and schedules it to be signalled when
-prior work on the queue has completed:</p>
+external use, and creates a native fence and schedules it to be signalled after
+the input semaphores have signaled:</p>
 
 <pre class="devsite-click-to-copy">
 VkResult VKAPI vkQueueSignalReleaseImageANDROID(
     VkQueue             queue,
+    uint32_t            waitSemaphoreCount,
+    const VkSemaphore*  pWaitSemaphores,
     VkImage             image,
     int*                pNativeFenceFd
 );
 </pre>
 
-<p>This API is called during <code>vkQueuePresentWSI</code> on the provided
+<p>This API is called during <code>vkQueuePresentKHR</code> on the provided
 queue. Effects are similar to <code>vkQueueSignalSemaphore</code>, except with a
-native fence instead of a semaphore. Unlike <code>vkQueueSignalSemaphore</code>,
+native fence instead of a semaphore. The native fence must not signal until the
+<code>waitSemaphoreCount</code> semaphores in <code>pWaitSemaphores</code> have
+signaled. Unlike <code>vkQueueSignalSemaphore</code>,
 however, this call creates and returns the synchronization object that will be
 signalled rather than having it provided as input. If the queue is already idle
 when this function is called, it is allowed (but not required) to set
 <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
 CPU-side data structures associated with a gralloc buffer for use by external
 image consumers. Preparing buffer contents for use by external consumers should
 have been done asynchronously as part of transitioning the image to
 <code>VK_IMAGE_LAYOUT_PRESENT_SRC_KHR</code>.</p>
 
+If the image was created with
+<code>VK_SWAPCHAIN_IMAGE_USAGE_SHARED_BIT_ANDROID</code>, then the driver must
+allow <code>vkQueueSignalReleaseImageANDROID</code> to be called repeatedly
+without intervening calls to <code>vkAcquireImageANDROID</code>.
+
 <h2 id=validation>Validation</h2>
 <p>OEMs can test their Vulkan implementation using CTS, which includes
 <a href="/devices/graphics/cts-integration.html">drawElements