Commit | Line | Data |
---|---|---|
1e494cf4 JB |
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(maj,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(maj,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 */ |