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