omap3isp-uapi.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3.. include:: <isonum.txt>
  4
  5OMAP 3 Image Signal Processor (ISP) driver
  6==========================================
  7
  8Copyright |copy| 2010 Nokia Corporation
  9
 10Copyright |copy| 2009 Texas Instruments, Inc.
 11
 12Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
 13Sakari Ailus <sakari.ailus@iki.fi>, David Cohen <dacohen@gmail.com>
 14
 15
 16Events
 17------
 18
 19The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and
 20statistics (AEWB, AF and histogram) subdevs.
 21
 22The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS
 23interrupt which is used to signal frame start. Earlier version of this
 24driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is
 25triggered exactly when the reception of the first line of the frame starts
 26in the CCDC module. The event can be subscribed on the CCDC subdev.
 27
 28(When using parallel interface one must pay account to correct configuration
 29of the VS signal polarity. This is automatically correct when using the serial
 30receivers.)
 31
 32Each of the statistics subdevs is able to produce events. An event is
 33generated whenever a statistics buffer can be dequeued by a user space
 34application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available
 35are:
 36
 37- V4L2_EVENT_OMAP3ISP_AEWB
 38- V4L2_EVENT_OMAP3ISP_AF
 39- V4L2_EVENT_OMAP3ISP_HIST
 40
 41The type of the event data is struct omap3isp_stat_event_status for these
 42ioctls. If there is an error calculating the statistics, there will be an
 43event as usual, but no related statistics buffer. In this case
 44omap3isp_stat_event_status.buf_err is set to non-zero.
 45
 46
 47Private IOCTLs
 48--------------
 49
 50The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where
 51possible and practical. Much of the functions provided by the ISP, however,
 52does not fall under the standard IOCTLs --- gamma tables and configuration of
 53statistics collection are examples of such.
 54
 55In general, there is a private ioctl for configuring each of the blocks
 56containing hardware-dependent functions.
 57
 58The following private IOCTLs are supported:
 59
 60- VIDIOC_OMAP3ISP_CCDC_CFG
 61- VIDIOC_OMAP3ISP_PRV_CFG
 62- VIDIOC_OMAP3ISP_AEWB_CFG
 63- VIDIOC_OMAP3ISP_HIST_CFG
 64- VIDIOC_OMAP3ISP_AF_CFG
 65- VIDIOC_OMAP3ISP_STAT_REQ
 66- VIDIOC_OMAP3ISP_STAT_EN
 67
 68The parameter structures used by these ioctls are described in
 69include/linux/omap3isp.h. The detailed functions of the ISP itself related to
 70a given ISP block is described in the Technical Reference Manuals (TRMs) ---
 71see the end of the document for those.
 72
 73While it is possible to use the ISP driver without any use of these private
 74IOCTLs it is not possible to obtain optimal image quality this way. The AEWB,
 75AF and histogram modules cannot be used without configuring them using the
 76appropriate private IOCTLs.
 77
 78
 79CCDC and preview block IOCTLs
 80-----------------------------
 81
 82The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to
 83configure, enable and disable functions in the CCDC and preview blocks,
 84respectively. Both IOCTLs control several functions in the blocks they
 85control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct
 86omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG
 87accepts a pointer to struct omap3isp_prev_update_config. The definition of
 88both structures is available in [#]_.
 89
 90The update field in the structures tells whether to update the configuration
 91for the specific function and the flag tells whether to enable or disable the
 92function.
 93
 94The update and flag bit masks accept the following values. Each separate
 95functions in the CCDC and preview blocks is associated with a flag (either
 96disable or enable; part of the flag field in the structure) and a pointer to
 97configuration data for the function.
 98
 99Valid values for the update and flag fields are listed here for
100VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one
101function in the same IOCTL call.
102
103- OMAP3ISP_CCDC_ALAW
104- OMAP3ISP_CCDC_LPF
105- OMAP3ISP_CCDC_BLCLAMP
106- OMAP3ISP_CCDC_BCOMP
107- OMAP3ISP_CCDC_FPC
108- OMAP3ISP_CCDC_CULL
109- OMAP3ISP_CCDC_CONFIG_LSC
110- OMAP3ISP_CCDC_TBL_LSC
111
112The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here:
113
114- OMAP3ISP_PREV_LUMAENH
115- OMAP3ISP_PREV_INVALAW
116- OMAP3ISP_PREV_HRZ_MED
117- OMAP3ISP_PREV_CFA
118- OMAP3ISP_PREV_CHROMA_SUPP
119- OMAP3ISP_PREV_WB
120- OMAP3ISP_PREV_BLKADJ
121- OMAP3ISP_PREV_RGB2RGB
122- OMAP3ISP_PREV_COLOR_CONV
123- OMAP3ISP_PREV_YC_LIMIT
124- OMAP3ISP_PREV_DEFECT_COR
125- OMAP3ISP_PREV_GAMMABYPASS
126- OMAP3ISP_PREV_DRK_FRM_CAPTURE
127- OMAP3ISP_PREV_DRK_FRM_SUBTRACT
128- OMAP3ISP_PREV_LENS_SHADING
129- OMAP3ISP_PREV_NF
130- OMAP3ISP_PREV_GAMMA
131
132The associated configuration pointer for the function may not be NULL when
133enabling the function. When disabling a function the configuration pointer is
134ignored.
135
136
137Statistic blocks IOCTLs
138-----------------------
139
140The statistics subdevs do offer more dynamic configuration options than the
141other subdevs. They can be enabled, disable and reconfigured when the pipeline
142is in streaming state.
143
144The statistics blocks always get the input image data from the CCDC (as the
145histogram memory read isn't implemented). The statistics are dequeueable by
146the user from the statistics subdev nodes using private IOCTLs.
147
148The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily
149reflected by the register level interface offered by the ISP hardware. There
150are aspects that are purely related to the driver implementation and these are
151discussed next.
152
153VIDIOC_OMAP3ISP_STAT_EN
154-----------------------
155
156This private IOCTL enables/disables a statistic module. If this request is
157done before streaming, it will take effect as soon as the pipeline starts to
158stream.  If the pipeline is already streaming, it will take effect as soon as
159the CCDC becomes idle.
160
161VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
162-----------------------------------------------------------------------------
163
164Those IOCTLs are used to configure the modules. They require user applications
165to have an in-depth knowledge of the hardware. Most of the fields explanation
166can be found on OMAP's TRMs. The two following fields common to all the above
167configure private IOCTLs require explanation for better understanding as they
168are not part of the TRM.
169
170omap3isp_[h3a_af/h3a_aewb/hist]\_config.buf_size:
171
172The modules handle their buffers internally. The necessary buffer size for the
173module's data output depends on the requested configuration. Although the
174driver supports reconfiguration while streaming, it does not support a
175reconfiguration which requires bigger buffer size than what is already
176internally allocated if the module is enabled. It will return -EBUSY on this
177case. In order to avoid such condition, either disable/reconfigure/enable the
178module or request the necessary buffer size during the first configuration
179while the module is disabled.
180
181The internal buffer size allocation considers the requested configuration's
182minimum buffer size and the value set on buf_size field. If buf_size field is
183out of [minimum, maximum] buffer size range, it's clamped to fit in there.
184The driver then selects the biggest value. The corrected buf_size value is
185written back to user application.
186
187omap3isp_[h3a_af/h3a_aewb/hist]\_config.config_counter:
188
189As the configuration doesn't take effect synchronously to the request, the
190driver must provide a way to track this information to provide more accurate
191data. After a configuration is requested, the config_counter returned to user
192space application will be an unique value associated to that request. When
193user application receives an event for buffer availability or when a new
194buffer is requested, this config_counter is used to match a buffer data and a
195configuration.
196
197VIDIOC_OMAP3ISP_STAT_REQ
198------------------------
199
200Send to user space the oldest data available in the internal buffer queue and
201discards such buffer afterwards. The field omap3isp_stat_data.frame_number
202matches with the video buffer's field_count.
203
204
205References
206----------
207
208.. [#] include/linux/omap3isp.h