1 <html devsite> 2 <head> 3 <title>Hardware Abstraction Layer (HAL)</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>A HAL defines a standard interface for hardware vendors to implement, 27 which enables Android to be agnostic about lower-level driver implementations. 28 Using a HAL allows you to implement functionality without affecting or modifying 29 the higher level system. HAL implementations are packaged into modules and 30 loaded by the Android system at the appropriate time.</p> 31 32 <img src="../images/ape_fwk_hal.png"> 33 34 <p class="img-caption"><strong>Figure 1.</strong> HAL components</p> 35 36 <p>You must implement the corresponding HAL (and driver) for the specific 37 hardware your product provides. HAL implementations are typically built into 38 shared library modules (<code>.so</code> files), but as Android does not mandate 39 a standard interaction between a HAL implementation and device drivers, you can 40 do what is best for your situation. However, to enable the Android system to 41 correctly interact with your hardware, you <strong>must</strong> abide by the 42 contract defined in each hardware-specific HAL interface.</p> 43 44 <p>To guarantee that HALs have a predictable structure, each hardware-specific 45 HAL interface has properties defined in 46 <code>hardware/libhardware/include/hardware/hardware.h</code>. This interface 47 allows the Android system to load correct versions of your HAL modules in a 48 consistent way. A HAL interface consists of two components: modules and devices. 49 </p> 50 51 <h2 id="hal-module">HAL modules</h2> 52 <p>A module represents your packaged HAL implementation, which is stored as a 53 shared library (<code>.so file</code>). The 54 <code>hardware/libhardware/include/hardware/hardware.h</code> header file 55 defines a struct (<code>hw_module_t</code>) that represents a module and 56 contains metadata such as the version, name, and author of the module. Android 57 uses this metadata to find and load the HAL module correctly.</p> 58 59 <p>In addition, the <code>hw_module_t</code> struct contains a pointer to 60 another struct, <code>hw_module_methods_t</code>, that contains a pointer to 61 an open function for the module. This open function is used to initiate 62 communication with the hardware for which the HAL is serving as an abstraction. 63 Each hardware-specific HAL usually extends the generic <code>hw_module_t</code> 64 struct with additional information for that specific piece of hardware. For 65 example, in the camera HAL, the <code>camera_module_t</code> struct contains a 66 <code>hw_module_t</code> struct along with other camera-specific function 67 pointers:</p> 68 69 <pre class="devsite-click-to-copy"> 70 typedef struct camera_module { 71 hw_module_t common; 72 int (*get_number_of_cameras)(void); 73 int (*get_camera_info)(int camera_id, struct camera_info *info); 74 } camera_module_t; 75 </pre> 76 77 <p>When you implement a HAL and create the module struct, you must name it 78 <code>HAL_MODULE_INFO_SYM</code>. Example from the Nexus 9 audio HAL:</p> 79 80 <pre class="devsite-click-to-copy"> 81 struct audio_module HAL_MODULE_INFO_SYM = { 82 .common = { 83 .tag = HARDWARE_MODULE_TAG, 84 .module_api_version = AUDIO_MODULE_API_VERSION_0_1, 85 .hal_api_version = HARDWARE_HAL_API_VERSION, 86 .id = AUDIO_HARDWARE_MODULE_ID, 87 .name = "NVIDIA Tegra Audio HAL", 88 .author = "The Android Open Source Project", 89 .methods = &hal_module_methods, 90 }, 91 }; 92 </pre> 93 94 <h2 id="hal-device">HAL devices</h2> 95 <p>A device abstracts the hardware of your product. For example, an audio 96 module can contain a primary audio device, a USB audio device, or a Bluetooth 97 A2DP audio device.</p> 98 99 <p>A device is represented by the <code>hw_device_t</code> struct. Similar to a 100 module, each type of device defines a detailed version of the generic 101 <code>hw_device_t</code> that contains function pointers for specific features 102 of the hardware. For example, the <code>audio_hw_device_t</code> struct type 103 contains function pointers to audio device operations:</p> 104 105 <pre class="devsite-click-to-copy"> 106 struct audio_hw_device { 107 struct hw_device_t common; 108 109 /** 110 * used by audio flinger to enumerate what devices are supported by 111 * each audio_hw_device implementation. 112 * 113 * Return value is a bitmask of 1 or more values of audio_devices_t 114 */ 115 uint32_t (*get_supported_devices)(const struct audio_hw_device *dev); 116 ... 117 }; 118 typedef struct audio_hw_device audio_hw_device_t; 119 </pre> 120 121 <p>In addition to these standard properties, each hardware-specific HAL 122 interface can define more of its own features and requirements. For details, 123 see the <a href="/reference/hal/">HAL reference documentation</a> as well as 124 the individual instructions for each HAL.</p> 125 126 <h2 id="hal-building">Building HAL modules</h2> 127 <p>HAL implementations are built into modules (<code>.so</code>) files and are 128 dynamically linked by Android when appropriate. You can build your modules by 129 creating <code>Android.mk</code> files for each of your HAL implementations 130 and pointing to your source files. In general, your shared libraries must be 131 named in a specific format so they can be found and loaded properly. The naming 132 scheme varies slightly from module to module, but follows the general pattern 133 of: <code><module_type>.<device_name></code>. 134 </p> 135 136 <p>For details on setting up the build for each HAL, see the HAL-specific 137 documentation through the Porting section of this website.</p> 138 139 </body> 140 </html> 141
