aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/video4linux
diff options
context:
space:
mode:
authorGuennadi Liakhovetski <g.liakhovetski@gmx.de>2008-08-29 14:16:31 -0400
committerMauro Carvalho Chehab <mchehab@redhat.com>2008-10-12 07:36:55 -0400
commit28531558006d5c525b19a207a7ab4ec0643191c9 (patch)
tree7a74d7c5e9f0f8e5da49303dec6ffe9c0cf0e6a3 /Documentation/video4linux
parent92c36147a7fdcead94f98c0a14f30d279653fa64 (diff)
V4L/DVB (8799): soc-camera: add API documentation
Signed-off-by: Guennadi Liakhovetski <g.liakhovetski@gmx.de> Acked-by: Hans Verkuil <hverkuil@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/video4linux')
-rw-r--r--Documentation/video4linux/soc-camera.txt120
1 files changed, 120 insertions, 0 deletions
diff --git a/Documentation/video4linux/soc-camera.txt b/Documentation/video4linux/soc-camera.txt
new file mode 100644
index 000000000000..178ef3c5e579
--- /dev/null
+++ b/Documentation/video4linux/soc-camera.txt
@@ -0,0 +1,120 @@
1 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
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
18Purpose of the soc-camera subsystem
19-----------------------------------
20
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.
24
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.
30
31Existing drivers
32----------------
33
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.
38
39Camera host API
40---------------
41
42A host camera driver is registered using the
43
44soc_camera_host_register(struct soc_camera_host *);
45
46function. The host object can be initialized as follows:
47
48static struct soc_camera_host pxa_soc_camera_host = {
49 .drv_name = PXA_CAM_DRV_NAME,
50 .ops = &pxa_soc_camera_host_ops,
51};
52
53All camera host methods are passed in a struct soc_camera_host_ops:
54
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,
69};
70
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.
81
82Camera API
83----------
84
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:
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
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
114functionality.
115
116struct soc_camera_device also links to an array of struct soc_camera_data_format,
117listing pixel formats, supported by the camera.
118
119--
120Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de>