PageRenderTime 15ms CodeModel.GetById 7ms app.highlight 6ms RepoModel.GetById 0ms app.codeStats 1ms

Plain Text | 160 lines | 132 code | 28 blank | 0 comment | 0 complexity | 51b686d69307b88b6ee86b126bdfebac MD5 | raw file
Possible License(s): CC-BY-SA-3.0, GPL-2.0, LGPL-2.0, AGPL-1.0
  1			Soc-Camera Subsystem
  2			====================
  7The 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.
 18Purpose of the soc-camera subsystem
 21The soc-camera subsystem provides a unified API between camera host drivers and
 22camera sensor drivers. It implements a V4L2 interface to the user, currently
 23only the mmap method is supported.
 25This subsystem has been written to connect drivers for System-on-Chip (SoC)
 26video capture interfaces with drivers for CMOS camera sensor chips to enable
 27the reuse of sensor drivers with various hosts. The subsystem has been designed
 28to support multiple camera host interfaces and multiple cameras per interface,
 29although most applications have only one camera sensor.
 31Existing drivers
 34As of 2.6.27-rc4 there are two host drivers in the mainline: pxa_camera.c for
 35PXA27x SoCs and sh_mobile_ceu_camera.c for SuperH SoCs, and four sensor drivers:
 36mt9m001.c, mt9m111.c, mt9v022.c and a generic soc_camera_platform.c driver. This
 37list is not supposed to be updated, look for more examples in your tree.
 39Camera host API
 42A host camera driver is registered using the
 44soc_camera_host_register(struct soc_camera_host *);
 46function. The host object can be initialized as follows:
 48static struct soc_camera_host pxa_soc_camera_host = {
 49	.drv_name	= PXA_CAM_DRV_NAME,
 50	.ops		= &pxa_soc_camera_host_ops,
 53All camera host methods are passed in a struct soc_camera_host_ops:
 55static 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,
 71.add and .remove methods are called when a sensor is attached to or detached
 72from the host, apart from performing host-internal tasks they shall also call
 73sensor driver's .init and .release methods respectively. .suspend and .resume
 74methods implement host's power-management functionality and its their
 75responsibility to call respective sensor's methods. .try_bus_param and
 76.set_bus_param are used to negotiate physical connection parameters between the
 77host and the sensor. .init_videobuf is called by soc-camera core when a
 78video-device is opened, further video-buffer management is implemented completely
 79by the specific camera host driver. The rest of the methods are called from
 80respective V4L2 operations.
 82Camera API
 85Sensor drivers can use struct soc_camera_link, typically provided by the
 86platform, and used to specify to which camera host bus the sensor is connected,
 87and arbitrarily provide platform .power and .reset methods for the camera.
 88soc_camera_device_register() and soc_camera_device_unregister() functions are
 89used to add a sensor driver to or remove one from the system. The registration
 90function takes a pointer to struct soc_camera_device as the only parameter.
 91This struct can be initialized as follows:
 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;
110struct soc_camera_ops provides .probe and .remove methods, which are called by
111the soc-camera core, when a camera is matched against or removed from a camera
112host bus, .init, .release, .suspend, and .resume are called from the camera host
113driver as discussed above. Other members of this struct provide respective V4L2
116struct soc_camera_device also links to an array of struct soc_camera_data_format,
117listing pixel formats, supported by the camera.
119VIDIOC_S_CROP and VIDIOC_S_FMT behaviour
122Above user ioctls modify image geometry as follows:
124VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor
125pixel. Changing sensor window sizes preserves any scaling factors, therefore
126user window sizes change as well.
128VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as
129much as possible by modifying scaling factors. If the sensor window cannot be
130preserved precisely, it may be changed too.
132In soc-camera there are two locations, where scaling and cropping can taks
133place: in the camera driver and in the host driver. User ioctls are first passed
134to the host driver, which then generally passes them down to the camera driver.
135It is more efficient to perform scaling and cropping in the camera driver to
136save camera bus bandwidth and maximise the framerate. However, if the camera
137driver failed to set the required parameters with sufficient precision, the host
138driver may decide to also use its own scaling and cropping to fulfill the user's
141Camera drivers are interfaced to the soc-camera core and to host drivers over
142the v4l2-subdev API, which is completely functional, it doesn't pass any data.
143Therefore all camera drivers shall reply to .g_fmt() requests with their current
144output 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
146factors have to be maintained by camera drivers internally. According to the
147V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we
148rely on camera drivers implementing .cropcap(). If the camera driver does not
149support cropping, it may choose to not implement .s_crop(), but to enable
150cropping support by the camera host driver at least the .g_crop method must be
153User window geometry is kept in .user_width and .user_height fields in struct
154soc_camera_device and used by the soc-camera core and host drivers. The core
155updates these fields upon successful completion of a .s_fmt() call, but if these
156fields change elsewhere, e.g., during .s_crop() processing, the host driver is
157responsible for updating them.
160Author: Guennadi Liakhovetski <>