Guennadi Liakhovetski | 2853155 | 2008-08-29 15:16:31 -0300 | [diff] [blame] | 1 | Soc-Camera Subsystem |
| 2 | ==================== |
| 3 | |
| 4 | Terminology |
| 5 | ----------- |
| 6 | |
| 7 | The following terms are used in this document: |
| 8 | - camera / camera device / camera sensor - a video-camera sensor chip, capable |
| 9 | of connecting to a variety of systems and interfaces, typically uses i2c for |
| 10 | control and configuration, and a parallel or a serial bus for data. |
| 11 | - camera host - an interface, to which a camera is connected. Typically a |
| 12 | specialised interface, present on many SoCs, e.g., PXA27x and PXA3xx, SuperH, |
| 13 | AVR32, i.MX27, i.MX31. |
| 14 | - camera host bus - a connection between a camera host and a camera. Can be |
| 15 | parallel or serial, consists of data and control lines, e.g., clock, vertical |
| 16 | and horizontal synchronization signals. |
| 17 | |
| 18 | Purpose of the soc-camera subsystem |
| 19 | ----------------------------------- |
| 20 | |
| 21 | The soc-camera subsystem provides a unified API between camera host drivers and |
| 22 | camera sensor drivers. It implements a V4L2 interface to the user, currently |
| 23 | only the mmap method is supported. |
| 24 | |
| 25 | This subsystem has been written to connect drivers for System-on-Chip (SoC) |
| 26 | video capture interfaces with drivers for CMOS camera sensor chips to enable |
| 27 | the reuse of sensor drivers with various hosts. The subsystem has been designed |
| 28 | to support multiple camera host interfaces and multiple cameras per interface, |
| 29 | although most applications have only one camera sensor. |
| 30 | |
| 31 | Existing drivers |
| 32 | ---------------- |
| 33 | |
| 34 | As of 2.6.27-rc4 there are two host drivers in the mainline: pxa_camera.c for |
| 35 | PXA27x SoCs and sh_mobile_ceu_camera.c for SuperH SoCs, and four sensor drivers: |
| 36 | mt9m001.c, mt9m111.c, mt9v022.c and a generic soc_camera_platform.c driver. This |
| 37 | list is not supposed to be updated, look for more examples in your tree. |
| 38 | |
| 39 | Camera host API |
| 40 | --------------- |
| 41 | |
| 42 | A host camera driver is registered using the |
| 43 | |
| 44 | soc_camera_host_register(struct soc_camera_host *); |
| 45 | |
| 46 | function. The host object can be initialized as follows: |
| 47 | |
| 48 | static struct soc_camera_host pxa_soc_camera_host = { |
| 49 | .drv_name = PXA_CAM_DRV_NAME, |
| 50 | .ops = &pxa_soc_camera_host_ops, |
| 51 | }; |
| 52 | |
| 53 | All camera host methods are passed in a struct soc_camera_host_ops: |
| 54 | |
| 55 | static struct soc_camera_host_ops pxa_soc_camera_host_ops = { |
| 56 | .owner = THIS_MODULE, |
| 57 | .add = pxa_camera_add_device, |
| 58 | .remove = pxa_camera_remove_device, |
| 59 | .suspend = pxa_camera_suspend, |
| 60 | .resume = pxa_camera_resume, |
| 61 | .set_fmt_cap = pxa_camera_set_fmt_cap, |
| 62 | .try_fmt_cap = pxa_camera_try_fmt_cap, |
| 63 | .init_videobuf = pxa_camera_init_videobuf, |
| 64 | .reqbufs = pxa_camera_reqbufs, |
| 65 | .poll = pxa_camera_poll, |
| 66 | .querycap = pxa_camera_querycap, |
| 67 | .try_bus_param = pxa_camera_try_bus_param, |
| 68 | .set_bus_param = pxa_camera_set_bus_param, |
| 69 | }; |
| 70 | |
| 71 | .add and .remove methods are called when a sensor is attached to or detached |
| 72 | from the host, apart from performing host-internal tasks they shall also call |
| 73 | sensor driver's .init and .release methods respectively. .suspend and .resume |
| 74 | methods implement host's power-management functionality and its their |
| 75 | responsibility to call respective sensor's methods. .try_bus_param and |
| 76 | .set_bus_param are used to negotiate physical connection parameters between the |
| 77 | host and the sensor. .init_videobuf is called by soc-camera core when a |
| 78 | video-device is opened, further video-buffer management is implemented completely |
| 79 | by the specific camera host driver. The rest of the methods are called from |
| 80 | respective V4L2 operations. |
| 81 | |
| 82 | Camera API |
| 83 | ---------- |
| 84 | |
| 85 | Sensor drivers can use struct soc_camera_link, typically provided by the |
| 86 | platform, and used to specify to which camera host bus the sensor is connected, |
| 87 | and arbitrarily provide platform .power and .reset methods for the camera. |
| 88 | soc_camera_device_register() and soc_camera_device_unregister() functions are |
| 89 | used to add a sensor driver to or remove one from the system. The registration |
| 90 | function takes a pointer to struct soc_camera_device as the only parameter. |
| 91 | This struct can be initialized as follows: |
| 92 | |
| 93 | /* link to driver operations */ |
| 94 | icd->ops = &mt9m001_ops; |
| 95 | /* link to the underlying physical (e.g., i2c) device */ |
| 96 | icd->control = &client->dev; |
| 97 | /* window geometry */ |
| 98 | icd->x_min = 20; |
| 99 | icd->y_min = 12; |
| 100 | icd->x_current = 20; |
| 101 | icd->y_current = 12; |
| 102 | icd->width_min = 48; |
| 103 | icd->width_max = 1280; |
| 104 | icd->height_min = 32; |
| 105 | icd->height_max = 1024; |
| 106 | icd->y_skip_top = 1; |
| 107 | /* camera bus ID, typically obtained from platform data */ |
| 108 | icd->iface = icl->bus_id; |
| 109 | |
| 110 | struct soc_camera_ops provides .probe and .remove methods, which are called by |
| 111 | the soc-camera core, when a camera is matched against or removed from a camera |
| 112 | host bus, .init, .release, .suspend, and .resume are called from the camera host |
| 113 | driver as discussed above. Other members of this struct provide respective V4L2 |
| 114 | functionality. |
| 115 | |
| 116 | struct soc_camera_device also links to an array of struct soc_camera_data_format, |
| 117 | listing pixel formats, supported by the camera. |
| 118 | |
Guennadi Liakhovetski | 6a6c878 | 2009-08-25 11:50:46 -0300 | [diff] [blame] | 119 | VIDIOC_S_CROP and VIDIOC_S_FMT behaviour |
| 120 | ---------------------------------------- |
| 121 | |
| 122 | Above user ioctls modify image geometry as follows: |
| 123 | |
| 124 | VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor |
| 125 | pixel. Changing sensor window sizes preserves any scaling factors, therefore |
| 126 | user window sizes change as well. |
| 127 | |
| 128 | VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as |
| 129 | much as possible by modifying scaling factors. If the sensor window cannot be |
| 130 | preserved precisely, it may be changed too. |
| 131 | |
| 132 | In soc-camera there are two locations, where scaling and cropping can taks |
| 133 | place: in the camera driver and in the host driver. User ioctls are first passed |
| 134 | to the host driver, which then generally passes them down to the camera driver. |
| 135 | It is more efficient to perform scaling and cropping in the camera driver to |
| 136 | save camera bus bandwidth and maximise the framerate. However, if the camera |
| 137 | driver failed to set the required parameters with sufficient precision, the host |
| 138 | driver may decide to also use its own scaling and cropping to fulfill the user's |
| 139 | request. |
| 140 | |
| 141 | Camera drivers are interfaced to the soc-camera core and to host drivers over |
| 142 | the v4l2-subdev API, which is completely functional, it doesn't pass any data. |
| 143 | Therefore all camera drivers shall reply to .g_fmt() requests with their current |
| 144 | output geometry. This is necessary to correctly configure the camera bus. |
| 145 | .s_fmt() and .try_fmt() have to be implemented too. Sensor window and scaling |
| 146 | factors have to be maintained by camera drivers internally. According to the |
| 147 | V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we |
| 148 | rely on camera drivers implementing .cropcap(). If the camera driver does not |
| 149 | support cropping, it may choose to not implement .s_crop(), but to enable |
| 150 | cropping support by the camera host driver at least the .g_crop method must be |
| 151 | implemented. |
| 152 | |
| 153 | User window geometry is kept in .user_width and .user_height fields in struct |
| 154 | soc_camera_device and used by the soc-camera core and host drivers. The core |
| 155 | updates these fields upon successful completion of a .s_fmt() call, but if these |
| 156 | fields change elsewhere, e.g., during .s_crop() processing, the host driver is |
| 157 | responsible for updating them. |
| 158 | |
Guennadi Liakhovetski | 2853155 | 2008-08-29 15:16:31 -0300 | [diff] [blame] | 159 | -- |
| 160 | Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> |