hardware.h revision 2b57780d88e32ce9fde32dc085aef2fa7fd478e1
1f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/* 2f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Copyright (C) 2008 The Android Open Source Project 3f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 4f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); 5f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * you may not use this file except in compliance with the License. 6f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * You may obtain a copy of the License at 7f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 8f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 9f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 10f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Unless required by applicable law or agreed to in writing, software 11f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 12f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * See the License for the specific language governing permissions and 14f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * limitations under the License. 15f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 16f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 17f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#ifndef ANDROID_INCLUDE_HARDWARE_HARDWARE_H 18f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#define ANDROID_INCLUDE_HARDWARE_HARDWARE_H 19f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 20f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#include <stdint.h> 21f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#include <sys/cdefs.h> 22f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 23a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#include <cutils/native_handle.h> 24c12d0e9240db0fb53546fd08276454a2cca72492Iliyan Malchev#include <system/graphics.h> 25a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 26f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project__BEGIN_DECLS 27f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 28f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/* 29f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Value for the hw_module_t.tag field 30f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 31a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 32a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#define MAKE_TAG_CONSTANT(A,B,C,D) (((A) << 24) | ((B) << 16) | ((C) << 8) | (D)) 33a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 34a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#define HARDWARE_MODULE_TAG MAKE_TAG_CONSTANT('H', 'W', 'M', 'T') 35a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#define HARDWARE_DEVICE_TAG MAKE_TAG_CONSTANT('H', 'W', 'D', 'T') 36f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 37f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Projectstruct hw_module_t; 38f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Projectstruct hw_module_methods_t; 39f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Projectstruct hw_device_t; 40f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 41f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 42f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 43f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * and the fields of this data structure must begin with hw_module_t 44f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * followed by module specific information. 45f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 469d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopiantypedef struct hw_module_t { 47f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** tag must be initialized to HARDWARE_MODULE_TAG */ 48f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project uint32_t tag; 49f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 502b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin /** 512b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * The API version of the implemented module. The module owner is 522b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * responsible for updating the version when a module interface has 532b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * changed. 542b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * 552b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * The derived modules such as gralloc and audio own and manage this field. 562b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * The module user must interpret the version field to decide whether or 572b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * not to inter-operate with the supplied module implementation. 582b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * For example, SurfaceFlinger is responsible for making sure that 592b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * it knows how to manage different versions of the gralloc-module API, 602b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * and AudioFlinger must know how to do the same for audio-module API. 612b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * 622b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * The module API version should include a major and a minor component. 632b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * For example, version 1.0 could be represented as 0x0100. This format 642b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * implies that versions 0x0100-0x01ff are all API-compatible. 652b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * 662b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * In the future, libhardware will expose a hw_get_module_version() 672b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * (or equivalent) function that will take minimum/maximum supported 682b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * versions as arguments and would be able to reject modules with 692b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * versions outside of the supplied range. 702b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin */ 712b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin uint16_t module_api_version; 722b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin 732b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin /** 742b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * The API version of the HAL module interface. This is meant to 752b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * version the hw_module_t, hw_module_methods_t, and hw_device_t 762b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * structures and definitions. 772b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * 782b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * The HAL interface owns this field. Module users/implementations 792b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * must NOT rely on this value for version information. 802b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * 812b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * Presently, 0 is the only valid value. 822b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin */ 832b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin uint16_t hal_api_version; 84f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 85f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** Identifier of module */ 86f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project const char *id; 87f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 88f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** Name of this module */ 89f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project const char *name; 90f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 91f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** Author/owner/implementor of the module */ 92f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project const char *author; 93f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 94f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** Modules methods */ 95f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project struct hw_module_methods_t* methods; 96a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 97a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /** module's dso */ 98a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian void* dso; 99a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 100f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** padding to 128 bytes, reserved for future use */ 101a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian uint32_t reserved[32-7]; 102f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 1039d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian} hw_module_t; 1049d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian 1059d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopiantypedef struct hw_module_methods_t { 106f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** Open a specific device */ 107f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project int (*open)(const struct hw_module_t* module, const char* id, 108f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project struct hw_device_t** device); 1099d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian 1109d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian} hw_module_methods_t; 111f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 112f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 113f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Every device data structure must begin with hw_device_t 114f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * followed by module specific public methods and attributes. 115f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 1169d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopiantypedef struct hw_device_t { 117f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** tag must be initialized to HARDWARE_DEVICE_TAG */ 118f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project uint32_t tag; 119f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 1202b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin /** 1212b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * Version of the module-specific device API. This value is used by 1222b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * the derived-module user to manage different device implementations. 1232b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * 1242b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * The module user is responsible for checking the module_api_version 1252b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * and device version fields to ensure that the user is capable of 1262b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * communicating with the specific module implementation. 1272b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * 1282b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * One module can support multiple devices with different versions. This 1292b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * can be useful when a device interface changes in an incompatible way 1302b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * but it is still necessary to support older implementations at the same 1312b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * time. One such example is the Camera 2.0 API. 1322b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * 1332b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * This field is interpreted by the module user and is ignored by the 1342b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin * HAL interface itself. 1352b57780d88e32ce9fde32dc085aef2fa7fd478e1Dima Zavin */ 136f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project uint32_t version; 137f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 138f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** reference to the module this device belongs to */ 139f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project struct hw_module_t* module; 140f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 141f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** padding reserved for future use */ 142f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project uint32_t reserved[12]; 143f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 144f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** Close this device */ 145f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project int (*close)(struct hw_device_t* device); 1469d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian 1479d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian} hw_device_t; 148f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 149f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 150a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Name of the hal_module_info 151f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 152f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#define HAL_MODULE_INFO_SYM HMI 153f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 154f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 155f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Name of the hal_module_info as a string 156f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 157f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#define HAL_MODULE_INFO_SYM_AS_STR "HMI" 158f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 159f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 160f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Get the module info associated with a module by id. 16154921de415cd91af21801115baa40e78fc4ea4beDima Zavin * 16254921de415cd91af21801115baa40e78fc4ea4beDima Zavin * @return: 0 == success, <0 == error and *module == NULL 163f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 164f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Projectint hw_get_module(const char *id, const struct hw_module_t **module); 165f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 16654921de415cd91af21801115baa40e78fc4ea4beDima Zavin/** 16754921de415cd91af21801115baa40e78fc4ea4beDima Zavin * Get the module info associated with a module instance by class 'class_id' 16854921de415cd91af21801115baa40e78fc4ea4beDima Zavin * and instance 'inst'. 16954921de415cd91af21801115baa40e78fc4ea4beDima Zavin * 17054921de415cd91af21801115baa40e78fc4ea4beDima Zavin * Some modules types necessitate multiple instances. For example audio supports 17154921de415cd91af21801115baa40e78fc4ea4beDima Zavin * multiple concurrent interfaces and thus 'audio' is the module class 17254921de415cd91af21801115baa40e78fc4ea4beDima Zavin * and 'primary' or 'a2dp' are module interfaces. This implies that the files 17354921de415cd91af21801115baa40e78fc4ea4beDima Zavin * providing these modules would be named audio.primary.<variant>.so and 17454921de415cd91af21801115baa40e78fc4ea4beDima Zavin * audio.a2dp.<variant>.so 17554921de415cd91af21801115baa40e78fc4ea4beDima Zavin * 17654921de415cd91af21801115baa40e78fc4ea4beDima Zavin * @return: 0 == success, <0 == error and *module == NULL 17754921de415cd91af21801115baa40e78fc4ea4beDima Zavin */ 17854921de415cd91af21801115baa40e78fc4ea4beDima Zavinint hw_get_module_by_class(const char *class_id, const char *inst, 17954921de415cd91af21801115baa40e78fc4ea4beDima Zavin const struct hw_module_t **module); 180f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 181f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project__END_DECLS 182f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 183f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#endif /* ANDROID_INCLUDE_HARDWARE_HARDWARE_H */ 184