1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_INCLUDE_HARDWARE_HARDWARE_H 18 #define ANDROID_INCLUDE_HARDWARE_HARDWARE_H 19 20 #include <stdint.h> 21 #include <sys/cdefs.h> 22 23 #ifndef _HW_DONT_INCLUDE_CORE_ 24 #include <cutils/native_handle.h> 25 #include <system/graphics.h> 26 #endif // _HW_DONT_INCLUDE_CORE_ 27 28 __BEGIN_DECLS 29 30 /* 31 * Value for the hw_module_t.tag field 32 */ 33 34 #define MAKE_TAG_CONSTANT(A,B,C,D) (((A) << 24) | ((B) << 16) | ((C) << 8) | (D)) 35 36 #define HARDWARE_MODULE_TAG MAKE_TAG_CONSTANT('H', 'W', 'M', 'T') 37 #define HARDWARE_DEVICE_TAG MAKE_TAG_CONSTANT('H', 'W', 'D', 'T') 38 39 #define HARDWARE_MAKE_API_VERSION(maj,min) \ 40 ((((maj) & 0xff) << 8) | ((min) & 0xff)) 41 42 #define HARDWARE_MAKE_API_VERSION_2(maj,min,hdr) \ 43 ((((maj) & 0xff) << 24) | (((min) & 0xff) << 16) | ((hdr) & 0xffff)) 44 #define HARDWARE_API_VERSION_2_MAJ_MIN_MASK 0xffff0000 45 #define HARDWARE_API_VERSION_2_HEADER_MASK 0x0000ffff 46 47 48 /* 49 * The current HAL API version. 50 * 51 * All module implementations must set the hw_module_t.hal_api_version field 52 * to this value when declaring the module with HAL_MODULE_INFO_SYM. 53 * 54 * Note that previous implementations have always set this field to 0. 55 * Therefore, libhardware HAL API will always consider versions 0.0 and 1.0 56 * to be 100% binary compatible. 57 * 58 */ 59 #define HARDWARE_HAL_API_VERSION HARDWARE_MAKE_API_VERSION(1, 0) 60 61 /* 62 * Helper macros for module implementors. 63 * 64 * The derived modules should provide convenience macros for supported 65 * versions so that implementations can explicitly specify module/device 66 * versions at definition time. 67 * 68 * Use this macro to set the hw_module_t.module_api_version field. 69 */ 70 #define HARDWARE_MODULE_API_VERSION(maj,min) HARDWARE_MAKE_API_VERSION(maj,min) 71 #define HARDWARE_MODULE_API_VERSION_2(maj,min,hdr) HARDWARE_MAKE_API_VERSION_2(maj,min,hdr) 72 73 /* 74 * Use this macro to set the hw_device_t.version field 75 */ 76 #define HARDWARE_DEVICE_API_VERSION(maj,min) HARDWARE_MAKE_API_VERSION(maj,min) 77 #define HARDWARE_DEVICE_API_VERSION_2(maj,min,hdr) HARDWARE_MAKE_API_VERSION_2(maj,min,hdr) 78 79 struct hw_module_t; 80 struct hw_module_methods_t; 81 struct hw_device_t; 82 83 /** 84 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 85 * and the fields of this data structure must begin with hw_module_t 86 * followed by module specific information. 87 */ 88 typedef struct hw_module_t { 89 /** tag must be initialized to HARDWARE_MODULE_TAG */ 90 uint32_t tag; 91 92 /** 93 * The API version of the implemented module. The module owner is 94 * responsible for updating the version when a module interface has 95 * changed. 96 * 97 * The derived modules such as gralloc and audio own and manage this field. 98 * The module user must interpret the version field to decide whether or 99 * not to inter-operate with the supplied module implementation. 100 * For example, SurfaceFlinger is responsible for making sure that 101 * it knows how to manage different versions of the gralloc-module API, 102 * and AudioFlinger must know how to do the same for audio-module API. 103 * 104 * The module API version should include a major and a minor component. 105 * For example, version 1.0 could be represented as 0x0100. This format 106 * implies that versions 0x0100-0x01ff are all API-compatible. 107 * 108 * In the future, libhardware will expose a hw_get_module_version() 109 * (or equivalent) function that will take minimum/maximum supported 110 * versions as arguments and would be able to reject modules with 111 * versions outside of the supplied range. 112 */ 113 uint16_t module_api_version; 114 #define version_major module_api_version 115 /** 116 * version_major/version_minor defines are supplied here for temporary 117 * source code compatibility. They will be removed in the next version. 118 * ALL clients must convert to the new version format. 119 */ 120 121 /** 122 * The API version of the HAL module interface. This is meant to 123 * version the hw_module_t, hw_module_methods_t, and hw_device_t 124 * structures and definitions. 125 * 126 * The HAL interface owns this field. Module users/implementations 127 * must NOT rely on this value for version information. 128 * 129 * Presently, 0 is the only valid value. 130 */ 131 uint16_t hal_api_version; 132 #define version_minor hal_api_version 133 134 /** Identifier of module */ 135 const char *id; 136 137 /** Name of this module */ 138 const char *name; 139 140 /** Author/owner/implementor of the module */ 141 const char *author; 142 143 /** Modules methods */ 144 struct hw_module_methods_t* methods; 145 146 /** module's dso */ 147 void* dso; 148 149 #ifdef __LP64__ 150 uint64_t reserved[32-7]; 151 #else 152 /** padding to 128 bytes, reserved for future use */ 153 uint32_t reserved[32-7]; 154 #endif 155 156 } hw_module_t; 157 158 typedef struct hw_module_methods_t { 159 /** Open a specific device */ 160 int (*open)(const struct hw_module_t* module, const char* id, 161 struct hw_device_t** device); 162 163 } hw_module_methods_t; 164 165 /** 166 * Every device data structure must begin with hw_device_t 167 * followed by module specific public methods and attributes. 168 */ 169 typedef struct hw_device_t { 170 /** tag must be initialized to HARDWARE_DEVICE_TAG */ 171 uint32_t tag; 172 173 /** 174 * Version of the module-specific device API. This value is used by 175 * the derived-module user to manage different device implementations. 176 * 177 * The module user is responsible for checking the module_api_version 178 * and device version fields to ensure that the user is capable of 179 * communicating with the specific module implementation. 180 * 181 * One module can support multiple devices with different versions. This 182 * can be useful when a device interface changes in an incompatible way 183 * but it is still necessary to support older implementations at the same 184 * time. One such example is the Camera 2.0 API. 185 * 186 * This field is interpreted by the module user and is ignored by the 187 * HAL interface itself. 188 */ 189 uint32_t version; 190 191 /** reference to the module this device belongs to */ 192 struct hw_module_t* module; 193 194 /** padding reserved for future use */ 195 #ifdef __LP64__ 196 uint64_t reserved[12]; 197 #else 198 uint32_t reserved[12]; 199 #endif 200 201 /** Close this device */ 202 int (*close)(struct hw_device_t* device); 203 204 } hw_device_t; 205 206 #ifdef __cplusplus 207 #define TO_HW_DEVICE_T_OPEN(x) reinterpret_cast<struct hw_device_t**>(x) 208 #else 209 #define TO_HW_DEVICE_T_OPEN(x) (struct hw_device_t**)(x) 210 #endif 211 212 /** 213 * Name of the hal_module_info 214 */ 215 #define HAL_MODULE_INFO_SYM HMI 216 217 /** 218 * Name of the hal_module_info as a string 219 */ 220 #define HAL_MODULE_INFO_SYM_AS_STR "HMI" 221 222 /** 223 * Get the module info associated with a module by id. 224 * 225 * @return: 0 == success, <0 == error and *module == NULL 226 */ 227 int hw_get_module(const char *id, const struct hw_module_t **module); 228 229 /** 230 * Get the module info associated with a module instance by class 'class_id' 231 * and instance 'inst'. 232 * 233 * Some modules types necessitate multiple instances. For example audio supports 234 * multiple concurrent interfaces and thus 'audio' is the module class 235 * and 'primary' or 'a2dp' are module interfaces. This implies that the files 236 * providing these modules would be named audio.primary.<variant>.so and 237 * audio.a2dp.<variant>.so 238 * 239 * @return: 0 == success, <0 == error and *module == NULL 240 */ 241 int hw_get_module_by_class(const char *class_id, const char *inst, 242 const struct hw_module_t **module); 243 244 __END_DECLS 245 246 #endif /* ANDROID_INCLUDE_HARDWARE_HARDWARE_H */ 247