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 */
124typedef struct camera_metadata camera_metadata_t;
125
126typedef 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 */
211typedef 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 */
242typedef 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
268typedef 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