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