Documentation/video4linux/omap3isp.txt

   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