blob: f62fcdbc8b9ffdeb3a92b3131c487df8fc7f08e8 [file] [log] [blame]
Guennadi Liakhovetski28531552008-08-29 15:16:31 -03001 Soc-Camera Subsystem
2 ====================
3
4Terminology
5-----------
6
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
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030012 specialised interface, present on many SoCs, e.g. PXA27x and PXA3xx, SuperH,
Guennadi Liakhovetski28531552008-08-29 15:16:31 -030013 AVR32, i.MX27, i.MX31.
14 - camera host bus - a connection between a camera host and a camera. Can be
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030015 parallel or serial, consists of data and control lines, e.g. clock, vertical
Guennadi Liakhovetski28531552008-08-29 15:16:31 -030016 and horizontal synchronization signals.
17
18Purpose of the soc-camera subsystem
19-----------------------------------
20
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030021The soc-camera subsystem initially provided a unified API between camera host
22drivers and camera sensor drivers. Later the soc-camera sensor API has been
23replaced with the V4L2 standard subdev API. This also made camera driver re-use
24with non-soc-camera hosts possible. The camera host API to the soc-camera core
25has been preserved.
Guennadi Liakhovetski28531552008-08-29 15:16:31 -030026
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030027Soc-camera implements a V4L2 interface to the user, currently only the "mmap"
28method is supported by host drivers. However, the soc-camera core also provides
29support for the "read" method.
30
31The subsystem has been designed to support multiple camera host interfaces and
32multiple cameras per interface, although most applications have only one camera
33sensor.
Guennadi Liakhovetski28531552008-08-29 15:16:31 -030034
35Existing drivers
36----------------
37
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030038As of 3.7 there are seven host drivers in the mainline: atmel-isi.c,
39mx1_camera.c (broken, scheduled for removal), mx2_camera.c, mx3_camera.c,
40omap1_camera.c, pxa_camera.c, sh_mobile_ceu_camera.c, and multiple sensor
41drivers under drivers/media/i2c/soc_camera/.
Guennadi Liakhovetski28531552008-08-29 15:16:31 -030042
43Camera host API
44---------------
45
46A host camera driver is registered using the
47
48soc_camera_host_register(struct soc_camera_host *);
49
50function. The host object can be initialized as follows:
51
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030052 struct soc_camera_host *ici;
53 ici->drv_name = DRV_NAME;
54 ici->ops = &camera_host_ops;
55 ici->priv = pcdev;
56 ici->v4l2_dev.dev = &pdev->dev;
57 ici->nr = pdev->id;
Guennadi Liakhovetski28531552008-08-29 15:16:31 -030058
59All camera host methods are passed in a struct soc_camera_host_ops:
60
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030061static struct soc_camera_host_ops camera_host_ops = {
Guennadi Liakhovetski28531552008-08-29 15:16:31 -030062 .owner = THIS_MODULE,
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030063 .add = camera_add_device,
64 .remove = camera_remove_device,
65 .set_fmt = camera_set_fmt_cap,
66 .try_fmt = camera_try_fmt_cap,
67 .init_videobuf2 = camera_init_videobuf2,
68 .poll = camera_poll,
69 .querycap = camera_querycap,
70 .set_bus_param = camera_set_bus_param,
71 /* The rest of host operations are optional */
Guennadi Liakhovetski28531552008-08-29 15:16:31 -030072};
73
74.add and .remove methods are called when a sensor is attached to or detached
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030075from the host. .set_bus_param is used to configure physical connection
76parameters between the host and the sensor. .init_videobuf2 is called by
77soc-camera core when a video-device is opened, the host driver would typically
78call vb2_queue_init() in this method. Further video-buffer management is
79implemented completely by the specific camera host driver. If the host driver
80supports non-standard pixel format conversion, it should implement a
81.get_formats and, possibly, a .put_formats operations. See below for more
82details about format conversion. The rest of the methods are called from
Guennadi Liakhovetski28531552008-08-29 15:16:31 -030083respective V4L2 operations.
84
85Camera API
86----------
87
88Sensor drivers can use struct soc_camera_link, typically provided by the
89platform, and used to specify to which camera host bus the sensor is connected,
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -030090and optionally provide platform .power and .reset methods for the camera. This
91struct is provided to the camera driver via the I2C client device platform data
92and can be obtained, using the soc_camera_i2c_to_link() macro. Care should be
93taken, when using soc_camera_vdev_to_subdev() and when accessing struct
94soc_camera_device, using v4l2_get_subdev_hostdata(): both only work, when
95running on an soc-camera host. The actual camera driver operation is implemented
96using the V4L2 subdev API. Additionally soc-camera camera drivers can use
97auxiliary soc-camera helper functions like soc_camera_power_on() and
98soc_camera_power_off(), which switch regulators, provided by the platform and call
99board-specific power switching methods. soc_camera_apply_board_flags() takes
100camera bus configuration capability flags and applies any board transformations,
101e.g. signal polarity inversion. soc_mbus_get_fmtdesc() can be used to obtain a
102pixel format descriptor, corresponding to a certain media-bus pixel format code.
103soc_camera_limit_side() can be used to restrict beginning and length of a frame
104side, based on camera capabilities.
Guennadi Liakhovetski28531552008-08-29 15:16:31 -0300105
Guennadi Liakhovetski6a6c8782009-08-25 11:50:46 -0300106VIDIOC_S_CROP and VIDIOC_S_FMT behaviour
107----------------------------------------
108
109Above user ioctls modify image geometry as follows:
110
111VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor
112pixel. Changing sensor window sizes preserves any scaling factors, therefore
113user window sizes change as well.
114
115VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as
116much as possible by modifying scaling factors. If the sensor window cannot be
117preserved precisely, it may be changed too.
118
119In soc-camera there are two locations, where scaling and cropping can taks
120place: in the camera driver and in the host driver. User ioctls are first passed
121to the host driver, which then generally passes them down to the camera driver.
122It is more efficient to perform scaling and cropping in the camera driver to
123save camera bus bandwidth and maximise the framerate. However, if the camera
124driver failed to set the required parameters with sufficient precision, the host
125driver may decide to also use its own scaling and cropping to fulfill the user's
126request.
127
128Camera drivers are interfaced to the soc-camera core and to host drivers over
129the v4l2-subdev API, which is completely functional, it doesn't pass any data.
130Therefore all camera drivers shall reply to .g_fmt() requests with their current
131output geometry. This is necessary to correctly configure the camera bus.
132.s_fmt() and .try_fmt() have to be implemented too. Sensor window and scaling
133factors have to be maintained by camera drivers internally. According to the
134V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we
135rely on camera drivers implementing .cropcap(). If the camera driver does not
136support cropping, it may choose to not implement .s_crop(), but to enable
137cropping support by the camera host driver at least the .g_crop method must be
138implemented.
139
140User window geometry is kept in .user_width and .user_height fields in struct
141soc_camera_device and used by the soc-camera core and host drivers. The core
142updates these fields upon successful completion of a .s_fmt() call, but if these
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -0300143fields change elsewhere, e.g. during .s_crop() processing, the host driver is
Guennadi Liakhovetski6a6c8782009-08-25 11:50:46 -0300144responsible for updating them.
145
Guennadi Liakhovetski454547f2012-10-05 12:33:45 -0300146Format conversion
147-----------------
148
149V4L2 distinguishes between pixel formats, as they are stored in memory, and as
150they are transferred over a media bus. Soc-camera provides support to
151conveniently manage these formats. A table of standard transformations is
152maintained by soc-camera core, which describes, what FOURCC pixel format will
153be obtained, if a media-bus pixel format is stored in memory according to
154certain rules. E.g. if V4L2_MBUS_FMT_YUYV8_2X8 data is sampled with 8 bits per
155sample and stored in memory in the little-endian order with no gaps between
156bytes, data in memory will represent the V4L2_PIX_FMT_YUYV FOURCC format. These
157standard transformations will be used by soc-camera or by camera host drivers to
158configure camera drivers to produce the FOURCC format, requested by the user,
159using the VIDIOC_S_FMT ioctl(). Apart from those standard format conversions,
160host drivers can also provide their own conversion rules by implementing a
161.get_formats and, if required, a .put_formats methods.
162
Guennadi Liakhovetski28531552008-08-29 15:16:31 -0300163--
164Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de>