About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / video4linux / omap3isp.txt


Based on kernel version 4.7.2. Page generated on 2016-08-22 22:48 EST.

1	OMAP 3 Image Signal Processor (ISP) driver
2	
3	Copyright (C) 2010 Nokia Corporation
4	Copyright (C) 2009 Texas Instruments, Inc.
5	
6	Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
7		  Sakari Ailus <sakari.ailus@iki.fi>
8		  David Cohen <dacohen@gmail.com>
9	
10	
11	Introduction
12	============
13	
14	This file documents the Texas Instruments OMAP 3 Image Signal Processor (ISP)
15	driver located under drivers/media/platform/omap3isp. The original driver was
16	written by Texas Instruments but since that it has been rewritten (twice) at
17	Nokia.
18	
19	The driver has been successfully used on the following versions of OMAP 3:
20	
21		3430
22		3530
23		3630
24	
25	The driver implements V4L2, Media controller and v4l2_subdev interfaces.
26	Sensor, lens and flash drivers using the v4l2_subdev interface in the kernel
27	are supported.
28	
29	
30	Split to subdevs
31	================
32	
33	The OMAP 3 ISP is split into V4L2 subdevs, each of the blocks inside the ISP
34	having one subdev to represent it. Each of the subdevs provide a V4L2 subdev
35	interface to userspace.
36	
37		OMAP3 ISP CCP2
38		OMAP3 ISP CSI2a
39		OMAP3 ISP CCDC
40		OMAP3 ISP preview
41		OMAP3 ISP resizer
42		OMAP3 ISP AEWB
43		OMAP3 ISP AF
44		OMAP3 ISP histogram
45	
46	Each possible link in the ISP is modelled by a link in the Media controller
47	interface. For an example program see [2].
48	
49	
50	Controlling the OMAP 3 ISP
51	==========================
52	
53	In general, the settings given to the OMAP 3 ISP take effect at the beginning
54	of the following frame. This is done when the module becomes idle during the
55	vertical blanking period on the sensor. In memory-to-memory operation the pipe
56	is run one frame at a time. Applying the settings is done between the frames.
57	
58	All the blocks in the ISP, excluding the CSI-2 and possibly the CCP2 receiver,
59	insist on receiving complete frames. Sensors must thus never send the ISP
60	partial frames.
61	
62	Autoidle does have issues with some ISP blocks on the 3430, at least.
63	Autoidle is only enabled on 3630 when the omap3isp module parameter autoidle
64	is non-zero.
65	
66	
67	Events
68	======
69	
70	The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and
71	statistics (AEWB, AF and histogram) subdevs.
72	
73	The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS
74	interrupt which is used to signal frame start. Earlier version of this
75	driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is
76	triggered exactly when the reception of the first line of the frame starts
77	in the CCDC module. The event can be subscribed on the CCDC subdev.
78	
79	(When using parallel interface one must pay account to correct configuration
80	of the VS signal polarity. This is automatically correct when using the serial
81	receivers.)
82	
83	Each of the statistics subdevs is able to produce events. An event is
84	generated whenever a statistics buffer can be dequeued by a user space
85	application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available
86	are:
87	
88		V4L2_EVENT_OMAP3ISP_AEWB
89		V4L2_EVENT_OMAP3ISP_AF
90		V4L2_EVENT_OMAP3ISP_HIST
91	
92	The type of the event data is struct omap3isp_stat_event_status for these
93	ioctls. If there is an error calculating the statistics, there will be an
94	event as usual, but no related statistics buffer. In this case
95	omap3isp_stat_event_status.buf_err is set to non-zero.
96	
97	
98	Private IOCTLs
99	==============
100	
101	The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where
102	possible and practical. Much of the functions provided by the ISP, however,
103	does not fall under the standard IOCTLs --- gamma tables and configuration of
104	statistics collection are examples of such.
105	
106	In general, there is a private ioctl for configuring each of the blocks
107	containing hardware-dependent functions.
108	
109	The following private IOCTLs are supported:
110	
111		VIDIOC_OMAP3ISP_CCDC_CFG
112		VIDIOC_OMAP3ISP_PRV_CFG
113		VIDIOC_OMAP3ISP_AEWB_CFG
114		VIDIOC_OMAP3ISP_HIST_CFG
115		VIDIOC_OMAP3ISP_AF_CFG
116		VIDIOC_OMAP3ISP_STAT_REQ
117		VIDIOC_OMAP3ISP_STAT_EN
118	
119	The parameter structures used by these ioctls are described in
120	include/linux/omap3isp.h. The detailed functions of the ISP itself related to
121	a given ISP block is described in the Technical Reference Manuals (TRMs) ---
122	see the end of the document for those.
123	
124	While it is possible to use the ISP driver without any use of these private
125	IOCTLs it is not possible to obtain optimal image quality this way. The AEWB,
126	AF and histogram modules cannot be used without configuring them using the
127	appropriate private IOCTLs.
128	
129	
130	CCDC and preview block IOCTLs
131	=============================
132	
133	The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to
134	configure, enable and disable functions in the CCDC and preview blocks,
135	respectively. Both IOCTLs control several functions in the blocks they
136	control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct
137	omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG
138	accepts a pointer to struct omap3isp_prev_update_config. The definition of
139	both structures is available in [1].
140	
141	The update field in the structures tells whether to update the configuration
142	for the specific function and the flag tells whether to enable or disable the
143	function.
144	
145	The update and flag bit masks accept the following values. Each separate
146	functions in the CCDC and preview blocks is associated with a flag (either
147	disable or enable; part of the flag field in the structure) and a pointer to
148	configuration data for the function.
149	
150	Valid values for the update and flag fields are listed here for
151	VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one
152	function in the same IOCTL call.
153	
154	        OMAP3ISP_CCDC_ALAW
155	        OMAP3ISP_CCDC_LPF
156	        OMAP3ISP_CCDC_BLCLAMP
157	        OMAP3ISP_CCDC_BCOMP
158	        OMAP3ISP_CCDC_FPC
159	        OMAP3ISP_CCDC_CULL
160	        OMAP3ISP_CCDC_CONFIG_LSC
161	        OMAP3ISP_CCDC_TBL_LSC
162	
163	The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here:
164	
165	        OMAP3ISP_PREV_LUMAENH
166	        OMAP3ISP_PREV_INVALAW
167	        OMAP3ISP_PREV_HRZ_MED
168	        OMAP3ISP_PREV_CFA
169	        OMAP3ISP_PREV_CHROMA_SUPP
170	        OMAP3ISP_PREV_WB
171	        OMAP3ISP_PREV_BLKADJ
172	        OMAP3ISP_PREV_RGB2RGB
173	        OMAP3ISP_PREV_COLOR_CONV
174	        OMAP3ISP_PREV_YC_LIMIT
175	        OMAP3ISP_PREV_DEFECT_COR
176	        OMAP3ISP_PREV_GAMMABYPASS
177	        OMAP3ISP_PREV_DRK_FRM_CAPTURE
178	        OMAP3ISP_PREV_DRK_FRM_SUBTRACT
179	        OMAP3ISP_PREV_LENS_SHADING
180	        OMAP3ISP_PREV_NF
181	        OMAP3ISP_PREV_GAMMA
182	
183	The associated configuration pointer for the function may not be NULL when
184	enabling the function. When disabling a function the configuration pointer is
185	ignored.
186	
187	
188	Statistic blocks IOCTLs
189	=======================
190	
191	The statistics subdevs do offer more dynamic configuration options than the
192	other subdevs. They can be enabled, disable and reconfigured when the pipeline
193	is in streaming state.
194	
195	The statistics blocks always get the input image data from the CCDC (as the
196	histogram memory read isn't implemented). The statistics are dequeueable by
197	the user from the statistics subdev nodes using private IOCTLs.
198	
199	The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily
200	reflected by the register level interface offered by the ISP hardware. There
201	are aspects that are purely related to the driver implementation and these are
202	discussed next.
203	
204	VIDIOC_OMAP3ISP_STAT_EN
205	-----------------------
206	
207	This private IOCTL enables/disables a statistic module. If this request is
208	done before streaming, it will take effect as soon as the pipeline starts to
209	stream.  If the pipeline is already streaming, it will take effect as soon as
210	the CCDC becomes idle.
211	
212	VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
213	-----------------------------------------------------------------------------
214	
215	Those IOCTLs are used to configure the modules. They require user applications
216	to have an in-depth knowledge of the hardware. Most of the fields explanation
217	can be found on OMAP's TRMs. The two following fields common to all the above
218	configure private IOCTLs require explanation for better understanding as they
219	are not part of the TRM.
220	
221	omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size:
222	
223	The modules handle their buffers internally. The necessary buffer size for the
224	module's data output depends on the requested configuration. Although the
225	driver supports reconfiguration while streaming, it does not support a
226	reconfiguration which requires bigger buffer size than what is already
227	internally allocated if the module is enabled. It will return -EBUSY on this
228	case. In order to avoid such condition, either disable/reconfigure/enable the
229	module or request the necessary buffer size during the first configuration
230	while the module is disabled.
231	
232	The internal buffer size allocation considers the requested configuration's
233	minimum buffer size and the value set on buf_size field. If buf_size field is
234	out of [minimum, maximum] buffer size range, it's clamped to fit in there.
235	The driver then selects the biggest value. The corrected buf_size value is
236	written back to user application.
237	
238	omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter:
239	
240	As the configuration doesn't take effect synchronously to the request, the
241	driver must provide a way to track this information to provide more accurate
242	data. After a configuration is requested, the config_counter returned to user
243	space application will be an unique value associated to that request. When
244	user application receives an event for buffer availability or when a new
245	buffer is requested, this config_counter is used to match a buffer data and a
246	configuration.
247	
248	VIDIOC_OMAP3ISP_STAT_REQ
249	------------------------
250	
251	Send to user space the oldest data available in the internal buffer queue and
252	discards such buffer afterwards. The field omap3isp_stat_data.frame_number
253	matches with the video buffer's field_count.
254	
255	
256	Technical reference manuals (TRMs) and other documentation
257	==========================================================
258	
259	OMAP 3430 TRM:
260	<URL:http://focus.ti.com/pdfs/wtbu/OMAP34xx_ES3.1.x_PUBLIC_TRM_vZM.zip>
261	Referenced 2011-03-05.
262	
263	OMAP 35xx TRM:
264	<URL:http://www.ti.com/litv/pdf/spruf98o> Referenced 2011-03-05.
265	
266	OMAP 3630 TRM:
267	<URL:http://focus.ti.com/pdfs/wtbu/OMAP36xx_ES1.x_PUBLIC_TRM_vQ.zip>
268	Referenced 2011-03-05.
269	
270	DM 3730 TRM:
271	<URL:http://www.ti.com/litv/pdf/sprugn4h> Referenced 2011-03-06.
272	
273	
274	References
275	==========
276	
277	[1] include/linux/omap3isp.h
278	
279	[2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog