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