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 <sys/cdefs.h> 24 #include <sys/types.h> 25 #include <cutils/native_handle.h> 26 #include <system/camera.h> 27 #include <system/camera_vendor_tags.h> 28 #include <hardware/hardware.h> 29 #include <hardware/gralloc.h> 30 31 __BEGIN_DECLS 32 33 /** 34 * The id of this module 35 */ 36 #define CAMERA_HARDWARE_MODULE_ID "camera" 37 38 /** 39 * Module versioning information for the Camera hardware module, based on 40 * camera_module_t.common.module_api_version. The two most significant hex 41 * digits represent the major version, and the two least significant represent 42 * the minor version. 43 * 44 ******************************************************************************* 45 * Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0] 46 * 47 * Camera modules that report these version numbers implement the initial 48 * camera module HAL interface. All camera devices openable through this 49 * module support only version 1 of the camera device HAL. The device_version 50 * and static_camera_characteristics fields of camera_info are not valid. Only 51 * the android.hardware.Camera API can be supported by this module and its 52 * devices. 53 * 54 ******************************************************************************* 55 * Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0] 56 * 57 * Camera modules that report this version number implement the second version 58 * of the camera module HAL interface. Camera devices openable through this 59 * module may support either version 1.0 or version 2.0 of the camera device 60 * HAL interface. The device_version field of camera_info is always valid; the 61 * static_camera_characteristics field of camera_info is valid if the 62 * device_version field is 2.0 or higher. 63 * 64 ******************************************************************************* 65 * Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1] 66 * 67 * This camera module version adds support for asynchronous callbacks to the 68 * framework from the camera HAL module, which is used to notify the framework 69 * about changes to the camera module state. Modules that provide a valid 70 * set_callbacks() method must report at least this version number. 71 * 72 ******************************************************************************* 73 * Version: 2.2 [CAMERA_MODULE_API_VERSION_2_2] 74 * 75 * This camera module version adds vendor tag support from the module, and 76 * deprecates the old vendor_tag_query_ops that were previously only 77 * accessible with a device open. 78 * 79 ******************************************************************************* 80 * Version: 2.3 [CAMERA_MODULE_API_VERSION_2_3] 81 * 82 * This camera module version adds open legacy camera HAL device support. 83 * Framework can use it to open the camera device as lower device HAL version 84 * HAL device if the same device can support multiple device API versions. 85 * The standard hardware module open call (common.methods->open) continues 86 * to open the camera device with the latest supported version, which is 87 * also the version listed in camera_info_t.device_version. 88 */ 89 90 /** 91 * Predefined macros for currently-defined version numbers 92 */ 93 94 /** 95 * All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated 96 * as CAMERA_MODULE_API_VERSION_1_0 97 */ 98 #define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) 99 #define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) 100 #define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1) 101 #define CAMERA_MODULE_API_VERSION_2_2 HARDWARE_MODULE_API_VERSION(2, 2) 102 #define CAMERA_MODULE_API_VERSION_2_3 HARDWARE_MODULE_API_VERSION(2, 3) 103 104 #define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_3 105 106 /** 107 * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated 108 * as CAMERA_DEVICE_API_VERSION_1_0 109 */ 110 #define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) 111 #define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) 112 #define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1) 113 #define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0) 114 #define CAMERA_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1) 115 #define CAMERA_DEVICE_API_VERSION_3_2 HARDWARE_DEVICE_API_VERSION(3, 2) 116 117 // Device version 3.2 is current, older HAL camera device versions are not 118 // recommended for new devices. 119 #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_3_2 120 121 /** 122 * Defined in /system/media/camera/include/system/camera_metadata.h 123 */ 124 typedef struct camera_metadata camera_metadata_t; 125 126 typedef struct camera_info { 127 /** 128 * The direction that the camera faces to. It should be CAMERA_FACING_BACK 129 * or CAMERA_FACING_FRONT. 130 * 131 * Version information: 132 * Valid in all camera_module versions 133 */ 134 int facing; 135 136 /** 137 * The orientation of the camera image. The value is the angle that the 138 * camera image needs to be rotated clockwise so it shows correctly on the 139 * display in its natural orientation. It should be 0, 90, 180, or 270. 140 * 141 * For example, suppose a device has a naturally tall screen. The 142 * back-facing camera sensor is mounted in landscape. You are looking at the 143 * screen. If the top side of the camera sensor is aligned with the right 144 * edge of the screen in natural orientation, the value should be 90. If the 145 * top side of a front-facing camera sensor is aligned with the right of the 146 * screen, the value should be 270. 147 * 148 * Version information: 149 * Valid in all camera_module versions 150 */ 151 int orientation; 152 153 /** 154 * The value of camera_device_t.common.version. 155 * 156 * Version information (based on camera_module_t.common.module_api_version): 157 * 158 * CAMERA_MODULE_API_VERSION_1_0: 159 * 160 * Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do 161 * not read this field. 162 * 163 * CAMERA_MODULE_API_VERSION_2_0 or higher: 164 * 165 * Always valid 166 * 167 */ 168 uint32_t device_version; 169 170 /** 171 * The camera's fixed characteristics, which include all camera metadata in 172 * the android.*.info.* sections. This should be a sorted metadata buffer, 173 * and may not be modified or freed by the caller. The pointer should remain 174 * valid for the lifetime of the camera module, and values in it may not 175 * change after it is returned by get_camera_info(). 176 * 177 * Version information (based on camera_module_t.common.module_api_version): 178 * 179 * CAMERA_MODULE_API_VERSION_1_0: 180 * 181 * Not valid. Extra characteristics are not available. Do not read this 182 * field. 183 * 184 * CAMERA_MODULE_API_VERSION_2_0 or higher: 185 * 186 * Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read 187 * otherwise. 188 * 189 */ 190 const camera_metadata_t *static_camera_characteristics; 191 } camera_info_t; 192 193 /** 194 * camera_device_status_t: 195 * 196 * The current status of the camera device, as provided by the HAL through the 197 * camera_module_callbacks.camera_device_status_change() call. 198 * 199 * At module load time, the framework will assume all camera devices are in the 200 * CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke 201 * camera_module_callbacks::camera_device_status_change to inform the framework 202 * of any initially NOT_PRESENT devices. 203 * 204 * Allowed transitions: 205 * PRESENT -> NOT_PRESENT 206 * NOT_PRESENT -> ENUMERATING 207 * NOT_PRESENT -> PRESENT 208 * ENUMERATING -> PRESENT 209 * ENUMERATING -> NOT_PRESENT 210 */ 211 typedef enum camera_device_status { 212 /** 213 * The camera device is not currently connected, and opening it will return 214 * failure. Calls to get_camera_info must still succeed, and provide the 215 * same information it would if the camera were connected 216 */ 217 CAMERA_DEVICE_STATUS_NOT_PRESENT = 0, 218 219 /** 220 * The camera device is connected, and opening it will succeed. The 221 * information returned by get_camera_info cannot change due to this status 222 * change. By default, the framework will assume all devices are in this 223 * state. 224 */ 225 CAMERA_DEVICE_STATUS_PRESENT = 1, 226 227 /** 228 * The camera device is connected, but it is undergoing an enumeration and 229 * so opening the device will return -EBUSY. Calls to get_camera_info 230 * must still succeed, as if the camera was in the PRESENT status. 231 */ 232 CAMERA_DEVICE_STATUS_ENUMERATING = 2, 233 234 } camera_device_status_t; 235 236 /** 237 * Callback functions for the camera HAL module to use to inform the framework 238 * of changes to the camera subsystem. These are called only by HAL modules 239 * implementing version CAMERA_MODULE_API_VERSION_2_1 or higher of the HAL 240 * module API interface. 241 */ 242 typedef struct camera_module_callbacks { 243 244 /** 245 * camera_device_status_change: 246 * 247 * Callback to the framework to indicate that the state of a specific camera 248 * device has changed. At module load time, the framework will assume all 249 * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL 250 * must call this method to inform the framework of any initially 251 * NOT_PRESENT devices. 252 * 253 * camera_module_callbacks: The instance of camera_module_callbacks_t passed 254 * to the module with set_callbacks. 255 * 256 * camera_id: The ID of the camera device that has a new status. 257 * 258 * new_status: The new status code, one of the camera_device_status_t enums, 259 * or a platform-specific status. 260 * 261 */ 262 void (*camera_device_status_change)(const struct camera_module_callbacks*, 263 int camera_id, 264 int new_status); 265 266 } camera_module_callbacks_t; 267 268 typedef struct camera_module { 269 /** 270 * Common methods of the camera module. This *must* be the first member of 271 * camera_module as users of this structure will cast a hw_module_t to 272 * camera_module pointer in contexts where it's known the hw_module_t 273 * references a camera_module. 274 * 275 * The return values for common.methods->open for camera_module are: 276 * 277 * 0: On a successful open of the camera device. 278 * 279 * -ENODEV: The camera device cannot be opened due to an internal 280 * error. 281 * 282 * -EINVAL: The input arguments are invalid, i.e. the id is invalid, 283 * and/or the module is invalid. 284 * 285 * -EBUSY: The camera device was already opened for this camera id 286 * (by using this method or open_legacy), 287 * regardless of the device HAL version it was opened as. 288 * 289 * -EUSERS: The maximal number of camera devices that can be 290 * opened concurrently were opened already, either by 291 * this method or the open_legacy method. 292 * 293 * All other return values from common.methods->open will be treated as 294 * -ENODEV. 295 */ 296 hw_module_t common; 297 298 /** 299 * get_number_of_cameras: 300 * 301 * Returns the number of camera devices accessible through the camera 302 * module. The camera devices are numbered 0 through N-1, where N is the 303 * value returned by this call. The name of the camera device for open() is 304 * simply the number converted to a string. That is, "0" for camera ID 0, 305 * "1" for camera ID 1. 306 * 307 * The value here must be static, and cannot change after the first call to 308 * this method 309 */ 310 int (*get_number_of_cameras)(void); 311 312 /** 313 * get_camera_info: 314 * 315 * Return the static camera information for a given camera device. This 316 * information may not change for a camera device. 317 * 318 * Return values: 319 * 320 * 0: On a successful operation 321 * 322 * -ENODEV: The information cannot be provided due to an internal 323 * error. 324 * 325 * -EINVAL: The input arguments are invalid, i.e. the id is invalid, 326 * and/or the module is invalid. 327 */ 328 int (*get_camera_info)(int camera_id, struct camera_info *info); 329 330 /** 331 * set_callbacks: 332 * 333 * Provide callback function pointers to the HAL module to inform framework 334 * of asynchronous camera module events. The framework will call this 335 * function once after initial camera HAL module load, after the 336 * get_number_of_cameras() method is called for the first time, and before 337 * any other calls to the module. 338 * 339 * Version information (based on camera_module_t.common.module_api_version): 340 * 341 * CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0: 342 * 343 * Not provided by HAL module. Framework may not call this function. 344 * 345 * CAMERA_MODULE_API_VERSION_2_1: 346 * 347 * Valid to be called by the framework. 348 * 349 * Return values: 350 * 351 * 0: On a successful operation 352 * 353 * -ENODEV: The operation cannot be completed due to an internal 354 * error. 355 * 356 * -EINVAL: The input arguments are invalid, i.e. the callbacks are 357 * null 358 */ 359 int (*set_callbacks)(const camera_module_callbacks_t *callbacks); 360 361 /** 362 * get_vendor_tag_ops: 363 * 364 * Get methods to query for vendor extension metadata tag information. The 365 * HAL should fill in all the vendor tag operation methods, or leave ops 366 * unchanged if no vendor tags are defined. 367 * 368 * The vendor_tag_ops structure used here is defined in: 369 * system/media/camera/include/system/vendor_tags.h 370 * 371 * Version information (based on camera_module_t.common.module_api_version): 372 * 373 * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1: 374 * Not provided by HAL module. Framework may not call this function. 375 * 376 * CAMERA_MODULE_API_VERSION_2_2: 377 * Valid to be called by the framework. 378 */ 379 void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops); 380 381 /** 382 * open_legacy: 383 * 384 * Open a specific legacy camera HAL device if multiple device HAL API 385 * versions are supported by this camera HAL module. For example, if the 386 * camera module supports both CAMERA_DEVICE_API_VERSION_1_0 and 387 * CAMERA_DEVICE_API_VERSION_3_2 device API for the same camera id, 388 * framework can call this function to open the camera device as 389 * CAMERA_DEVICE_API_VERSION_1_0 device. 390 * 391 * This is an optional method. A Camera HAL module does not need to support 392 * more than one device HAL version per device, and such modules may return 393 * -ENOSYS for all calls to this method. For all older HAL device API 394 * versions that are not supported, it may return -EOPNOTSUPP. When above 395 * cases occur, The normal open() method (common.methods->open) will be 396 * used by the framework instead. 397 * 398 * Version information (based on camera_module_t.common.module_api_version): 399 * 400 * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2: 401 * Not provided by HAL module. Framework will not call this function. 402 * 403 * CAMERA_MODULE_API_VERSION_2_3: 404 * Valid to be called by the framework. 405 * 406 * Return values: 407 * 408 * 0: On a successful open of the camera device. 409 * 410 * -ENOSYS This method is not supported. 411 * 412 * -EOPNOTSUPP: The requested HAL version is not supported by this method. 413 * 414 * -EINVAL: The input arguments are invalid, i.e. the id is invalid, 415 * and/or the module is invalid. 416 * 417 * -EBUSY: The camera device was already opened for this camera id 418 * (by using this method or common.methods->open method), 419 * regardless of the device HAL version it was opened as. 420 * 421 * -EUSERS: The maximal number of camera devices that can be 422 * opened concurrently were opened already, either by 423 * this method or common.methods->open method. 424 */ 425 int (*open_legacy)(const struct hw_module_t* module, const char* id, 426 uint32_t halVersion, struct hw_device_t** device); 427 428 /* reserved for future use */ 429 void* reserved[7]; 430 } camera_module_t; 431 432 __END_DECLS 433 434 #endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */ 435
