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