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