Docs: Changes to source.android.com

  - 176365996 Devsite localized content from translation request 36fc3b... by Android Partner Docs <noreply@android.com>
  - 176365994 Devsite localized content from translation request 29ecb2... by Android Partner Docs <noreply@android.com>
  - 176318336 Devsite localized content from translation request d25ba3... by Android Partner Docs <noreply@android.com>
  - 176195455 Add note to CTS section "GPS/GNSS" about port availability. by Christina Nguyen <cqn@google.com>
  - 176110625 Devsite localized content from translation request aec37a... by Android Partner Docs <noreply@android.com>
  - 176110530 Devsite localized content from translation request ac14a0... by Android Partner Docs <noreply@android.com>
  - 176110525 Devsite localized content from translation request 7d4488... by Android Partner Docs <noreply@android.com>
  - 176001918 Update displayed error message to reflect "what is". (Tho... by Billy Lamberta <blamb@google.com>
  - 175980378 Update Motorola link by Android Partner Docs <noreply@android.com>
  - 175972776 Devsite localized content from translation request 21d570... by Android Partner Docs <noreply@android.com>
  - 175925123 Publish localized security bulletins by Danielle Roberts <daroberts@google.com>
  - 175921366 Update CTS/CTS-Verifier downloads for CTS-Dec-2017 Releases by Billy Lamberta <blamb@google.com>
  - 175915069 Put CTS supported platforms in a more distinct call-out. by Christina Nguyen <cqn@google.com>
  - 175908691 Update FMQ doc for indentations by Android Partner Docs <noreply@android.com>
  - 175905935 Devsite localized content from translation request 266989... by Android Partner Docs <noreply@android.com>
  - 175905631 Devsite localized content from translation request 255121... by Android Partner Docs <noreply@android.com>
  - 175905617 Devsite localized content from translation request 7e5691... by Android Partner Docs <noreply@android.com>
  - 175874683 Rename links from /source/... to /setup/... by Billy Lamberta <blamb@google.com>
  - 175774898 Devsite localized content from translation request 23a854... by Android Partner Docs <noreply@android.com>
  - 175754894 Update continuous localization for Setup tab by Danielle Roberts <daroberts@google.com>
  - 175754691 Top-level _translation.yaml: Ignore /setup/ directory (fo... by Billy Lamberta <blamb@google.com>
  - 175744774 Updating ril images and text flow by Heidi von Markham <hvm@google.com>
  - 175733952 Rename top-level 'Source' tab to 'Setup' tab. by Billy Lamberta <blamb@google.com>
  - 175720207 Moving layout summary to interfaces page by Heidi von Markham <hvm@google.com>
  - 175706780 Devsite localized content from translation request 0dea26... by Android Partner Docs <noreply@android.com>
  - 175703999 Changing GCM to FCM and links by Heidi von Markham <hvm@google.com>
  - 175698764 Point the "Year in Review" link to the latest available r... by Android Partner Docs <noreply@android.com>
  - 175599600 Fix missing and unnecessary tags. by Christina Nguyen <cqn@google.com>
  - 175589733 Remove unused tag by Christina Nguyen <cqn@google.com>

PiperOrigin-RevId: 176365996
Change-Id: I3f5dcfd9b8c953b642b752c9c4e04313126eeee4

1 files changed, 100 insertions, 12 deletions

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>