Commit | Line | Data |
---|---|---|
28531558 GL |
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 | ||
6a6c8786 GL |
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 | ||
28531558 GL |
159 | -- |
160 | Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> |