7 files changed, 121 insertions, 34 deletions
diff --git a/en/devices/architecture/dto/implement.html b/en/devices/architecture/dto/implement.html
index 5d10a92c..52906fc8 100644
--- a/en/devices/architecture/dto/implement.html
+++ b/en/devices/architecture/dto/implement.html
@@ -108,8 +108,8 @@ top of the main DT blob. Typically, 8 MB is more than enough and allows room to
 grow in the future if required.</p>
 
 <p>For devices that support
-<a href="https://source.android.com/devices/tech/ota/ab_updates.html">seamless
-(A/B) updates</a>, A/B the main DT and overlay DT partitions:</p>
+<a href="/devices/tech/ota/ab_updates.html">seamless (A/B) updates</a>, A/B the
+main DT and overlay DT partitions:</p>
 
 <div style="width:75%">
 <div class="attempt-left">
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>
diff --git a/en/devices/architecture/index.html b/en/devices/architecture/index.html
index 38f494a7..592198ff 100644
--- a/en/devices/architecture/index.html
+++ b/en/devices/architecture/index.html
@@ -75,7 +75,7 @@ primarily for system functionality and do not affect driver development.</p>
 <p>You can use any version of the kernel as long as it supports the required
 features (such as the binder driver). However, we recommend using the latest
 version of the Android kernel. For details, see
-<a href="/source/building-kernels.html">Building Kernels</a>.</p>
+<a href="/setup/building-kernels.html">Building Kernels</a>.</p>
 
   </body>
 </html>
diff --git a/en/devices/architecture/kernel/modular-kernels.html b/en/devices/architecture/kernel/modular-kernels.html
index 5c4b54c3..70debebe 100644
--- a/en/devices/architecture/kernel/modular-kernels.html
+++ b/en/devices/architecture/kernel/modular-kernels.html
@@ -181,8 +181,8 @@ mounted in Recovery mode.</li>
 partitions are <strong>not</strong> mounted early. In Android 8.0, to make
 module loading from these partitions possible, provisions have been made to
 mount partitions early for both
-<a href="https://source.android.com/devices/tech/ota/ab_updates">non-A/B and A/B
-devices</a>. This also ensures the partitions are mounted in both Android and
+<a href="/devices/tech/ota/ab_updates">non-A/B and A/B devices</a>. This also
+ensures the partitions are mounted in both Android and
 Charger modes.</p>
 
 <h3 id="android-build-system-support">Android build system support</h3>
@@ -604,9 +604,9 @@ see <a href="/devices/architecture/dto/partitions.html">DTB/DTBO Partitions</a>.
 The assumption is that bootloader already knows where and how to load the
 SoC–specific DTB.</li>
 <li>Overlay DT partition should be
-<a href="https://source.android.com/devices/tech/ota/ab_updates.html">A/B-ed</a>
-for A/B devices. For these devices, the recovery kernel is the same as Android
-kernel, but the partition must be A/B-ed as it can be updated via OTA.</li>
+<a href="/devices/tech/ota/ab_updates.html">A/B-ed</a> for A/B devices. For these
+devices, the recovery kernel is the same as Android kernel, but the partition
+must be A/B-ed as it can be updated via OTA.</li>
 <li>Partition size is board–specific.
  <ul>
  <li>The DT overlay partition size depends on the device and the amount of
diff --git a/en/devices/architecture/kernel/network_tests.html b/en/devices/architecture/kernel/network_tests.html
index bc437ad2..39329d2b 100644
--- a/en/devices/architecture/kernel/network_tests.html
+++ b/en/devices/architecture/kernel/network_tests.html
@@ -45,9 +45,9 @@ Suite (CTS) tests.</p>
 
 <h2 id=using>Using the tests</h2> <p>The tests use <a
 href="http://user-mode-linux.sourceforge.net/">User-Mode Linux</a> to boot the
-kernel as a process on a Linux host machine. See <a
-href="https://source.android.com/source/initializing.html">Establishing a Build
-Environment</a> for suitable operating system versions. The unit test framework
+kernel as a process on a Linux host machine. See
+<a href="/setup/initializing.html">Establishing a Build Environment</a> for
+suitable operating system versions. The unit test framework
 boots the kernel with an appropriate disk image and runs the tests from the
 host file system. The tests are written in Python 2.x and use TAP interfaces to
 exercise kernel behaviour and the socket API.</p>