linux/Documentation/video4linux/omap3isp.txt
<<
>>
Prefs
   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_FRAME_SYNC type event on HS_VS
  74interrupt which is used to signal frame start. Earlier version of this
  75driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is
  76triggered exactly when the reception of the first line of the frame starts
  77in the CCDC module. The event can be subscribed on the CCDC subdev.
  78
  79(When using parallel interface one must pay account to correct configuration
  80of the VS signal polarity. This is automatically correct when using the serial
  81receivers.)
  82
  83Each of the statistics subdevs is able to produce events. An event is
  84generated whenever a statistics buffer can be dequeued by a user space
  85application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available
  86are:
  87
  88        V4L2_EVENT_OMAP3ISP_AEWB
  89        V4L2_EVENT_OMAP3ISP_AF
  90        V4L2_EVENT_OMAP3ISP_HIST
  91
  92The type of the event data is struct omap3isp_stat_event_status for these
  93ioctls. If there is an error calculating the statistics, there will be an
  94event as usual, but no related statistics buffer. In this case
  95omap3isp_stat_event_status.buf_err is set to non-zero.
  96
  97
  98Private IOCTLs
  99==============
 100
 101The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where
 102possible and practical. Much of the functions provided by the ISP, however,
 103does not fall under the standard IOCTLs --- gamma tables and configuration of
 104statistics collection are examples of such.
 105
 106In general, there is a private ioctl for configuring each of the blocks
 107containing hardware-dependent functions.
 108
 109The following private IOCTLs are supported:
 110
 111        VIDIOC_OMAP3ISP_CCDC_CFG
 112        VIDIOC_OMAP3ISP_PRV_CFG
 113        VIDIOC_OMAP3ISP_AEWB_CFG
 114        VIDIOC_OMAP3ISP_HIST_CFG
 115        VIDIOC_OMAP3ISP_AF_CFG
 116        VIDIOC_OMAP3ISP_STAT_REQ
 117        VIDIOC_OMAP3ISP_STAT_EN
 118
 119The parameter structures used by these ioctls are described in
 120include/linux/omap3isp.h. The detailed functions of the ISP itself related to
 121a given ISP block is described in the Technical Reference Manuals (TRMs) ---
 122see the end of the document for those.
 123
 124While it is possible to use the ISP driver without any use of these private
 125IOCTLs it is not possible to obtain optimal image quality this way. The AEWB,
 126AF and histogram modules cannot be used without configuring them using the
 127appropriate private IOCTLs.
 128
 129
 130CCDC and preview block IOCTLs
 131=============================
 132
 133The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to
 134configure, enable and disable functions in the CCDC and preview blocks,
 135respectively. Both IOCTLs control several functions in the blocks they
 136control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct
 137omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG
 138accepts a pointer to struct omap3isp_prev_update_config. The definition of
 139both structures is available in [1].
 140
 141The update field in the structures tells whether to update the configuration
 142for the specific function and the flag tells whether to enable or disable the
 143function.
 144
 145The update and flag bit masks accept the following values. Each separate
 146functions in the CCDC and preview blocks is associated with a flag (either
 147disable or enable; part of the flag field in the structure) and a pointer to
 148configuration data for the function.
 149
 150Valid values for the update and flag fields are listed here for
 151VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one
 152function in the same IOCTL call.
 153
 154        OMAP3ISP_CCDC_ALAW
 155        OMAP3ISP_CCDC_LPF
 156        OMAP3ISP_CCDC_BLCLAMP
 157        OMAP3ISP_CCDC_BCOMP
 158        OMAP3ISP_CCDC_FPC
 159        OMAP3ISP_CCDC_CULL
 160        OMAP3ISP_CCDC_CONFIG_LSC
 161        OMAP3ISP_CCDC_TBL_LSC
 162
 163The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here:
 164
 165        OMAP3ISP_PREV_LUMAENH
 166        OMAP3ISP_PREV_INVALAW
 167        OMAP3ISP_PREV_HRZ_MED
 168        OMAP3ISP_PREV_CFA
 169        OMAP3ISP_PREV_CHROMA_SUPP
 170        OMAP3ISP_PREV_WB
 171        OMAP3ISP_PREV_BLKADJ
 172        OMAP3ISP_PREV_RGB2RGB
 173        OMAP3ISP_PREV_COLOR_CONV
 174        OMAP3ISP_PREV_YC_LIMIT
 175        OMAP3ISP_PREV_DEFECT_COR
 176        OMAP3ISP_PREV_GAMMABYPASS
 177        OMAP3ISP_PREV_DRK_FRM_CAPTURE
 178        OMAP3ISP_PREV_DRK_FRM_SUBTRACT
 179        OMAP3ISP_PREV_LENS_SHADING
 180        OMAP3ISP_PREV_NF
 181        OMAP3ISP_PREV_GAMMA
 182
 183The associated configuration pointer for the function may not be NULL when
 184enabling the function. When disabling a function the configuration pointer is
 185ignored.
 186
 187
 188Statistic blocks IOCTLs
 189=======================
 190
 191The statistics subdevs do offer more dynamic configuration options than the
 192other subdevs. They can be enabled, disable and reconfigured when the pipeline
 193is in streaming state.
 194
 195The statistics blocks always get the input image data from the CCDC (as the
 196histogram memory read isn't implemented). The statistics are dequeueable by
 197the user from the statistics subdev nodes using private IOCTLs.
 198
 199The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily
 200reflected by the register level interface offered by the ISP hardware. There
 201are aspects that are purely related to the driver implementation and these are
 202discussed next.
 203
 204VIDIOC_OMAP3ISP_STAT_EN
 205-----------------------
 206
 207This private IOCTL enables/disables a statistic module. If this request is
 208done before streaming, it will take effect as soon as the pipeline starts to
 209stream.  If the pipeline is already streaming, it will take effect as soon as
 210the CCDC becomes idle.
 211
 212VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
 213-----------------------------------------------------------------------------
 214
 215Those IOCTLs are used to configure the modules. They require user applications
 216to have an in-depth knowledge of the hardware. Most of the fields explanation
 217can be found on OMAP's TRMs. The two following fields common to all the above
 218configure private IOCTLs require explanation for better understanding as they
 219are not part of the TRM.
 220
 221omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size:
 222
 223The modules handle their buffers internally. The necessary buffer size for the
 224module's data output depends on the requested configuration. Although the
 225driver supports reconfiguration while streaming, it does not support a
 226reconfiguration which requires bigger buffer size than what is already
 227internally allocated if the module is enabled. It will return -EBUSY on this
 228case. In order to avoid such condition, either disable/reconfigure/enable the
 229module or request the necessary buffer size during the first configuration
 230while the module is disabled.
 231
 232The internal buffer size allocation considers the requested configuration's
 233minimum buffer size and the value set on buf_size field. If buf_size field is
 234out of [minimum, maximum] buffer size range, it's clamped to fit in there.
 235The driver then selects the biggest value. The corrected buf_size value is
 236written back to user application.
 237
 238omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter:
 239
 240As the configuration doesn't take effect synchronously to the request, the
 241driver must provide a way to track this information to provide more accurate
 242data. After a configuration is requested, the config_counter returned to user
 243space application will be an unique value associated to that request. When
 244user application receives an event for buffer availability or when a new
 245buffer is requested, this config_counter is used to match a buffer data and a
 246configuration.
 247
 248VIDIOC_OMAP3ISP_STAT_REQ
 249------------------------
 250
 251Send to user space the oldest data available in the internal buffer queue and
 252discards such buffer afterwards. The field omap3isp_stat_data.frame_number
 253matches with the video buffer's field_count.
 254
 255
 256Technical reference manuals (TRMs) and other documentation
 257==========================================================
 258
 259OMAP 3430 TRM:
 260<URL:http://focus.ti.com/pdfs/wtbu/OMAP34xx_ES3.1.x_PUBLIC_TRM_vZM.zip>
 261Referenced 2011-03-05.
 262
 263OMAP 35xx TRM:
 264<URL:http://www.ti.com/litv/pdf/spruf98o> Referenced 2011-03-05.
 265
 266OMAP 3630 TRM:
 267<URL:http://focus.ti.com/pdfs/wtbu/OMAP36xx_ES1.x_PUBLIC_TRM_vQ.zip>
 268Referenced 2011-03-05.
 269
 270DM 3730 TRM:
 271<URL:http://www.ti.com/litv/pdf/sprugn4h> Referenced 2011-03-06.
 272
 273
 274References
 275==========
 276
 277[1] include/linux/omap3isp.h
 278
 279[2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
 280
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.