Documentation/media/v4l-drivers/omap3isp.rst

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