diff options
author | Sakari Ailus <sakari.ailus@iki.fi> | 2011-03-07 12:20:52 -0500 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@redhat.com> | 2011-03-22 03:53:57 -0400 |
commit | e83dd485ed04b21215c1283042e8d4712ab1a675 (patch) | |
tree | bf5f626da436c1d0122ebe87e0b5f4250d886d4c /Documentation/video4linux/omap3isp.txt | |
parent | 474966ee01cc877e28abed3ada5b48a963c58695 (diff) |
[media] omap3isp: Add documentation
Add documentation on the OMAP 3 ISP driver. Document the subdevs, V4L2
events and private IOCTLs the driver implements
Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
Signed-off-by: David Cohen <dacohen@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/video4linux/omap3isp.txt')
-rw-r--r-- | Documentation/video4linux/omap3isp.txt | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/Documentation/video4linux/omap3isp.txt b/Documentation/video4linux/omap3isp.txt new file mode 100644 index 000000000000..69be2c782b98 --- /dev/null +++ b/Documentation/video4linux/omap3isp.txt | |||
@@ -0,0 +1,278 @@ | |||
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/video/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_OMAP3ISP_HS_VS type event on HS_VS | ||
74 | interrupt which is used to signal frame start. The event is triggered exactly | ||
75 | when the reception of the first line of the frame starts in the CCDC module. | ||
76 | The event can be subscribed on the CCDC subdev. | ||
77 | |||
78 | (When using parallel interface one must pay account to correct configuration | ||
79 | of the VS signal polarity. This is automatically correct when using the serial | ||
80 | receivers.) | ||
81 | |||
82 | Each of the statistics subdevs is able to produce events. An event is | ||
83 | generated whenever a statistics buffer can be dequeued by a user space | ||
84 | application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available | ||
85 | are: | ||
86 | |||
87 | V4L2_EVENT_OMAP3ISP_AEWB | ||
88 | V4L2_EVENT_OMAP3ISP_AF | ||
89 | V4L2_EVENT_OMAP3ISP_HIST | ||
90 | |||
91 | The type of the event data is struct omap3isp_stat_event_status for these | ||
92 | ioctls. If there is an error calculating the statistics, there will be an | ||
93 | event as usual, but no related statistics buffer. In this case | ||
94 | omap3isp_stat_event_status.buf_err is set to non-zero. | ||
95 | |||
96 | |||
97 | Private IOCTLs | ||
98 | ============== | ||
99 | |||
100 | The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where | ||
101 | possible and practical. Much of the functions provided by the ISP, however, | ||
102 | does not fall under the standard IOCTLs --- gamma tables and configuration of | ||
103 | statistics collection are examples of such. | ||
104 | |||
105 | In general, there is a private ioctl for configuring each of the blocks | ||
106 | containing hardware-dependent functions. | ||
107 | |||
108 | The 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 | |||
118 | The parameter structures used by these ioctls are described in | ||
119 | include/linux/omap3isp.h. The detailed functions of the ISP itself related to | ||
120 | a given ISP block is described in the Technical Reference Manuals (TRMs) --- | ||
121 | see the end of the document for those. | ||
122 | |||
123 | While it is possible to use the ISP driver without any use of these private | ||
124 | IOCTLs it is not possible to obtain optimal image quality this way. The AEWB, | ||
125 | AF and histogram modules cannot be used without configuring them using the | ||
126 | appropriate private IOCTLs. | ||
127 | |||
128 | |||
129 | CCDC and preview block IOCTLs | ||
130 | ============================= | ||
131 | |||
132 | The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to | ||
133 | configure, enable and disable functions in the CCDC and preview blocks, | ||
134 | respectively. Both IOCTLs control several functions in the blocks they | ||
135 | control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct | ||
136 | omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG | ||
137 | accepts a pointer to struct omap3isp_prev_update_config. The definition of | ||
138 | both structures is available in [1]. | ||
139 | |||
140 | The update field in the structures tells whether to update the configuration | ||
141 | for the specific function and the flag tells whether to enable or disable the | ||
142 | function. | ||
143 | |||
144 | The update and flag bit masks accept the following values. Each separate | ||
145 | functions in the CCDC and preview blocks is associated with a flag (either | ||
146 | disable or enable; part of the flag field in the structure) and a pointer to | ||
147 | configuration data for the function. | ||
148 | |||
149 | Valid values for the update and flag fields are listed here for | ||
150 | VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one | ||
151 | function 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 | |||
162 | The 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 | |||
182 | The associated configuration pointer for the function may not be NULL when | ||
183 | enabling the function. When disabling a function the configuration pointer is | ||
184 | ignored. | ||
185 | |||
186 | |||
187 | Statistic blocks IOCTLs | ||
188 | ======================= | ||
189 | |||
190 | The statistics subdevs do offer more dynamic configuration options than the | ||
191 | other subdevs. They can be enabled, disable and reconfigured when the pipeline | ||
192 | is in streaming state. | ||
193 | |||
194 | The statistics blocks always get the input image data from the CCDC (as the | ||
195 | histogram memory read isn't implemented). The statistics are dequeueable by | ||
196 | the user from the statistics subdev nodes using private IOCTLs. | ||
197 | |||
198 | The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily | ||
199 | reflected by the register level interface offered by the ISP hardware. There | ||
200 | are aspects that are purely related to the driver implementation and these are | ||
201 | discussed next. | ||
202 | |||
203 | VIDIOC_OMAP3ISP_STAT_EN | ||
204 | ----------------------- | ||
205 | |||
206 | This private IOCTL enables/disables a statistic module. If this request is | ||
207 | done before streaming, it will take effect as soon as the pipeline starts to | ||
208 | stream. If the pipeline is already streaming, it will take effect as soon as | ||
209 | the CCDC becomes idle. | ||
210 | |||
211 | VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG | ||
212 | ----------------------------------------------------------------------------- | ||
213 | |||
214 | Those IOCTLs are used to configure the modules. They require user applications | ||
215 | to have an in-depth knowledge of the hardware. Most of the fields explanation | ||
216 | can be found on OMAP's TRMs. The two following fields common to all the above | ||
217 | configure private IOCTLs require explanation for better understanding as they | ||
218 | are not part of the TRM. | ||
219 | |||
220 | omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size: | ||
221 | |||
222 | The modules handle their buffers internally. The necessary buffer size for the | ||
223 | module's data output depends on the requested configuration. Although the | ||
224 | driver supports reconfiguration while streaming, it does not support a | ||
225 | reconfiguration which requires bigger buffer size than what is already | ||
226 | internally allocated if the module is enabled. It will return -EBUSY on this | ||
227 | case. In order to avoid such condition, either disable/reconfigure/enable the | ||
228 | module or request the necessary buffer size during the first configuration | ||
229 | while the module is disabled. | ||
230 | |||
231 | The internal buffer size allocation considers the requested configuration's | ||
232 | minimum buffer size and the value set on buf_size field. If buf_size field is | ||
233 | out of [minimum, maximum] buffer size range, it's clamped to fit in there. | ||
234 | The driver then selects the biggest value. The corrected buf_size value is | ||
235 | written back to user application. | ||
236 | |||
237 | omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter: | ||
238 | |||
239 | As the configuration doesn't take effect synchronously to the request, the | ||
240 | driver must provide a way to track this information to provide more accurate | ||
241 | data. After a configuration is requested, the config_counter returned to user | ||
242 | space application will be an unique value associated to that request. When | ||
243 | user application receives an event for buffer availability or when a new | ||
244 | buffer is requested, this config_counter is used to match a buffer data and a | ||
245 | configuration. | ||
246 | |||
247 | VIDIOC_OMAP3ISP_STAT_REQ | ||
248 | ------------------------ | ||
249 | |||
250 | Send to user space the oldest data available in the internal buffer queue and | ||
251 | discards such buffer afterwards. The field omap3isp_stat_data.frame_number | ||
252 | matches with the video buffer's field_count. | ||
253 | |||
254 | |||
255 | Technical reference manuals (TRMs) and other documentation | ||
256 | ========================================================== | ||
257 | |||
258 | OMAP 3430 TRM: | ||
259 | <URL:http://focus.ti.com/pdfs/wtbu/OMAP34xx_ES3.1.x_PUBLIC_TRM_vZM.zip> | ||
260 | Referenced 2011-03-05. | ||
261 | |||
262 | OMAP 35xx TRM: | ||
263 | <URL:http://www.ti.com/litv/pdf/spruf98o> Referenced 2011-03-05. | ||
264 | |||
265 | OMAP 3630 TRM: | ||
266 | <URL:http://focus.ti.com/pdfs/wtbu/OMAP36xx_ES1.x_PUBLIC_TRM_vQ.zip> | ||
267 | Referenced 2011-03-05. | ||
268 | |||
269 | DM 3730 TRM: | ||
270 | <URL:http://www.ti.com/litv/pdf/sprugn4h> Referenced 2011-03-06. | ||
271 | |||
272 | |||
273 | References | ||
274 | ========== | ||
275 | |||
276 | [1] include/linux/omap3isp.h | ||
277 | |||
278 | [2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary | ||