1 page.title=The Hardware Abstraction Layer 2 @jd:body 3 4 <!-- 5 Copyright 2010 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 <div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25 </div> 26 27 <p> 28 The hardware abstraction layer (HAL) defines a standard interface for hardware vendors to 29 implement and allows Android to be agnostic about lower-level driver 30 implementations. The HAL allows you to implement functionality 31 without affecting or modifying the higher level system. HAL implementations 32 are packaged into modules (<code>.so</code>) file and loaded by the Android 33 system at the appropriate time. 34 <h2 id="structure"> 35 Standard HAL structure 36 </h2> 37 <p> 38 Each hardware-specific HAL interface has properties that are common to all HAL interfaces. These 39 properties are defined in <code>hardware/libhardware/include/hardware/hardware.h</code> and 40 guarantees that HALs have a predictable structure. 41 This interface allows the Android system to load the correct versions of your 42 HAL modules in a consistent way. There are two general components 43 that a HAL interface consists of: a module and a device. 44 </p> 45 <p> 46 A module represents your packaged HAL implementation, which is stored as a shared library (<code>.so file</code>). It contains 47 metadata such as the version, name, and author of the module, which helps Android find and load it correctly. The 48 <code>hardware/libhardware/include/hardware/hardware.h</code> header file defines a 49 struct, <code>hw_module_t</code>, that represents a module and contains information such as 50 the module version, author, and name.</p> 51 52 <p>In addition, the <code>hw_module_t</code> struct contains 53 a pointer to another struct, <code>hw_module_methods_t</code>, that contains a pointer to 54 an "open" function for the module. This open function is used to initate communication with 55 the hardware that the HAL is serving as an abstraction for. Each hardware-specific HAL usually 56 extends the generic <code>hw_module_t</code> struct with additional information 57 for that specific piece of hardware. For example in the camera HAL, the <code>camera_module_t</code> struct 58 contains a <code>hw_module_t</code> struct along with other camera-specific function pointers: 59 </p> 60 61 <pre> 62 typedef struct camera_module { 63 hw_module_t common; 64 int (*get_number_of_cameras)(void); 65 int (*get_camera_info)(int camera_id, struct camera_info *info); 66 } camera_module_t; 67 </pre> 68 69 <p>When you implement a HAL and create the module struct, you must name it 70 <code>HAL_MODULE_INFO_SYM</code>. For instance, here is an example from the Galaxy Nexus audio HAL:</p> 71 <pre> 72 struct audio_module HAL_MODULE_INFO_SYM = { 73 .common = { 74 .tag = HARDWARE_MODULE_TAG, 75 .module_api_version = AUDIO_MODULE_API_VERSION_0_1, 76 .hal_api_version = HARDWARE_HAL_API_VERSION, 77 .id = AUDIO_HARDWARE_MODULE_ID, 78 .name = "Tuna audio HW HAL", 79 .author = "The Android Open Source Project", 80 .methods = &hal_module_methods, 81 }, 82 }; 83 </pre> 84 <p> 85 A device abstracts the actual hardware of your product. For example, an audio module can contain 86 a primary audio device, a USB audio device, or a Bluetooth A2DP audio device. A device 87 is represented by the <code>hw_device_t</code> struct. Like a module, each type of device 88 defines a more-detailed version of the generic <code>hw_device_t</code> that contains 89 function pointers for specific features of the hardware. For example, the 90 <code>audio_hw_device_t</code> struct type contains function pointers to audio device operations: 91 </p> 92 93 <pre> 94 struct audio_hw_device { 95 struct hw_device_t common; 96 97 /** 98 * used by audio flinger to enumerate what devices are supported by 99 * each audio_hw_device implementation. 100 * 101 * Return value is a bitmask of 1 or more values of audio_devices_t 102 */ 103 uint32_t (*get_supported_devices)(const struct audio_hw_device *dev); 104 ... 105 }; 106 typedef struct audio_hw_device audio_hw_device_t; 107 </pre> 108 109 <p> 110 In addition to these standard properties, each hardware-specific HAL interface can define more of its 111 own features and requirements. See the <a href="{@docRoot}guide/reference/files.html">HAL reference documentation</a> 112 as well as the individual instructions for each HAL for more information on how to implement a specific interface. 113 </p> 114 115 <h2 id="modules">HAL modules</h2> 116 <p>HAL implementations are built into modules (<code>.so</code>) files and are dynamically linked by Android when appropriate. 117 You can build your modules by creating <code>Android.mk</code> files for each of your HAL implementations 118 and pointing to your source files. In general, your shared libraries must be named in a certain format, so that 119 they can be found and loaded properly. The naming scheme varies slightly from module to module, but they follow 120 the general pattern of: <code><module_type>.<device_name></code>.</p> 121 122 <p>For more information about setting up the build for each HAL, see its respective documentation.</p> 123 124 </p>
