[deliverable/linux.git] / Documentation / video4linux / soc-camera.txt

			Soc-Camera Subsystem
			====================

Terminology
-----------

The following terms are used in this document:
 - camera / camera device / camera sensor - a video-camera sensor chip, capable
   of connecting to a variety of systems and interfaces, typically uses i2c for
   control and configuration, and a parallel or a serial bus for data.
 - camera host - an interface, to which a camera is connected. Typically a
   specialised interface, present on many SoCs, e.g., PXA27x and PXA3xx, SuperH,
   AVR32, i.MX27, i.MX31.
 - camera host bus - a connection between a camera host and a camera. Can be
   parallel or serial, consists of data and control lines, e.g., clock, vertical
   and horizontal synchronization signals.

Purpose of the soc-camera subsystem
-----------------------------------

The soc-camera subsystem provides a unified API between camera host drivers and
camera sensor drivers. It implements a V4L2 interface to the user, currently
only the mmap method is supported.

This subsystem has been written to connect drivers for System-on-Chip (SoC)
video capture interfaces with drivers for CMOS camera sensor chips to enable
the reuse of sensor drivers with various hosts. The subsystem has been designed
to support multiple camera host interfaces and multiple cameras per interface,
although most applications have only one camera sensor.

Existing drivers
----------------

As of 2.6.27-rc4 there are two host drivers in the mainline: pxa_camera.c for
PXA27x SoCs and sh_mobile_ceu_camera.c for SuperH SoCs, and four sensor drivers:
mt9m001.c, mt9m111.c, mt9v022.c and a generic soc_camera_platform.c driver. This
list is not supposed to be updated, look for more examples in your tree.

Camera host API
---------------

A host camera driver is registered using the

soc_camera_host_register(struct soc_camera_host *);

function. The host object can be initialized as follows:

static struct soc_camera_host pxa_soc_camera_host = {
	.drv_name	= PXA_CAM_DRV_NAME,
	.ops		= &pxa_soc_camera_host_ops,
};

All camera host methods are passed in a struct soc_camera_host_ops:

static struct soc_camera_host_ops pxa_soc_camera_host_ops = {
	.owner		= THIS_MODULE,
	.add		= pxa_camera_add_device,
	.remove		= pxa_camera_remove_device,
	.suspend	= pxa_camera_suspend,
	.resume		= pxa_camera_resume,
	.set_fmt_cap	= pxa_camera_set_fmt_cap,
	.try_fmt_cap	= pxa_camera_try_fmt_cap,
	.init_videobuf	= pxa_camera_init_videobuf,
	.reqbufs	= pxa_camera_reqbufs,
	.poll		= pxa_camera_poll,
	.querycap	= pxa_camera_querycap,
	.try_bus_param	= pxa_camera_try_bus_param,
	.set_bus_param	= pxa_camera_set_bus_param,
};

.add and .remove methods are called when a sensor is attached to or detached
from the host, apart from performing host-internal tasks they shall also call
sensor driver's .init and .release methods respectively. .suspend and .resume
methods implement host's power-management functionality and its their
responsibility to call respective sensor's methods. .try_bus_param and
.set_bus_param are used to negotiate physical connection parameters between the
host and the sensor. .init_videobuf is called by soc-camera core when a
video-device is opened, further video-buffer management is implemented completely
by the specific camera host driver. The rest of the methods are called from
respective V4L2 operations.

Camera API
----------

Sensor drivers can use struct soc_camera_link, typically provided by the
platform, and used to specify to which camera host bus the sensor is connected,
and arbitrarily provide platform .power and .reset methods for the camera.
soc_camera_device_register() and soc_camera_device_unregister() functions are
used to add a sensor driver to or remove one from the system. The registration
function takes a pointer to struct soc_camera_device as the only parameter.
This struct can be initialized as follows:

	/* link to driver operations */
	icd->ops	= &mt9m001_ops;
	/* link to the underlying physical (e.g., i2c) device */
	icd->control	= &client->dev;
	/* window geometry */
	icd->x_min	= 20;
	icd->y_min	= 12;
	icd->x_current	= 20;
	icd->y_current	= 12;
	icd->width_min	= 48;
	icd->width_max	= 1280;
	icd->height_min	= 32;
	icd->height_max	= 1024;
	icd->y_skip_top	= 1;
	/* camera bus ID, typically obtained from platform data */
	icd->iface	= icl->bus_id;

struct soc_camera_ops provides .probe and .remove methods, which are called by
the soc-camera core, when a camera is matched against or removed from a camera
host bus, .init, .release, .suspend, and .resume are called from the camera host
driver as discussed above. Other members of this struct provide respective V4L2
functionality.

struct soc_camera_device also links to an array of struct soc_camera_data_format,
listing pixel formats, supported by the camera.

--
Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de>
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
119	--
120	Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de>