Merge "Docs: Changes to source.android.com"android-o-mr1-iot-preview-6o-mr1-iot-preview-6

3 files changed, 110 insertions, 23 deletions

diff --git a/en/devices/architecture/hidl/binder-ipc.html b/en/devices/architecture/hidl/binder-ipc.html
index 811bc3b7..22c38a11 100644
--- a/en/devices/architecture/hidl/binder-ipc.html
+++ b/en/devices/architecture/hidl/binder-ipc.html
@@ -255,9 +255,8 @@ need renaming.</p>
 <p>To fulfill requirement 4, you must make changes in the way service names,
 service labels, and rules are handled.</p>
 
-<p>For details on SELinux, see
-<a href="https://source.android.com/security/selinux/">Security-Enhanced Linux
-in Android</a>. For details on SELinux in Android 8.0, see
+<p>For details on SELinux, see <a href="/security/selinux/">Security-Enhanced
+Linux in Android</a>. For details on SELinux in Android 8.0, see
 <a href="/security/selinux/images/SELinux_Treble.pdf">SELinux for Android
 8.0</a>.</p>
 
diff --git a/en/devices/architecture/hidl/fmq.html b/en/devices/architecture/hidl/fmq.html
index 13a79610..db4055b5 100644
--- a/en/devices/architecture/hidl/fmq.html
+++ b/en/devices/architecture/hidl/fmq.html
@@ -353,17 +353,17 @@ const MemRegion&amp; getSecondRegion(); // get a reference to the second MemRegi
 <pre class="prettyprint">
 MessageQueueSync::MemTransaction tx;
 if (mQueue->beginRead(dataLen, &amp;tx)) {
-auto first = tx.getFirstRegion();
-auto second = tx.getSecondRegion();
+    auto first = tx.getFirstRegion();
+    auto second = tx.getSecondRegion();
 
-foo(first.getAddress(), first.getLength()); // method that performs the data write
-foo(second.getAddress(), second.getLength()); // method that performs the data write
+    foo(first.getAddress(), first.getLength()); // method that performs the data write
+    foo(second.getAddress(), second.getLength()); // method that performs the data write
 
-if(commitWrite(dataLen) == false) {
-//report error
-}
+    if(commitWrite(dataLen) == false) {
+       // report error
+    }
 } else {
-//report error
+   // report error
 }
 </pre>
 
diff --git a/en/devices/architecture/hidl/interfaces.html b/en/devices/architecture/hidl/interfaces.html
index a044abde..6fc1cb1b 100644
--- a/en/devices/architecture/hidl/interfaces.html
+++ b/en/devices/architecture/hidl/interfaces.html
@@ -75,7 +75,7 @@ interface in the package.</p>
 
 <h2 id=interface-def>Interface definition</h2>
 <p>Aside from <code>types.hal</code>, every other <code>.hal</code> file defines
-an interface. For example, an interface is typically defined as follows:</p>
+an interface. An interface is typically defined as follows:</p>
 
 <pre class="prettyprint">
 interface IBar extends IFoo { // IFoo is another interface
@@ -101,7 +101,7 @@ include:</p>
 <li><code>interfaceDescriptor</code></li>
 <li><code>notifySyspropsChanged</code></li>
 <li><code>linkToDeath</code></li>
-<li><code>unlinkToDeath</code></li
+<li><code>unlinkToDeath</code></li>
 <li><code>setHALInstrumentation</code></li>
 <li><code>getDebugInfo</code></li>
 <li><code>debug</code></li>
@@ -136,13 +136,13 @@ For fully-qualified values, the following import cases are supported:</p>
 <li><strong>Whole-package imports</strong>. If the value is a package name and a
 version (syntax described below), then the entire package is imported into the
 importing entity.</li>
-<li><strong>Partial imports</strong>.
+<li><strong>Partial imports</strong>. If the value is:
 <ul>
-<li>If the value is an interface, the package's <code>types.hal</code> and that
-interface are imported into the importing entity.</li>
-<li>If the value is an UDT defined in <code>types.hal</code>, then only that UDT
-is imported into the importing entity (other types in <code>types.hal</code> are
-not imported).</li>
+<li>An interface, the package's <code>types.hal</code> and that interface are
+imported into the importing entity.</li>
+<li>A UDT defined in <code>types.hal</code>, then only that UDT is imported into
+the importing entity (other types in <code>types.hal</code> are not imported).
+</li>
 </ul>
 <li><strong>Types-only imports</strong>. If the value uses the syntax of a
 partial import described above, but with the keyword <code>types</code> instead
@@ -208,7 +208,7 @@ be registered under the base HAL name and version, and under the extension's
 Versions are expressed in two integers, <em>major</em>.<em>minor</em>.</p>
 <ul>
 <li><strong>Major</strong> versions are not backwards compatible. Incrementing
-the major version number resets the minor version to 0.</li>
+the major version number resets the minor version number to 0.</li>
 <li><strong>Minor</strong> versions are backwards compatible. Incrementing the
 minor number indicates the newer version is fully backward compatible with the
 previous version. New data structures and methods can be added, but no existing
@@ -219,10 +219,98 @@ data structures or method signatures may be changed.</li>
 can be present on a device simultaneously. While multiple minor versions can
 also be present on a device, as minor versions are backwards compatible no
 reason exists to support more than the latest minor version for each major
-version.</p>
-
-<p>For more details on versioning and vendor extensions, see
+version. For more details on versioning and vendor extensions, see
 <a href="/devices/architecture/hidl/versioning">HIDL Versioning</a>.</p>
 
+<h2 id="interface-layout-summary">Interface layout summary</h2>
+<p>This section summarizes how to manage a HIDL interface package (such as
+<code>hardware/interfaces</code>) and consolidates information presented
+throughout the HIDL section. Before reading, ensure you are familiar with
+<a href="/devices/architecture/hidl/versioning">HIDL Versioning</a>, the hashing
+concepts in <a href="/devices/architecture/hidl/hashing#hidl-gen">Hashing with
+hidl-gen</a>, the details of <a href="/devices/architecture/hidl/">working with
+HIDL in general</a>, and the following definitions:</p>
+
+<table>
+<thead>
+<tr>
+<th width="30%">Term</th>
+<th>Definition</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Application Binary Interface (ABI)</td>
+<td>Application programming interface + any binary linkages required.</td>
+</tr>
+<tr>
+<td>Fully-qualified name (fqName)</td>
+<td>Name to distinguish a hidl type. Example:
+<code>android.hardware.foo@1.0::IFoo</code>.</td>
+</tr>
+<tr>
+<td>Package</td>
+<td>Package containing a HIDL interface and types. Example:
+<code>android.hardware.foo@1.0</code>.</td>
+</tr>
+<tr>
+<td> Package root</td>
+<td>Root package that contains the HIDL interfaces. Example: the HIDL interface
+<code>android.hardware</code> is in the package root
+<code>android.hardware.foo@1.0</code>.</td>
+</tr>
+<tr>
+<td>Package root path</td>
+<td>Location in the Android source tree where a package root maps to.</td>
+</tr>
+</tbody>
+</table>
+
+<p>For more definitions, see HIDL
+<a href="/devices/architecture/hidl/#terms">Terminology</a>.
+</p>
+
+<h3 id="file-found">Every file can be found from the package root mapping and
+its fully-qualified name</h3>
+<p>Package roots are specified to <code>hidl-gen</code> as the argument
+<code>-r android.hardware:hardware/interfaces</code>. For example, if the
+package is <code>vendor.awesome.foo@1.0::IFoo</code> and <code>hidl-gen</code>
+is sent <code>-r vendor.awesome:some/device/independent/path/interfaces</code>,
+then the interface file should be located in
+<code>$ANDROID_BUILD_TOP/some/device/independent/path/interfaces/foo/1.0/IFoo.hal</code>.
+</p>
+<p>In practice, it is recommended for a vendor or OEM named <code>awesome</code>
+to put their standard interfaces in <code>vendor.awesome</code>. After a package
+path has been selected, it must not be changed as this is baked into the ABI of
+the interface.</p>
+
+<h3 id="package-path-mapping">Package path mapping should be unique</h3>
+<p>For example, if you have <code>-rsome.package:$PATH_A</code> and
+<code>-rsome.package:$PATH_B</code>, <code>$PATH_A</code> must be equal to
+<code>$PATH_B</code> for a consistent interface directory (this also makes
+<a href="/devices/architecture/hidl/versioning">versioning interfaces</a> much
+easier).</p>
+
+<h3 id="package-root-version">Package root must have a versioning file</h3>
+<p>If you create a package path such as
+<code>-r vendor.awesome:vendor/awesome/interfaces</code>, you should also
+create the file
+<code>$ANDROID_BUILD_TOP/vendor/awesome/interfaces/current.txt</code>, which
+should contain hashes of interfaces made using the <code>-Lhash</code> option in
+<code>hidl-gen</code> (this is discussed extensively in
+<a href="/devices/architecture/hidl/hashing#hidl-gen">Hashing with
+hidl-gen</a>).</p>
+
+<aside class="caution"><strong>Caution:</strong> Manage all changes carefully!
+The <a href="/devices/tech/vts/">Vendor Test Suite (VTS)</a> will fail if an
+interface is not frozen, and ABI-incompatible changes to an interface will cause
+framework-only OTAs to fail.</aside>
+
+<h3 id="interfaces-device-dependent">Interfaces go in device-independent
+locations</h3>
+<p>In practice, it is recommended to share interfaces between branches. This
+allows for maximum code re-usage and maximum testing of code across different
+devices and use cases.</p>
+
   </body>
 </html>