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