hardware.h
Go to the documentation of this file.
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  */
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 */
143 
144  /** module's dso */
145  void* dso;
146 
147 #ifdef __LP64__
148  uint64_t reserved[32-7];
149 #else
150  /** padding to 128 bytes, reserved for future use */
151  uint32_t reserved[32-7];
152 #endif
153 
154 } hw_module_t;
155 
156 typedef struct hw_module_methods_t {
157  /** Open a specific device */
158  int (*open)(const struct hw_module_t* module, const char* id,
159  struct hw_device_t** device);
160 
162 
163 /**
164  * Every device data structure must begin with hw_device_t
165  * followed by module specific public methods and attributes.
166  */
167 typedef struct hw_device_t {
168  /** tag must be initialized to HARDWARE_DEVICE_TAG */
169  uint32_t tag;
170 
171  /**
172  * Version of the module-specific device API. This value is used by
173  * the derived-module user to manage different device implementations.
174  *
175  * The module user is responsible for checking the module_api_version
176  * and device version fields to ensure that the user is capable of
177  * communicating with the specific module implementation.
178  *
179  * One module can support multiple devices with different versions. This
180  * can be useful when a device interface changes in an incompatible way
181  * but it is still necessary to support older implementations at the same
182  * time. One such example is the Camera 2.0 API.
183  *
184  * This field is interpreted by the module user and is ignored by the
185  * HAL interface itself.
186  */
187  uint32_t version;
188 
189  /** reference to the module this device belongs to */
191 
192  /** padding reserved for future use */
193 #ifdef __LP64__
194  uint64_t reserved[12];
195 #else
196  uint32_t reserved[12];
197 #endif
198 
199  /** Close this device */
200  int (*close)(struct hw_device_t* device);
201 
202 } hw_device_t;
203 
204 /**
205  * Name of the hal_module_info
206  */
207 #define HAL_MODULE_INFO_SYM HMI
208 
209 /**
210  * Name of the hal_module_info as a string
211  */
212 #define HAL_MODULE_INFO_SYM_AS_STR "HMI"
213 
214 /**
215  * Get the module info associated with a module by id.
216  *
217  * @return: 0 == success, <0 == error and *module == NULL
218  */
219 int hw_get_module(const char *id, const struct hw_module_t **module);
220 
221 /**
222  * Get the module info associated with a module instance by class 'class_id'
223  * and instance 'inst'.
224  *
225  * Some modules types necessitate multiple instances. For example audio supports
226  * multiple concurrent interfaces and thus 'audio' is the module class
227  * and 'primary' or 'a2dp' are module interfaces. This implies that the files
228  * providing these modules would be named audio.primary.<variant>.so and
229  * audio.a2dp.<variant>.so
230  *
231  * @return: 0 == success, <0 == error and *module == NULL
232  */
233 int hw_get_module_by_class(const char *class_id, const char *inst,
234  const struct hw_module_t **module);
235 
236 __END_DECLS
237 
238 #endif /* ANDROID_INCLUDE_HARDWARE_HARDWARE_H */
int(* open)(const struct hw_module_t *module, const char *id, struct hw_device_t **device)
Definition: hardware.h:158
int hw_get_module_by_class(const char *class_id, const char *inst, const struct hw_module_t **module)
const char * id
Definition: hardware.h:133
uint32_t tag
Definition: hardware.h:169
int(* close)(struct hw_device_t *device)
Definition: hardware.h:200
uint16_t hal_api_version
Definition: hardware.h:129
const char * author
Definition: hardware.h:139
uint32_t reserved[12]
Definition: hardware.h:196
uint32_t reserved[32-7]
Definition: hardware.h:151
const char * name
Definition: hardware.h:136
struct hw_device_t hw_device_t
uint32_t tag
Definition: hardware.h:88
struct hw_module_t * module
Definition: hardware.h:190
void * dso
Definition: hardware.h:145
uint32_t version
Definition: hardware.h:187
uint16_t module_api_version
Definition: hardware.h:111
struct hw_module_methods_t hw_module_methods_t
int hw_get_module(const char *id, const struct hw_module_t **module)
struct hw_module_methods_t * methods
Definition: hardware.h:142
struct hw_module_t hw_module_t