Home | History | Annotate | Download | only in hardware
      1 /*
      2  * Copyright (C) 2012 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 // FIXME: add well-defined names for cameras
     18 
     19 #ifndef ANDROID_INCLUDE_CAMERA_COMMON_H
     20 #define ANDROID_INCLUDE_CAMERA_COMMON_H
     21 
     22 #include <stdint.h>
     23 #include <stdbool.h>
     24 #include <sys/cdefs.h>
     25 #include <sys/types.h>
     26 #include <cutils/native_handle.h>
     27 #include <system/camera.h>
     28 #include <system/camera_vendor_tags.h>
     29 #include <hardware/hardware.h>
     30 #include <hardware/gralloc.h>
     31 
     32 __BEGIN_DECLS
     33 
     34 /**
     35  * The id of this module
     36  */
     37 #define CAMERA_HARDWARE_MODULE_ID "camera"
     38 
     39 /**
     40  * Module versioning information for the Camera hardware module, based on
     41  * camera_module_t.common.module_api_version. The two most significant hex
     42  * digits represent the major version, and the two least significant represent
     43  * the minor version.
     44  *
     45  *******************************************************************************
     46  * Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0]
     47  *
     48  *   Camera modules that report these version numbers implement the initial
     49  *   camera module HAL interface. All camera devices openable through this
     50  *   module support only version 1 of the camera device HAL. The device_version
     51  *   and static_camera_characteristics fields of camera_info are not valid. Only
     52  *   the android.hardware.Camera API can be supported by this module and its
     53  *   devices.
     54  *
     55  *******************************************************************************
     56  * Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0]
     57  *
     58  *   Camera modules that report this version number implement the second version
     59  *   of the camera module HAL interface. Camera devices openable through this
     60  *   module may support either version 1.0 or version 2.0 of the camera device
     61  *   HAL interface. The device_version field of camera_info is always valid; the
     62  *   static_camera_characteristics field of camera_info is valid if the
     63  *   device_version field is 2.0 or higher.
     64  *
     65  *******************************************************************************
     66  * Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1]
     67  *
     68  *   This camera module version adds support for asynchronous callbacks to the
     69  *   framework from the camera HAL module, which is used to notify the framework
     70  *   about changes to the camera module state. Modules that provide a valid
     71  *   set_callbacks() method must report at least this version number.
     72  *
     73  *******************************************************************************
     74  * Version: 2.2 [CAMERA_MODULE_API_VERSION_2_2]
     75  *
     76  *   This camera module version adds vendor tag support from the module, and
     77  *   deprecates the old vendor_tag_query_ops that were previously only
     78  *   accessible with a device open.
     79  *
     80  *******************************************************************************
     81  * Version: 2.3 [CAMERA_MODULE_API_VERSION_2_3]
     82  *
     83  *   This camera module version adds open legacy camera HAL device support.
     84  *   Framework can use it to open the camera device as lower device HAL version
     85  *   HAL device if the same device can support multiple device API versions.
     86  *   The standard hardware module open call (common.methods->open) continues
     87  *   to open the camera device with the latest supported version, which is
     88  *   also the version listed in camera_info_t.device_version.
     89  *
     90  *******************************************************************************
     91  * Version: 2.4 [CAMERA_MODULE_API_VERSION_2_4]
     92  *
     93  * This camera module version adds below API changes:
     94  *
     95  * 1. Torch mode support. The framework can use it to turn on torch mode for
     96  *    any camera device that has a flash unit, without opening a camera device. The
     97  *    camera device has a higher priority accessing the flash unit than the camera
     98  *    module; opening a camera device will turn off the torch if it had been enabled
     99  *    through the module interface. When there are any resource conflicts, such as
    100  *    open() is called to open a camera device, the camera HAL module must notify the
    101  *    framework through the torch mode status callback that the torch mode has been
    102  *    turned off.
    103  *
    104  * 2. External camera (e.g. USB hot-plug camera) support. The API updates specify that
    105  *    the camera static info is only available when camera is connected and ready to
    106  *    use for external hot-plug cameras. Calls to get static info will be invalid
    107  *    calls when camera status is not CAMERA_DEVICE_STATUS_PRESENT. The frameworks
    108  *    will only count on device status change callbacks to manage the available external
    109  *    camera list.
    110  *
    111  * 3. Camera arbitration hints. This module version adds support for explicitly
    112  *    indicating the number of camera devices that can be simultaneously opened and used.
    113  *    To specify valid combinations of devices, the resource_cost and conflicting_devices
    114  *    fields should always be set in the camera_info structure returned by the
    115  *    get_camera_info call.
    116  *
    117  * 4. Module initialization method. This will be called by the camera service
    118  *    right after the HAL module is loaded, to allow for one-time initialization
    119  *    of the HAL. It is called before any other module methods are invoked.
    120  */
    121 
    122 /**
    123  * Predefined macros for currently-defined version numbers
    124  */
    125 
    126 /**
    127  * All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated
    128  * as CAMERA_MODULE_API_VERSION_1_0
    129  */
    130 #define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
    131 #define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0)
    132 #define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1)
    133 #define CAMERA_MODULE_API_VERSION_2_2 HARDWARE_MODULE_API_VERSION(2, 2)
    134 #define CAMERA_MODULE_API_VERSION_2_3 HARDWARE_MODULE_API_VERSION(2, 3)
    135 #define CAMERA_MODULE_API_VERSION_2_4 HARDWARE_MODULE_API_VERSION(2, 4)
    136 
    137 #define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_4
    138 
    139 /**
    140  * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated
    141  * as CAMERA_DEVICE_API_VERSION_1_0
    142  */
    143 #define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) // DEPRECATED
    144 #define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) // NO LONGER SUPPORTED
    145 #define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1) // NO LONGER SUPPORTED
    146 #define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0)
    147 #define CAMERA_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1)
    148 #define CAMERA_DEVICE_API_VERSION_3_2 HARDWARE_DEVICE_API_VERSION(3, 2)
    149 #define CAMERA_DEVICE_API_VERSION_3_3 HARDWARE_DEVICE_API_VERSION(3, 3)
    150 #define CAMERA_DEVICE_API_VERSION_3_4 HARDWARE_DEVICE_API_VERSION(3, 4)
    151 
    152 // Device version 3.4 is current, older HAL camera device versions are not
    153 // recommended for new devices.
    154 #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_3_4
    155 
    156 /**
    157  * Defined in /system/media/camera/include/system/camera_metadata.h
    158  */
    159 typedef struct camera_metadata camera_metadata_t;
    160 
    161 typedef struct camera_info {
    162     /**
    163      * The direction that the camera faces to. See system/core/include/system/camera.h
    164      * for camera facing definitions.
    165      *
    166      * Version information (based on camera_module_t.common.module_api_version):
    167      *
    168      * CAMERA_MODULE_API_VERSION_2_3 or lower:
    169      *
    170      *   It should be CAMERA_FACING_BACK or CAMERA_FACING_FRONT.
    171      *
    172      * CAMERA_MODULE_API_VERSION_2_4 or higher:
    173      *
    174      *   It should be CAMERA_FACING_BACK, CAMERA_FACING_FRONT or
    175      *   CAMERA_FACING_EXTERNAL.
    176      */
    177     int facing;
    178 
    179     /**
    180      * The orientation of the camera image. The value is the angle that the
    181      * camera image needs to be rotated clockwise so it shows correctly on the
    182      * display in its natural orientation. It should be 0, 90, 180, or 270.
    183      *
    184      * For example, suppose a device has a naturally tall screen. The
    185      * back-facing camera sensor is mounted in landscape. You are looking at the
    186      * screen. If the top side of the camera sensor is aligned with the right
    187      * edge of the screen in natural orientation, the value should be 90. If the
    188      * top side of a front-facing camera sensor is aligned with the right of the
    189      * screen, the value should be 270.
    190      *
    191      * Version information (based on camera_module_t.common.module_api_version):
    192      *
    193      * CAMERA_MODULE_API_VERSION_2_3 or lower:
    194      *
    195      *   Valid in all camera_module versions.
    196      *
    197      * CAMERA_MODULE_API_VERSION_2_4 or higher:
    198      *
    199      *   Valid if camera facing is CAMERA_FACING_BACK or CAMERA_FACING_FRONT,
    200      *   not valid if camera facing is CAMERA_FACING_EXTERNAL.
    201      */
    202     int orientation;
    203 
    204     /**
    205      * The value of camera_device_t.common.version.
    206      *
    207      * Version information (based on camera_module_t.common.module_api_version):
    208      *
    209      *  CAMERA_MODULE_API_VERSION_1_0:
    210      *
    211      *    Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do
    212      *    not read this field.
    213      *
    214      *  CAMERA_MODULE_API_VERSION_2_0 or higher:
    215      *
    216      *    Always valid
    217      *
    218      */
    219     uint32_t device_version;
    220 
    221     /**
    222      * The camera's fixed characteristics, which include all static camera metadata
    223      * specified in system/media/camera/docs/docs.html. This should be a sorted metadata
    224      * buffer, and may not be modified or freed by the caller. The pointer should remain
    225      * valid for the lifetime of the camera module, and values in it may not
    226      * change after it is returned by get_camera_info().
    227      *
    228      * Version information (based on camera_module_t.common.module_api_version):
    229      *
    230      *  CAMERA_MODULE_API_VERSION_1_0:
    231      *
    232      *    Not valid. Extra characteristics are not available. Do not read this
    233      *    field.
    234      *
    235      *  CAMERA_MODULE_API_VERSION_2_0 or higher:
    236      *
    237      *    Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read
    238      *    otherwise.
    239      *
    240      */
    241     const camera_metadata_t *static_camera_characteristics;
    242 
    243     /**
    244      * The total resource "cost" of using this camera, represented as an integer
    245      * value in the range [0, 100] where 100 represents total usage of the shared
    246      * resource that is the limiting bottleneck of the camera subsystem.  This may
    247      * be a very rough estimate, and is used as a hint to the camera service to
    248      * determine when to disallow multiple applications from simultaneously
    249      * opening different cameras advertised by the camera service.
    250      *
    251      * The camera service must be able to simultaneously open and use any
    252      * combination of camera devices exposed by the HAL where the sum of
    253      * the resource costs of these cameras is <= 100.  For determining cost,
    254      * each camera device must be assumed to be configured and operating at
    255      * the maximally resource-consuming framerate and stream size settings
    256      * available in the configuration settings exposed for that device through
    257      * the camera metadata.
    258      *
    259      * The camera service may still attempt to simultaneously open combinations
    260      * of camera devices with a total resource cost > 100.  This may succeed or
    261      * fail.  If this succeeds, combinations of configurations that are not
    262      * supported due to resource constraints from having multiple open devices
    263      * should fail during the configure calls.  If the total resource cost is
    264      * <= 100, open and configure should never fail for any stream configuration
    265      * settings or other device capabilities that would normally succeed for a
    266      * device when it is the only open camera device.
    267      *
    268      * This field will be used to determine whether background applications are
    269      * allowed to use this camera device while other applications are using other
    270      * camera devices.  Note: multiple applications will never be allowed by the
    271      * camera service to simultaneously open the same camera device.
    272      *
    273      * Example use cases:
    274      *
    275      * Ex. 1: Camera Device 0 = Back Camera
    276      *        Camera Device 1 = Front Camera
    277      *   - Using both camera devices causes a large framerate slowdown due to
    278      *     limited ISP bandwidth.
    279      *
    280      *   Configuration:
    281      *
    282      *   Camera Device 0 - resource_cost = 51
    283      *                     conflicting_devices = null
    284      *   Camera Device 1 - resource_cost = 51
    285      *                     conflicting_devices = null
    286      *
    287      *   Result:
    288      *
    289      *   Since the sum of the resource costs is > 100, if a higher-priority
    290      *   application has either device open, no lower-priority applications will be
    291      *   allowed by the camera service to open either device.  If a lower-priority
    292      *   application is using a device that a higher-priority subsequently attempts
    293      *   to open, the lower-priority application will be forced to disconnect the
    294      *   the device.
    295      *
    296      *   If the highest-priority application chooses, it may still attempt to open
    297      *   both devices (since these devices are not listed as conflicting in the
    298      *   conflicting_devices fields), but usage of these devices may fail in the
    299      *   open or configure calls.
    300      *
    301      * Ex. 2: Camera Device 0 = Left Back Camera
    302      *        Camera Device 1 = Right Back Camera
    303      *        Camera Device 2 = Combined stereo camera using both right and left
    304      *                          back camera sensors used by devices 0, and 1
    305      *        Camera Device 3 = Front Camera
    306      *   - Due to do hardware constraints, up to two cameras may be open at once. The
    307      *     combined stereo camera may never be used at the same time as either of the
    308      *     two back camera devices (device 0, 1), and typically requires too much
    309      *     bandwidth to use at the same time as the front camera (device 3).
    310      *
    311      *   Configuration:
    312      *
    313      *   Camera Device 0 - resource_cost = 50
    314      *                     conflicting_devices = { 2 }
    315      *   Camera Device 1 - resource_cost = 50
    316      *                     conflicting_devices = { 2 }
    317      *   Camera Device 2 - resource_cost = 100
    318      *                     conflicting_devices = { 0, 1 }
    319      *   Camera Device 3 - resource_cost = 50
    320      *                     conflicting_devices = null
    321      *
    322      *   Result:
    323      *
    324      *   Based on the conflicting_devices fields, the camera service guarantees that
    325      *   the following sets of open devices will never be allowed: { 1, 2 }, { 0, 2 }.
    326      *
    327      *   Based on the resource_cost fields, if a high-priority foreground application
    328      *   is using camera device 0, a background application would be allowed to open
    329      *   camera device 1 or 3 (but would be forced to disconnect it again if the
    330      *   foreground application opened another device).
    331      *
    332      *   The highest priority application may still attempt to simultaneously open
    333      *   devices 0, 2, and 3, but the HAL may fail in open or configure calls for
    334      *   this combination.
    335      *
    336      * Ex. 3: Camera Device 0 = Back Camera
    337      *        Camera Device 1 = Front Camera
    338      *        Camera Device 2 = Low-power Front Camera that uses the same
    339      *                          sensor as device 1, but only exposes image stream
    340      *                          resolutions that can be used in low-power mode
    341      *  - Using both front cameras (device 1, 2) at the same time is impossible due
    342      *    a shared physical sensor.  Using the back and "high-power" front camera
    343      *    (device 1) may be impossible for some stream configurations due to hardware
    344      *    limitations, but the "low-power" front camera option may always be used as
    345      *    it has special dedicated hardware.
    346      *
    347      *   Configuration:
    348      *
    349      *   Camera Device 0 - resource_cost = 100
    350      *                     conflicting_devices = null
    351      *   Camera Device 1 - resource_cost = 100
    352      *                     conflicting_devices = { 2 }
    353      *   Camera Device 2 - resource_cost = 0
    354      *                     conflicting_devices = { 1 }
    355      *   Result:
    356      *
    357      *   Based on the conflicting_devices fields, the camera service guarantees that
    358      *   the following sets of open devices will never be allowed: { 1, 2 }.
    359      *
    360      *   Based on the resource_cost fields, only the highest priority application
    361      *   may attempt to open both device 0 and 1 at the same time. If a higher-priority
    362      *   application is not using device 1 or 2, a low-priority background application
    363      *   may open device 2 (but will be forced to disconnect it if a higher-priority
    364      *   application subsequently opens device 1 or 2).
    365      *
    366      * Version information (based on camera_module_t.common.module_api_version):
    367      *
    368      *  CAMERA_MODULE_API_VERSION_2_3 or lower:
    369      *
    370      *    Not valid.  Can be assumed to be 100.  Do not read this field.
    371      *
    372      *  CAMERA_MODULE_API_VERSION_2_4 or higher:
    373      *
    374      *    Always valid.
    375      */
    376     int resource_cost;
    377 
    378     /**
    379      * An array of camera device IDs represented as NULL-terminated strings
    380      * indicating other devices that cannot be simultaneously opened while this
    381      * camera device is in use.
    382      *
    383      * This field is intended to be used to indicate that this camera device
    384      * is a composite of several other camera devices, or otherwise has
    385      * hardware dependencies that prohibit simultaneous usage. If there are no
    386      * dependencies, a NULL may be returned in this field to indicate this.
    387      *
    388      * The camera service will never simultaneously open any of the devices
    389      * in this list while this camera device is open.
    390      *
    391      * The strings pointed to in this field will not be cleaned up by the camera
    392      * service, and must remain while this device is plugged in.
    393      *
    394      * Version information (based on camera_module_t.common.module_api_version):
    395      *
    396      *  CAMERA_MODULE_API_VERSION_2_3 or lower:
    397      *
    398      *    Not valid.  Can be assumed to be NULL.  Do not read this field.
    399      *
    400      *  CAMERA_MODULE_API_VERSION_2_4 or higher:
    401      *
    402      *    Always valid.
    403      */
    404     char** conflicting_devices;
    405 
    406     /**
    407      * The length of the array given in the conflicting_devices field.
    408      *
    409      * Version information (based on camera_module_t.common.module_api_version):
    410      *
    411      *  CAMERA_MODULE_API_VERSION_2_3 or lower:
    412      *
    413      *    Not valid.  Can be assumed to be 0.  Do not read this field.
    414      *
    415      *  CAMERA_MODULE_API_VERSION_2_4 or higher:
    416      *
    417      *    Always valid.
    418      */
    419     size_t conflicting_devices_length;
    420 
    421 } camera_info_t;
    422 
    423 /**
    424  * camera_device_status_t:
    425  *
    426  * The current status of the camera device, as provided by the HAL through the
    427  * camera_module_callbacks.camera_device_status_change() call.
    428  *
    429  * At module load time, the framework will assume all camera devices are in the
    430  * CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke
    431  * camera_module_callbacks::camera_device_status_change to inform the framework
    432  * of any initially NOT_PRESENT devices.
    433  *
    434  * Allowed transitions:
    435  *      PRESENT            -> NOT_PRESENT
    436  *      NOT_PRESENT        -> ENUMERATING
    437  *      NOT_PRESENT        -> PRESENT
    438  *      ENUMERATING        -> PRESENT
    439  *      ENUMERATING        -> NOT_PRESENT
    440  */
    441 typedef enum camera_device_status {
    442     /**
    443      * The camera device is not currently connected, and opening it will return
    444      * failure.
    445      *
    446      * Version information (based on camera_module_t.common.module_api_version):
    447      *
    448      * CAMERA_MODULE_API_VERSION_2_3 or lower:
    449      *
    450      *   Calls to get_camera_info must still succeed, and provide the same information
    451      *   it would if the camera were connected.
    452      *
    453      * CAMERA_MODULE_API_VERSION_2_4:
    454      *
    455      *   The camera device at this status must return -EINVAL for get_camera_info call,
    456      *   as the device is not connected.
    457      */
    458     CAMERA_DEVICE_STATUS_NOT_PRESENT = 0,
    459 
    460     /**
    461      * The camera device is connected, and opening it will succeed.
    462      *
    463      * CAMERA_MODULE_API_VERSION_2_3 or lower:
    464      *
    465      *   The information returned by get_camera_info cannot change due to this status
    466      *   change. By default, the framework will assume all devices are in this state.
    467      *
    468      * CAMERA_MODULE_API_VERSION_2_4:
    469      *
    470      *   The information returned by get_camera_info will become valid after a device's
    471      *   status changes to this. By default, the framework will assume all devices are in
    472      *   this state.
    473      */
    474     CAMERA_DEVICE_STATUS_PRESENT = 1,
    475 
    476     /**
    477      * The camera device is connected, but it is undergoing an enumeration and
    478      * so opening the device will return -EBUSY.
    479      *
    480      * CAMERA_MODULE_API_VERSION_2_3 or lower:
    481      *
    482      *   Calls to get_camera_info must still succeed, as if the camera was in the
    483      *   PRESENT status.
    484      *
    485      * CAMERA_MODULE_API_VERSION_2_4:
    486      *
    487      *   The camera device at this status must return -EINVAL for get_camera_info for call,
    488      *   as the device is not ready.
    489      */
    490     CAMERA_DEVICE_STATUS_ENUMERATING = 2,
    491 
    492 } camera_device_status_t;
    493 
    494 /**
    495  * torch_mode_status_t:
    496  *
    497  * The current status of the torch mode, as provided by the HAL through the
    498  * camera_module_callbacks.torch_mode_status_change() call.
    499  *
    500  * The torch mode status of a camera device is applicable only when the camera
    501  * device is present. The framework will not call set_torch_mode() to turn on
    502  * torch mode of a camera device if the camera device is not present. At module
    503  * load time, the framework will assume torch modes are in the
    504  * TORCH_MODE_STATUS_AVAILABLE_OFF state if the camera device is present and
    505  * android.flash.info.available is reported as true via get_camera_info() call.
    506  *
    507  * The behaviors of the camera HAL module that the framework expects in the
    508  * following situations when a camera device's status changes:
    509  *  1. A previously-disconnected camera device becomes connected.
    510  *      After camera_module_callbacks::camera_device_status_change() is invoked
    511  *      to inform the framework that the camera device is present, the framework
    512  *      will assume the camera device's torch mode is in
    513  *      TORCH_MODE_STATUS_AVAILABLE_OFF state. The camera HAL module does not need
    514  *      to invoke camera_module_callbacks::torch_mode_status_change() unless the
    515  *      flash unit is unavailable to use by set_torch_mode().
    516  *
    517  *  2. A previously-connected camera becomes disconnected.
    518  *      After camera_module_callbacks::camera_device_status_change() is invoked
    519  *      to inform the framework that the camera device is not present, the
    520  *      framework will not call set_torch_mode() for the disconnected camera
    521  *      device until its flash unit becomes available again. The camera HAL
    522  *      module does not need to invoke
    523  *      camera_module_callbacks::torch_mode_status_change() separately to inform
    524  *      that the flash unit has become unavailable.
    525  *
    526  *  3. open() is called to open a camera device.
    527  *      The camera HAL module must invoke
    528  *      camera_module_callbacks::torch_mode_status_change() for all flash units
    529  *      that have entered TORCH_MODE_STATUS_NOT_AVAILABLE state and can not be
    530  *      turned on by calling set_torch_mode() anymore due to this open() call.
    531  *      open() must not trigger TORCH_MODE_STATUS_AVAILABLE_OFF before
    532  *      TORCH_MODE_STATUS_NOT_AVAILABLE for all flash units that have become
    533  *      unavailable.
    534  *
    535  *  4. close() is called to close a camera device.
    536  *      The camera HAL module must invoke
    537  *      camera_module_callbacks::torch_mode_status_change() for all flash units
    538  *      that have entered TORCH_MODE_STATUS_AVAILABLE_OFF state and can be turned
    539  *      on by calling set_torch_mode() again because of enough resources freed
    540  *      up by this close() call.
    541  *
    542  *  Note that the framework calling set_torch_mode() successfully must trigger
    543  *  TORCH_MODE_STATUS_AVAILABLE_OFF or TORCH_MODE_STATUS_AVAILABLE_ON callback
    544  *  for the given camera device. Additionally it must trigger
    545  *  TORCH_MODE_STATUS_AVAILABLE_OFF callbacks for other previously-on torch
    546  *  modes if HAL cannot keep multiple torch modes on simultaneously.
    547  */
    548 typedef enum torch_mode_status {
    549 
    550     /**
    551      * The flash unit is no longer available and the torch mode can not be
    552      * turned on by calling set_torch_mode(). If the torch mode is on, it
    553      * will be turned off by HAL before HAL calls torch_mode_status_change().
    554      */
    555     TORCH_MODE_STATUS_NOT_AVAILABLE = 0,
    556 
    557     /**
    558      * A torch mode has become off and available to be turned on via
    559      * set_torch_mode(). This may happen in the following
    560      * cases:
    561      *   1. After the resources to turn on the torch mode have become available.
    562      *   2. After set_torch_mode() is called to turn off the torch mode.
    563      *   3. After the framework turned on the torch mode of some other camera
    564      *      device and HAL had to turn off the torch modes of any camera devices
    565      *      that were previously on.
    566      */
    567     TORCH_MODE_STATUS_AVAILABLE_OFF = 1,
    568 
    569     /**
    570      * A torch mode has become on and available to be turned off via
    571      * set_torch_mode(). This can happen only after set_torch_mode() is called
    572      * to turn on the torch mode.
    573      */
    574     TORCH_MODE_STATUS_AVAILABLE_ON = 2,
    575 
    576 } torch_mode_status_t;
    577 
    578 /**
    579  * Callback functions for the camera HAL module to use to inform the framework
    580  * of changes to the camera subsystem.
    581  *
    582  * Version information (based on camera_module_t.common.module_api_version):
    583  *
    584  * Each callback is called only by HAL modules implementing the indicated
    585  * version or higher of the HAL module API interface.
    586  *
    587  *  CAMERA_MODULE_API_VERSION_2_1:
    588  *    camera_device_status_change()
    589  *
    590  *  CAMERA_MODULE_API_VERSION_2_4:
    591  *    torch_mode_status_change()
    592 
    593  */
    594 typedef struct camera_module_callbacks {
    595 
    596     /**
    597      * camera_device_status_change:
    598      *
    599      * Callback to the framework to indicate that the state of a specific camera
    600      * device has changed. At module load time, the framework will assume all
    601      * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL
    602      * must call this method to inform the framework of any initially
    603      * NOT_PRESENT devices.
    604      *
    605      * This callback is added for CAMERA_MODULE_API_VERSION_2_1.
    606      *
    607      * camera_module_callbacks: The instance of camera_module_callbacks_t passed
    608      *   to the module with set_callbacks.
    609      *
    610      * camera_id: The ID of the camera device that has a new status.
    611      *
    612      * new_status: The new status code, one of the camera_device_status_t enums,
    613      *   or a platform-specific status.
    614      *
    615      */
    616     void (*camera_device_status_change)(const struct camera_module_callbacks*,
    617             int camera_id,
    618             int new_status);
    619 
    620     /**
    621      * torch_mode_status_change:
    622      *
    623      * Callback to the framework to indicate that the state of the torch mode
    624      * of the flash unit associated with a specific camera device has changed.
    625      * At module load time, the framework will assume the torch modes are in
    626      * the TORCH_MODE_STATUS_AVAILABLE_OFF state if android.flash.info.available
    627      * is reported as true via get_camera_info() call.
    628      *
    629      * This callback is added for CAMERA_MODULE_API_VERSION_2_4.
    630      *
    631      * camera_module_callbacks: The instance of camera_module_callbacks_t
    632      *   passed to the module with set_callbacks.
    633      *
    634      * camera_id: The ID of camera device whose flash unit has a new torch mode
    635      *   status.
    636      *
    637      * new_status: The new status code, one of the torch_mode_status_t enums.
    638      */
    639     void (*torch_mode_status_change)(const struct camera_module_callbacks*,
    640             const char* camera_id,
    641             int new_status);
    642 
    643 
    644 } camera_module_callbacks_t;
    645 
    646 typedef struct camera_module {
    647     /**
    648      * Common methods of the camera module.  This *must* be the first member of
    649      * camera_module as users of this structure will cast a hw_module_t to
    650      * camera_module pointer in contexts where it's known the hw_module_t
    651      * references a camera_module.
    652      *
    653      * The return values for common.methods->open for camera_module are:
    654      *
    655      * 0:           On a successful open of the camera device.
    656      *
    657      * -ENODEV:     The camera device cannot be opened due to an internal
    658      *              error.
    659      *
    660      * -EINVAL:     The input arguments are invalid, i.e. the id is invalid,
    661      *              and/or the module is invalid.
    662      *
    663      * -EBUSY:      The camera device was already opened for this camera id
    664      *              (by using this method or open_legacy),
    665      *              regardless of the device HAL version it was opened as.
    666      *
    667      * -EUSERS:     The maximal number of camera devices that can be
    668      *              opened concurrently were opened already, either by
    669      *              this method or the open_legacy method.
    670      *
    671      * All other return values from common.methods->open will be treated as
    672      * -ENODEV.
    673      */
    674     hw_module_t common;
    675 
    676     /**
    677      * get_number_of_cameras:
    678      *
    679      * Returns the number of camera devices accessible through the camera
    680      * module.  The camera devices are numbered 0 through N-1, where N is the
    681      * value returned by this call. The name of the camera device for open() is
    682      * simply the number converted to a string. That is, "0" for camera ID 0,
    683      * "1" for camera ID 1.
    684      *
    685      * Version information (based on camera_module_t.common.module_api_version):
    686      *
    687      * CAMERA_MODULE_API_VERSION_2_3 or lower:
    688      *
    689      *   The value here must be static, and cannot change after the first call
    690      *   to this method.
    691      *
    692      * CAMERA_MODULE_API_VERSION_2_4 or higher:
    693      *
    694      *   The value here must be static, and must count only built-in cameras,
    695      *   which have CAMERA_FACING_BACK or CAMERA_FACING_FRONT camera facing values
    696      *   (camera_info.facing). The HAL must not include the external cameras
    697      *   (camera_info.facing == CAMERA_FACING_EXTERNAL) into the return value
    698      *   of this call. Frameworks will use camera_device_status_change callback
    699      *   to manage number of external cameras.
    700      */
    701     int (*get_number_of_cameras)(void);
    702 
    703     /**
    704      * get_camera_info:
    705      *
    706      * Return the static camera information for a given camera device. This
    707      * information may not change for a camera device.
    708      *
    709      * Return values:
    710      *
    711      * 0:           On a successful operation
    712      *
    713      * -ENODEV:     The information cannot be provided due to an internal
    714      *              error.
    715      *
    716      * -EINVAL:     The input arguments are invalid, i.e. the id is invalid,
    717      *              and/or the module is invalid.
    718      *
    719      * Version information (based on camera_module_t.common.module_api_version):
    720      *
    721      * CAMERA_MODULE_API_VERSION_2_4 or higher:
    722      *
    723      *   When a camera is disconnected, its camera id becomes invalid. Calling this
    724      *   this method with this invalid camera id will get -EINVAL and NULL camera
    725      *   static metadata (camera_info.static_camera_characteristics).
    726      */
    727     int (*get_camera_info)(int camera_id, struct camera_info *info);
    728 
    729     /**
    730      * set_callbacks:
    731      *
    732      * Provide callback function pointers to the HAL module to inform framework
    733      * of asynchronous camera module events. The framework will call this
    734      * function once after initial camera HAL module load, after the
    735      * get_number_of_cameras() method is called for the first time, and before
    736      * any other calls to the module.
    737      *
    738      * Version information (based on camera_module_t.common.module_api_version):
    739      *
    740      *  CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0:
    741      *
    742      *    Not provided by HAL module. Framework may not call this function.
    743      *
    744      *  CAMERA_MODULE_API_VERSION_2_1:
    745      *
    746      *    Valid to be called by the framework.
    747      *
    748      * Return values:
    749      *
    750      * 0:           On a successful operation
    751      *
    752      * -ENODEV:     The operation cannot be completed due to an internal
    753      *              error.
    754      *
    755      * -EINVAL:     The input arguments are invalid, i.e. the callbacks are
    756      *              null
    757      */
    758     int (*set_callbacks)(const camera_module_callbacks_t *callbacks);
    759 
    760     /**
    761      * get_vendor_tag_ops:
    762      *
    763      * Get methods to query for vendor extension metadata tag information. The
    764      * HAL should fill in all the vendor tag operation methods, or leave ops
    765      * unchanged if no vendor tags are defined.
    766      *
    767      * The vendor_tag_ops structure used here is defined in:
    768      * system/media/camera/include/system/vendor_tags.h
    769      *
    770      * Version information (based on camera_module_t.common.module_api_version):
    771      *
    772      *  CAMERA_MODULE_API_VERSION_1_x/2_0/2_1:
    773      *    Not provided by HAL module. Framework may not call this function.
    774      *
    775      *  CAMERA_MODULE_API_VERSION_2_2:
    776      *    Valid to be called by the framework.
    777      */
    778     void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops);
    779 
    780     /**
    781      * open_legacy:
    782      *
    783      * Open a specific legacy camera HAL device if multiple device HAL API
    784      * versions are supported by this camera HAL module. For example, if the
    785      * camera module supports both CAMERA_DEVICE_API_VERSION_1_0 and
    786      * CAMERA_DEVICE_API_VERSION_3_2 device API for the same camera id,
    787      * framework can call this function to open the camera device as
    788      * CAMERA_DEVICE_API_VERSION_1_0 device.
    789      *
    790      * This is an optional method. A Camera HAL module does not need to support
    791      * more than one device HAL version per device, and such modules may return
    792      * -ENOSYS for all calls to this method. For all older HAL device API
    793      * versions that are not supported, it may return -EOPNOTSUPP. When above
    794      * cases occur, The normal open() method (common.methods->open) will be
    795      * used by the framework instead.
    796      *
    797      * Version information (based on camera_module_t.common.module_api_version):
    798      *
    799      *  CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2:
    800      *    Not provided by HAL module. Framework will not call this function.
    801      *
    802      *  CAMERA_MODULE_API_VERSION_2_3:
    803      *    Valid to be called by the framework.
    804      *
    805      * Return values:
    806      *
    807      * 0:           On a successful open of the camera device.
    808      *
    809      * -ENOSYS      This method is not supported.
    810      *
    811      * -EOPNOTSUPP: The requested HAL version is not supported by this method.
    812      *
    813      * -EINVAL:     The input arguments are invalid, i.e. the id is invalid,
    814      *              and/or the module is invalid.
    815      *
    816      * -EBUSY:      The camera device was already opened for this camera id
    817      *              (by using this method or common.methods->open method),
    818      *              regardless of the device HAL version it was opened as.
    819      *
    820      * -EUSERS:     The maximal number of camera devices that can be
    821      *              opened concurrently were opened already, either by
    822      *              this method or common.methods->open method.
    823      */
    824     int (*open_legacy)(const struct hw_module_t* module, const char* id,
    825             uint32_t halVersion, struct hw_device_t** device);
    826 
    827     /**
    828      * set_torch_mode:
    829      *
    830      * Turn on or off the torch mode of the flash unit associated with a given
    831      * camera ID. If the operation is successful, HAL must notify the framework
    832      * torch state by invoking
    833      * camera_module_callbacks.torch_mode_status_change() with the new state.
    834      *
    835      * The camera device has a higher priority accessing the flash unit. When
    836      * there are any resource conflicts, such as open() is called to open a
    837      * camera device, HAL module must notify the framework through
    838      * camera_module_callbacks.torch_mode_status_change() that the
    839      * torch mode has been turned off and the torch mode state has become
    840      * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode
    841      * become available again, HAL module must notify the framework through
    842      * camera_module_callbacks.torch_mode_status_change() that the torch mode
    843      * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to
    844      * be called.
    845      *
    846      * When the framework calls set_torch_mode() to turn on the torch mode of a
    847      * flash unit, if HAL cannot keep multiple torch modes on simultaneously,
    848      * HAL should turn off the torch mode that was turned on by
    849      * a previous set_torch_mode() call and notify the framework that the torch
    850      * mode state of that flash unit has become TORCH_MODE_STATUS_AVAILABLE_OFF.
    851      *
    852      * Version information (based on camera_module_t.common.module_api_version):
    853      *
    854      * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3:
    855      *   Not provided by HAL module. Framework will not call this function.
    856      *
    857      * CAMERA_MODULE_API_VERSION_2_4:
    858      *   Valid to be called by the framework.
    859      *
    860      * Return values:
    861      *
    862      * 0:           On a successful operation.
    863      *
    864      * -ENOSYS:     The camera device does not support this operation. It is
    865      *              returned if and only if android.flash.info.available is
    866      *              false.
    867      *
    868      * -EBUSY:      The camera device is already in use.
    869      *
    870      * -EUSERS:     The resources needed to turn on the torch mode are not
    871      *              available, typically because other camera devices are
    872      *              holding the resources to make using the flash unit not
    873      *              possible.
    874      *
    875      * -EINVAL:     camera_id is invalid.
    876      *
    877      */
    878     int (*set_torch_mode)(const char* camera_id, bool enabled);
    879 
    880     /**
    881      * init:
    882      *
    883      * This method is called by the camera service before any other methods
    884      * are invoked, right after the camera HAL library has been successfully
    885      * loaded. It may be left as NULL by the HAL module, if no initialization
    886      * in needed.
    887      *
    888      * It can be used by HAL implementations to perform initialization and
    889      * other one-time operations.
    890      *
    891      * Version information (based on camera_module_t.common.module_api_version):
    892      *
    893      * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3:
    894      *   Not provided by HAL module. Framework will not call this function.
    895      *
    896      * CAMERA_MODULE_API_VERSION_2_4:
    897      *   If not NULL, will always be called by the framework once after the HAL
    898      *   module is loaded, before any other HAL module method is called.
    899      *
    900      * Return values:
    901      *
    902      * 0:           On a successful operation.
    903      *
    904      * -ENODEV:     Initialization cannot be completed due to an internal
    905      *              error. The HAL must be assumed to be in a nonfunctional
    906      *              state.
    907      *
    908      */
    909     int (*init)();
    910 
    911     /* reserved for future use */
    912     void* reserved[5];
    913 } camera_module_t;
    914 
    915 __END_DECLS
    916 
    917 #endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */
    918