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