Docs: Restore deleted contents
Bug: 19484165
Change-Id: I6d7e17a0a2eb2da80388ca63d89ad7e4e6fde223
diff --git a/src/devices/index.jd b/src/devices/index.jd
index e433f1c..a09d10c 100644
--- a/src/devices/index.jd
+++ b/src/devices/index.jd
@@ -1,4 +1,4 @@
-page.title=Android Interfaces
+page.title=Android Interfaces and Architecture
@jd:body
<!--
@@ -40,8 +40,6 @@
<a href="{@docRoot}compatibility/index.html">Compatibility</a>.
</p>
-<h2 id="Android system architecture">Android system architecture</h2>
-
<p>
Before porting Android to your hardware, take a moment to understand the Android
system architecture at a high level. Because your drivers and the HAL interact
@@ -53,7 +51,7 @@
<p class="img-caption"><strong>Figure 1.</strong> Android System Architecture</p>
-<h3 id="Application framework">Application framework</h3>
+<h2 id="Application framework">Application framework</h2>
<p>
The application framework is used most often by application developers. As a
hardware developer, you should be aware of developer APIs as many map directly
@@ -61,7 +59,7 @@
implementing drivers.
</p>
-<h3 id="Binder IPC">Binder IPC</h3>
+<h2 id="Binder IPC">Binder IPC</h2>
<p>
The Binder Inter-Process Communication (IPC) mechanism allows the application
framework to cross process boundaries and call into the Android system services
@@ -70,7 +68,7 @@
the developer and things appear to "just work."
</p>
-<h3 id="System services">System services</h3>
+<h2 id="System services">System services</h2>
<p>
Functionality exposed by application framework APIs communicates with system
services to access the underlying hardware. Services are modular, focused
@@ -80,11 +78,14 @@
in playing and recording media).
</p>
-<h3 id="Hardware Abstraction Layer">Hardware abstraction layer (HAL)</h3>
+<h2 id="Hardware Abstraction Layer">Hardware abstraction layer (HAL)</h2>
<p>
-The HAL is a standard interface that allows the Android system to call into the
-device driver layer while being agnostic about the lower-level implementations
-of drivers and hardware.
+The hardware abstraction layer (HAL) defines a standard interface for hardware
+vendors to implement and allows Android to be agnostic about lower-level driver
+implementations. The HAL allows you to implement functionality without
+affecting or modifying the higher level system. HAL implementations are
+packaged into modules (<code>.so</code>) file and loaded by the Android system
+at the appropriate time.
</p>
<img src="images/ape_fwk_hal.png">
@@ -102,7 +103,95 @@
by the contract defined in each hardware-specific HAL interface.
</p>
-<h3 id="Linux kernel">Linux Kernel</h3>
+<h3 id="structure">Standard HAL structure</h3>
+<p>
+ Each hardware-specific HAL interface has properties that are defined in
+ <code>hardware/libhardware/include/hardware/hardware.h</code>, which
+ guarantee that HALs have a predictable structure.
+ This interface allows the Android system to load the correct versions of your
+ HAL modules in a consistent way. There are two general components
+ that a HAL interface consists of: a module and a device.
+</p>
+<p>
+ A module represents your packaged HAL implementation, which is stored as a shared library (<code>.so file</code>). It contains
+ metadata such as the version, name, and author of the module, which helps Android find and load it correctly. The
+ <code>hardware/libhardware/include/hardware/hardware.h</code> header file defines a
+ struct, <code>hw_module_t</code>, that represents a module and contains information such as
+ the module version, author, and name.</p>
+
+ <p>In addition, the <code>hw_module_t</code> struct contains
+ a pointer to another struct, <code>hw_module_methods_t</code>, that contains a pointer to
+ an "open" function for the module. This open function is used to initate communication with
+ the hardware that the HAL is serving as an abstraction for. Each hardware-specific HAL usually
+ extends the generic <code>hw_module_t</code> struct with additional information
+ for that specific piece of hardware. For example in the camera HAL, the <code>camera_module_t</code> struct
+ contains a <code>hw_module_t</code> struct along with other camera-specific function pointers:
+</p>
+
+<pre>
+typedef struct camera_module {
+ hw_module_t common;
+ int (*get_number_of_cameras)(void);
+ int (*get_camera_info)(int camera_id, struct camera_info *info);
+} camera_module_t;
+</pre>
+
+<p>When you implement a HAL and create the module struct, you must name it
+ <code>HAL_MODULE_INFO_SYM</code>. For instance, here is an example from the Nexus 9 audio HAL:</p>
+<pre>
+struct audio_module HAL_MODULE_INFO_SYM = {
+ .common = {
+ .tag = HARDWARE_MODULE_TAG,
+ .module_api_version = AUDIO_MODULE_API_VERSION_0_1,
+ .hal_api_version = HARDWARE_HAL_API_VERSION,
+ .id = AUDIO_HARDWARE_MODULE_ID,
+ .name = "NVIDIA Tegra Audio HAL",
+ .author = "The Android Open Source Project",
+ .methods = &hal_module_methods,
+ },
+};
+</pre>
+<p>
+ A device abstracts the actual hardware of your product. For example, an audio module can contain
+ a primary audio device, a USB audio device, or a Bluetooth A2DP audio device. A device
+ is represented by the <code>hw_device_t</code> struct. Like a module, each type of device
+ defines a more-detailed version of the generic <code>hw_device_t</code> that contains
+ function pointers for specific features of the hardware. For example, the
+ <code>audio_hw_device_t</code> struct type contains function pointers to audio device operations:
+</p>
+
+<pre>
+struct audio_hw_device {
+ struct hw_device_t common;
+
+ /**
+ * used by audio flinger to enumerate what devices are supported by
+ * each audio_hw_device implementation.
+ *
+ * Return value is a bitmask of 1 or more values of audio_devices_t
+ */
+ uint32_t (*get_supported_devices)(const struct audio_hw_device *dev);
+ ...
+};
+typedef struct audio_hw_device audio_hw_device_t;
+</pre>
+
+<p>
+ In addition to these standard properties, each hardware-specific HAL interface can define more of its
+ own features and requirements. See the <a href="{@docRoot}devices/halref/index.html">HAL reference documentation</a>
+ as well as the individual instructions for each HAL for more information on how to implement a specific interface.
+</p>
+
+<h3 id="modules">HAL modules</h3>
+<p>HAL implementations are built into modules (<code>.so</code>) files and are dynamically linked by Android when appropriate.
+ You can build your modules by creating <code>Android.mk</code> files for each of your HAL implementations
+ and pointing to your source files. In general, your shared libraries must be named in a certain format, so that
+ they can be found and loaded properly. The naming scheme varies slightly from module to module, but they follow
+ the general pattern of: <code><module_type>.<device_name></code>.</p>
+
+ <p>For more information about setting up the build for each HAL, see its respective documentation.</p>
+
+<h2 id="Linux kernel">Linux kernel</h2>
<p>
Developing your device drivers is similar to developing a typical Linux device
driver. Android uses a version of the Linux kernel with a few special additions
@@ -115,4 +204,4 @@
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 on the latest Android kernel, see <a href="{@docRoot}source/building-kernels.html" >Building Kernels</a>.
-</p>
\ No newline at end of file
+</p>