Docs: Changes to source.android.com

  - 192190878 Update build numbers for Apr 2018 backpocket releases by Android Partner Docs <noreply@android.com>
  - 192180981 Fix hidl-cpp Nfc example to compile. by Android Partner Docs <noreply@android.com>
  - 192149941 Fix link to user guide, add link to dir, add section header by Clay Murphy <claym@google.com>
  - 192144867 Fix lines exceeding 80 character limit by Android Partner Docs <noreply@android.com>
  - 192143959 Devsite localized content from translation request f1daaa... by Android Partner Docs <noreply@android.com>
  - 192143763 Devsite localized content from translation request ea6294... by Android Partner Docs <noreply@android.com>
  - 192143652 Devsite localized content from translation request 055318... by Android Partner Docs <noreply@android.com>
  - 192143640 Devsite localized content from translation request d8e019... by Android Partner Docs <noreply@android.com>
  - 192139612 Fix link to moved external HiKey960_Schematics.pdf by Clay Murphy <claym@google.com>
  - 191951035 Remove ccache advice we don't believe. by Android Partner Docs <noreply@android.com>
  - 191909962 Typo in closing tag. <ol> to </ol> by Android Partner Docs <noreply@android.com>
  - 191907769 Update hikey960 to use vendor partition by Android Partner Docs <noreply@android.com>
  - 191821197 Amending additional steps and requirements on /vendor/etc... by Android Partner Docs <noreply@android.com>
  - 191808945 Add code tags by Android Partner Docs <noreply@android.com>
  - 191783990 Update typing for plural permissions following b/77605085 by Christina Nguyen <cqn@google.com>
  - 191744609 Change headings from title case to sentence case in /setup. by Android Partner Docs <noreply@android.com>
  - 191666381 Update File DAC configuration on using an OEM-specific AID by Christina Nguyen <cqn@google.com>
  - 191644853 Update AOSP links in April bulletins by Danielle Roberts <daroberts@google.com>
  - 191606759 Devsite localized content from translation request ab2ae5... by Android Partner Docs <noreply@android.com>
  - 191604399 Remove duplicate entry (already in Android bulletin) by Android Partner Docs <noreply@android.com>
  - 191463374 Devsite localized content from translation request 177e53... by Android Partner Docs <noreply@android.com>
  - 191451679 Add more information on boottime optimization by Android Partner Docs <noreply@android.com>
  - 191440990 Devsite localized content from translation request 1028aa... by Android Partner Docs <noreply@android.com>
  - 191438500 Update OWNERS files with new team members by Danielle Roberts <daroberts@google.com>
  - 191438471 Fix incorrect CVE number by Android Partner Docs <noreply@android.com>
  - 191365978 Update build numbers for Apr 2018 releases by Android Partner Docs <noreply@android.com>
  - 191337429 No need to download Mali binary blob anymore by Android Partner Docs <noreply@android.com>
  - 191317352 Fixed mixup in ARF name (Access File Rule -> Access Rule ... by Christina Nguyen <cqn@google.com>
  - 191315249 Fix dates by Clay Murphy <claym@google.com>
  - 191313037 Add second details ref, remove spacing other artifacts by Clay Murphy <claym@google.com>
  - 191308126 Add April 2018 security bulletins and acknowledgements by Clay Murphy <claym@google.com>
  - 191302158 Update February Pixel bulletin to move CVE-2017-15817 as ... by Android Partner Docs <noreply@android.com>
  - 191302132 Update February Android bulletin to move CVE-2017-15817 a... by Android Partner Docs <noreply@android.com>
  - 191294135 Devsite localized content from translation request 975929... by Android Partner Docs <noreply@android.com>
  - 191294129 Devsite localized content from translation request 2671e0... by Android Partner Docs <noreply@android.com>
  - 191294124 Devsite localized content from translation request da4c33... by Android Partner Docs <noreply@android.com>
  - 191294045 Devsite localized content from translation request 0c8eb6... by Android Partner Docs <noreply@android.com>
  - 191294039 Devsite localized content from translation request dcb545... by Android Partner Docs <noreply@android.com>
  - 191294037 Devsite localized content from translation request 32f608... by Android Partner Docs <noreply@android.com>
  - 191132422 Adding new vts Test Framework with three new pages and mu... by Heidi von Markham <hvm@google.com>
  - 191132198 Clarify that the OTA updates are "system" updates on the ... by Christina Nguyen <cqn@google.com>
  - 191083408 FooCallback should be extending IFooCallback.Stub, not IF... by Android Partner Docs <noreply@android.com>
  - 190951580 Remove message soliciting external contributions by Clay Murphy <claym@google.com>
  - 190817491 Updating using multiple dt overlays by Heidi von Markham <hvm@google.com>
  - 190786806 hikey: Switch to compressed kernel images by Android Partner Docs <noreply@android.com>
  - 190699917 Add YIR2017 to updates and resources page by Danielle Roberts <daroberts@google.com>
  - 190684574 Reorg of Setup to include directories, fixing old/bad/non... by Heidi von Markham <hvm@google.com>
  - 190661679 Added missing change log to CDD 5.1. by Android Partner Docs <noreply@android.com>
  - 190650880 Devsite localized content from translation request 91b16e... by Android Partner Docs <noreply@android.com>
  - 190650867 Devsite localized content from translation request 2a06e8... by Android Partner Docs <noreply@android.com>
  - 190650721 Devsite localized content from translation request d34273... by Android Partner Docs <noreply@android.com>
  - 190650712 Devsite localized content from translation request 850bf6... by Android Partner Docs <noreply@android.com>
  - 190650708 Devsite localized content from translation request 7cfb03... by Android Partner Docs <noreply@android.com>
  - 190643444 Adding details on structured interfaces by Heidi von Markham <hvm@google.com>

PiperOrigin-RevId: 192190878
Change-Id: If9d3a38dd1075636c0a61651cbd73e8acc903146

4 files changed, 60 insertions, 6 deletions

diff --git a/en/devices/architecture/dto/multiple.html b/en/devices/architecture/dto/multiple.html
index 52f47a46..f431a9d7 100644
--- a/en/devices/architecture/dto/multiple.html
+++ b/en/devices/architecture/dto/multiple.html
@@ -43,12 +43,18 @@ DTs.</figcaption>
 <p>The bootloader should be able to:</p>
 
 <ul>
-<li>read the SoC ID and select the main DT correspondingly, and</li>
-<li>read the board ID and select the overlay DT accordingly.</li>
+<li>Read the SoC ID and select the corresponding main device tree, and</li>
+<li>Read the board ID and select the set of overlay device trees accordingly.
+</li>
 </ul>
 
-<p>Only one main DT and one overlay DT are selected for use at runtime, and the
-selected pair must be compatible.</p>
+<p>Only one main DT should be selected for use at runtime. Multiple overlay DTs
+may be selected but they must be compatible with the chosen main DT. Using
+multiple overlays can help avoid storing one overlay per board within the DTBO
+partition and enable the bootloader to determine the subset of required overlays
+based on the board ID (or possibly by probing the peripherals). For
+example, Board A may need the devices added by the overlays 1, 3, and 5 while
+Board B may need the devices added by the overlays 1, 4, and 5.</p>
 
 <h2 id=partition>Partitioning</h2>
 <p>To partition, determine a bootloader runtime-accessible and trusted location
diff --git a/en/devices/architecture/hidl-cpp/index.html b/en/devices/architecture/hidl-cpp/index.html
index 7d8466cb..28c4aa0a 100644
--- a/en/devices/architecture/hidl-cpp/index.html
+++ b/en/devices/architecture/hidl-cpp/index.html
@@ -117,7 +117,7 @@ a binderized service. Example daemon code (for pure binderized service):</p>
 
 <pre class="prettyprint">
 int main(int /* argc */, char* /* argv */ []) {
-    Nfc nfc = new Nfc();
+    sp<INfc> nfc = new Nfc();
     const status_t status = nfc-&gt;registerAsService();
     if (status != ::android::OK) {
         return 1; // or handle error
diff --git a/en/devices/architecture/hidl-java/index.html b/en/devices/architecture/hidl-java/index.html
index 3b94247e..c4218160 100644
--- a/en/devices/architecture/hidl-java/index.html
+++ b/en/devices/architecture/hidl-java/index.html
@@ -136,7 +136,7 @@ to run the service is:</p>
 import android.hardware.foo.V1_0.IFoo;
 import android.hardware.foo.V1_0.IFooCallback.Stub;
 ....
-class FooCallback extends IFoo.Stub {
+class FooCallback extends IFooCallback.Stub {
     // implement methods
 }
 ....
diff --git a/en/devices/architecture/hidl/versioning.html b/en/devices/architecture/hidl/versioning.html
index 13bce259..52552f0c 100644
--- a/en/devices/architecture/hidl/versioning.html
+++ b/en/devices/architecture/hidl/versioning.html
@@ -112,6 +112,54 @@ types from the older version of the package, and inheritance of a subset of
 old-package interfaces.</li>
 </ul>
 
+<h2 id=structuring>Structuring interfaces</h2>
+
+<p>For a well structured interface, adding new types of functionality that
+are not part of the original design should require a modification to the HIDL
+interface. Conversely, if you can or expect to make a change on both sides of
+the interface that introduces new functionality without changing the interface
+itself, then the interface is not structured.</p>
+
+<p>Treble supports separately-compiled vendor and system components in which the
+<code>vendor.img</code> on a device and the <code>system.img</code> can be
+compiled separately. All interactions between <code>vendor.img</code> and
+<code>system.img</code> must be explicitly and thoroughly defined so they can
+continue to work for many years. This includes many API surfaces, but a major
+surface is the IPC mechanism HIDL uses for interprocess communication on the
+<code>system.img</code>/<code>vendor.img</code> boundary.</p>
+
+<h3 id="structuring-requirements">Requirements</h3>
+<p>All data passed through HIDL must be explicitly defined. To ensure an
+implementation and client can continue to work together even when compiled
+separately or developed on independently, data must adhere to the following
+requirements:</p>
+
+<ul>
+<li>Can be described in HIDL directly (using structs enums, etc.) with
+semantic names and meaning.</li>
+<li>Can be described by a public standard such as ISO/IEC 7816.</li>
+<li>Can be described by a hardware standard or physical layout of hardware.</li>
+<li>Can be opaque data (such as public keys, ids, etc.) if necessary.</li>
+</ul>
+
+<p>If opague data is used, it must be read only by one side of the HIDL
+interface. For example, if <code>vendor.img</code> code gives a component on the
+<code>system.img</code> a string message or <code>vec&lt;uint8_t&gt;</code>
+data, that data cannot be parsed by the <code>system.img</code> itself; it can
+only be passed back to <code>vendor.img</code> to interpret. <strong>When
+passing a value from <code>vendor.img</code> to vendor code on
+<code>system.img</code> or to another device, the format of the data and how it
+is to be interpreted must be exactly described and is still part of the
+interface</strong>.</p>
+
+<h3 id="structuring-guidelines">Guidelines</h3>
+
+<p>You should be able to write an implementation or client of a HAL using only
+the .hal files (i.e. you should not need to look at the Android source or public
+standards). We recommend specifying the exact required behavior. Statements such
+as "an implementation may do A or B" encourage implementations to become
+intertwined with the clients they are developed with.</p>
+
 <h2 id=code-layout>HIDL code layout</h2>
 <p>HIDL includes core and vendor packages.</p>