Docs: Changes to source.android.com

  - 182815898 Add persistent link to China mirror on home page by Clay Murphy <claym@google.com>
  - 182789083 Devsite localized content from translation request 46370c... by Android Partner Docs <noreply@android.com>
  - 182789077 Devsite localized content from translation request 6133ed... by Android Partner Docs <noreply@android.com>
  - 182597042 Updating English for translation fixes by Heidi von Markham <hvm@google.com>
  - 182578621 Add verification HTML page for Search Console to try and ... by Christina Nguyen <cqn@google.com>
  - 182560649 Devsite localized content from translation request ac6bc4... by Android Partner Docs <noreply@android.com>
  - 182560639 Devsite localized content from translation request 4b21f6... by Android Partner Docs <noreply@android.com>
  - 182560630 Devsite localized content from translation request 907a58... by Android Partner Docs <noreply@android.com>
  - 182559954 Devsite localized content from translation request 277f34... by Android Partner Docs <noreply@android.com>
  - 182559754 Devsite localized content from translation request 9f4f3f... by Android Partner Docs <noreply@android.com>
  - 182559744 Devsite localized content from translation request 34815b... by Android Partner Docs <noreply@android.com>

PiperOrigin-RevId: 182815898
Change-Id: I1fe7673e8fe6dd116e3f2ac0e6283a953e22510b

3 files changed, 58 insertions, 47 deletions

diff --git a/en/devices/architecture/hidl/fmq.html b/en/devices/architecture/hidl/fmq.html
index db4055b5..1573b071 100644
--- a/en/devices/architecture/hidl/fmq.html
+++ b/en/devices/architecture/hidl/fmq.html
@@ -35,7 +35,7 @@ message queue.</p>
 <p class="caution">Fast Message Queues are supported only in C++.</p>
 
 <h2 id=flavors>MessageQueue types</h2>
-<p>Android supports two queue types:</p>
+<p>Android supports two queue types (known as <em>flavors</em>):</p>
 <ul>
 <li><em>Unsynchronized</em> queues are allowed to overflow, and can have many
 readers; each reader must read data in time or lose it.
@@ -136,14 +136,15 @@ for the queue.</li>
 <code>MQDescriptor</code> object obtained from the first side. The
 <code>MQDescriptor</code> object is sent over a HIDL RPC call to the process
 that will hold the second end of the message queue. The
-<code>MQDescriptor</code> contains information about the queue:</p>
+<code>MQDescriptor</code> contains information about the queue, including:</p>
 
 <ul>
 <li>Information to map the buffer and write pointer.</li>
-<li>If the queue is synchronized, information to map the read pointer.</li>
-<li>If the queue is blocking, information to map the event flag word.</li>
-<li>The object type is made into a template with the HIDL-defined type of queue
-elements and the flavor (synchronized or unsynchronized).</li>
+<li>Information to map the read pointer (if the queue is synchronized).</li>
+<li>Information to map the event flag word (if the queue is blocking).</li>
+<li>Object type (<code>&lt;T, flavor&gt;</code>), which includes the
+<a href="/devices/architecture/hidl-cpp/types.html">HIDL-defined type</a> of
+queue elements and the queue flavor (synchronized or unsynchronized).</li>
 </ul>
 
 <p>The <code>MQDescriptor</code> object can be used to construct a
@@ -172,8 +173,15 @@ of blocking read/write calls:</p>
 <li><em>Short form</em>, with three parameters (data pointer, number of items,
 timeout). Supports blocking on individual read/write operations on a single
 queue. When using this form, the queue will handle the event flag and bitmasks
-internally, and the first message queue object must be initialized with a
-second parameter of <code>true</code>.</li>
+internally, and the <a href="#first-object">first message queue object</a> must
+be initialized with a second parameter of <code>true</code>. For example:
+<pre>
+// For an unsynchronized FMQ that supports blocking
+mFmqUnsynchronizedBlocking =
+  new (std::nothrow) MessageQueue&lt;uint16_t, kUnsynchronizedWrite&gt;
+      (kNumElementsInQueue, true /* enable blocking operations */);
+<pre>
+</li>
 <li><em>Long form</em>, with six parameters (includes event flag and bitmasks).
 Supports using a shared <code>EventFlag</code> object between multiple queues
 and allows specifying the notification bit masks to be used. In this case, the
@@ -285,12 +293,12 @@ notification bits. Similarly, <code>writeblocking()</code> will fail if
 <p>To wait on multiple queues at once, use an <code>EventFlag</code> object's
 <code>wait()</code> method to wait on a bitmask of notifications. The
 <code>wait()</code> method returns a status word with the bits that caused the
-wake up set. Using the information, the user can then check the corresponding
-queue to see whether it has enough space or data for the desired write or read
-operation and perform a nonblocking <code>read()</code>/<code>write()</code>
-followed by a call to the <code>EventFlag</code>'s <code>wake()</code> method if
-a notification is desired after the same. For a definition of the
-<code>EventFlag</code> abstraction, refer to
+wake up set. This information is then used to verify the corresponding queue has
+enough space or data for the desired write/read operation and perform a
+nonblocking <code>write()</code>/<code>read()</code>. To get a post operation
+notification, use another call to the <code>EventFlag</code>'s
+<code>wake()</code> method. For a definition of the <code>EventFlag</code>
+abstraction, refer to
 <a href="https://android.googlesource.com/platform/system/libfmq/+/master/include/fmq/EventFlag.h" class="external"><code>system/libfmq/include/fmq/EventFlag.h</code></a>.
 </p>
 
@@ -299,9 +307,9 @@ a notification is desired after the same. For a definition of the
 <code>read</code>/<code>write</code>/<code>readBlocking</code>/<code>writeBlocking()</code>
 APIs take a pointer to an input/output buffer as an argument and use
 <code>memcpy()</code> calls internally to copy data between the same and the
-FMQ ring buffer. To improve performance, Android O includes a set of APIs that
-provide direct pointer access into the ring buffer, eliminating the need to use
-<code>memcpy</code> calls.</p>
+FMQ ring buffer. To improve performance, Android 8.0 and higher include a set of
+APIs that provide direct pointer access into the ring buffer, eliminating the
+need to use <code>memcpy</code> calls.</p>
 
 <p>Use the following public APIs for zero copy FMQ operations:</p>
 
@@ -323,8 +331,9 @@ read/write is possible. If the read or write is possible the <code>memTx</code>
 struct is populated with base pointers that can be used for direct pointer
 access into the ring buffer shared memory.</li>
 <li>The <code>MemRegion</code> struct contains details about a block of memory,
-i.e. a base pointer and length in terms of <code>T</code>(where the FMQ is
-templatized to <code>T</code>).</li>
+including the base pointer (base address of the memory block) and the length in
+terms of <code>T</code> (length of the memory block in terms of the HIDL-defined
+type of the message queue).</li>
 <li>The <code>MemTransaction</code> struct contains two <code>MemRegion</code>
 structs, <code>first</code> and <code>second</code> as a read or write into
 the ring buffer may require a wrap around to the beginning of the queue. This
@@ -404,7 +413,7 @@ event flag pointer (using <code>getEventFlagWord()</code>) from a
 use that flag to create the necessary <code>EventFlag</code> object.</li>
 <li>Use the <code>MessageQueue</code> <code>getDesc()</code> method to get a
 descriptor object.</li>
-<li>In the <code>.hal</code> file, give a method a parameter of type
+<li>In the <code>.hal</code> file, give the method a parameter of type
 <code>fmq_sync<T></code> or <code>fmq_unsync<T></code> where <code>T</code> is a
 suitable HIDL-defined type. Use this to send the object returned by
 <code>getDesc()</code> to the receiving process.</li>
diff --git a/en/devices/architecture/hidl/types.html b/en/devices/architecture/hidl/types.html
index 1f36262d..943d355e 100644
--- a/en/devices/architecture/hidl/types.html
+++ b/en/devices/architecture/hidl/types.html
@@ -95,14 +95,14 @@ can be attached to the same item.</p>
 <h2 id=forward>Forward declarations</h2>
 <p>In HIDL, structs may not be forward-declared, making user-defined,
 self-referential data types impossible (e.g., you cannot describe a linked list
-or a tree in HIDL). Most existing (pre-Android O) HALs have limited use of
+or a tree in HIDL). Most existing (pre-Android 8.x) HALs have limited use of
 forward declarations, which can be removed by rearranging data structure
 declarations.</p>
 
 <p>This restriction allows data structures to be copied by-value with a simple
 deep-copy, rather than keeping track of pointer values that may occur multiple
 times in a self-referential data structure. If the same data is passed twice,
-such as with two method parameters or <code>vec&lt;T&gt;</code>'s that point to
+such as with two method parameters or <code>vec&lt;T&gt;</code>s that point to
 the same data, two separate copies are made and delivered.</p>
 
 <h2 id=nested>Nested declarations</h2>
@@ -255,7 +255,7 @@ allocated <code>native_handle_t</code>.</p>
 <p>In earlier versions of Android, native handles were created using the same
 functions present in
 <a href="https://android.googlesource.com/platform/system/core/+/master/libcutils/native_handle.c">libcutils</a>.
-In Android O, these functions are now copied to the
+In Android 8.0 and higher, these functions are now copied to the
 <code>android::hardware::hidl</code> namespace or moved to the NDK. HIDL
 autogenerated code serializes and deserializes these functions automatically,
 without involvement from user-written code.</p>
@@ -266,18 +266,20 @@ without involvement from user-written code.</p>
 the ownership of the file descriptors contained in it is as follows:</p>
 
 <ul>
-<li>When passing a <code>hidl_handle</code> object as an argument, the caller
-retains ownership of the file descriptors contained in the
-<code>native_handle_t</code> it wraps, and must close them when it is done with
-them. Likewise, when returning a <code>hidl_handle</code> object (by passing it
-into a <code>_cb</code> function), the process returning it retains ownership of
-the file descriptors contained in the <code>native_handle_t</code> it wraps, and
-must close them when it is done with them.</li>
-<li>When receiving a <code>hidl_handle</code> object, the
-<strong>transport</strong> owns the file descriptors inside the
-<code>native_handle_t</code> it wraps; the receiver can use them as-is during
-the transaction callback, but must clone the native handle if it wants to keep
-using its file descriptors beyond the callback. The transport will automatically
+<li>The <strong>caller</strong> passing a <code>hidl_handle</code> object as an
+argument retains ownership of the file descriptors contained in the
+<code>native_handle_t</code> it wraps; the caller must close these file
+descriptors when it is done with them.</li>
+<li>The <strong>process</strong> returning a <code>hidl_handle</code>
+object (by passing it into a <code>_cb</code> function) retains ownership of the
+file descriptors contained in the <code>native_handle_t</code> wrapped by the
+object; the process must close these file descriptors when it is done with them.
+</li>
+<li>A <strong>transport</strong> that receives a <code>hidl_handle</code> has
+ownership of the file descriptors inside the <code>native_handle_t</code>
+wrapped by the object; the receiver can use these file descriptors as-is during
+the transaction callback, but must clone the native handle to use the file
+descriptors beyond the callback. The transport will automatically
 <code>close()</code> the file descriptors when the transaction is done.</li>
 </ul>
 
diff --git a/en/devices/architecture/hidl/versioning.html b/en/devices/architecture/hidl/versioning.html
index 20ea34b4..fbfd60fa 100644
--- a/en/devices/architecture/hidl/versioning.html
+++ b/en/devices/architecture/hidl/versioning.html
@@ -388,14 +388,14 @@ via <code>import android.hardware.foo@1.0;</code>).</li>
 </ul>
 
 <h2 id=types>types.hal</h2>
-<p>Every HIDL package contains a <code>types.hal</code> file with UDTs share
-among all interfaces participating in that package. HIDL types are always
-public; regardless of whether a UDT is declared in <code>types.hal</code> or
-within an interface declaration, these types are accessible outside of the scope
-where they are defined. <code>types.hal</code> is not meant to describe the
-public API of a package, but rather to host UDTs used by all interfaces within
-the package. Due to the nature of HIDL, all UDTs are a part of the interface.
-</p>
+<p>Every HIDL package contains a <code>types.hal</code> file containing UDTs
+that are shared among all interfaces participating in that package. HIDL types
+are always public; regardless of whether a UDT is declared in
+<code>types.hal</code> or within an interface declaration, these types are
+accessible outside of the scope where they are defined. <code>types.hal</code>
+is not meant to describe the public API of a package, but rather to host UDTs
+used by all interfaces within the package. Due to the nature of HIDL, all UDTs
+are a part of the interface.</p>
 
 <p><code>types.hal</code> consists of UDTs and <code>import</code> statements.
 Because <code>types.hal</code> is made available to every interface of the
@@ -584,13 +584,13 @@ redundant.</p>
 <code>fromFooToBar()</code> it inherits from <code>@1.0::IQuux</code>; it simply
 lists the new method it adds <code>fromBarToFoo()</code>. In HIDL, inherited
 methods may <strong>not</strong> be declared again in the child interfaces, so
-for <code>IQuux</code> it would not be an option to declare
-<code>fromFooToBar()</code> explicitly.</p>
+the <code>IQuux</code> interface cannot declare the <code>fromFooToBar()</code>
+method explicitly.</p>
 
 <aside class="key-point"><strong>Key Point:</strong> In HIDL, every inherited
 method from a base class must be explicitly implemented in the inheriting class.
-If a method implementation needs to fall back to that of the base, the fallback
-must be in the implementation.</aside>
+If a method implementation needs to fall back to the method implementation of
+the base class, the fallback must be in the implementation.</aside>
 
 <h3 id=conventions>Uprev conventions</h3>
 <p>Sometimes interface names must rename the extending interface. We recommend