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