Documentation/userspace-api/media/drivers/omap3isp-uapi.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 Events
  17 ------
  18
  19 The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and
  20 statistics (AEWB, AF and histogram) subdevs.
  21
  22 The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS
  23 interrupt which is used to signal frame start. Earlier version of this
  24 driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is
  25 triggered exactly when the reception of the first line of the frame starts
  26 in 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
  29 of the VS signal polarity. This is automatically correct when using the serial
  30 receivers.)
  31
  32 Each of the statistics subdevs is able to produce events. An event is
  33 generated whenever a statistics buffer can be dequeued by a user space
  34 application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available
  35 are:
  36
  37 - V4L2_EVENT_OMAP3ISP_AEWB
  38 - V4L2_EVENT_OMAP3ISP_AF
  39 - V4L2_EVENT_OMAP3ISP_HIST
  40
  41 The type of the event data is struct omap3isp_stat_event_status for these
  42 ioctls. If there is an error calculating the statistics, there will be an
  43 event as usual, but no related statistics buffer. In this case
  44 omap3isp_stat_event_status.buf_err is set to non-zero.
  45
  46
  47 Private IOCTLs
  48 --------------
  49
  50 The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where
  51 possible and practical. Much of the functions provided by the ISP, however,
  52 does not fall under the standard IOCTLs --- gamma tables and configuration of
  53 statistics collection are examples of such.
  54
  55 In general, there is a private ioctl for configuring each of the blocks
  56 containing hardware-dependent functions.
  57
  58 The 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
  68 The parameter structures used by these ioctls are described in
  69 include/linux/omap3isp.h. The detailed functions of the ISP itself related to
  70 a given ISP block is described in the Technical Reference Manuals (TRMs) ---
  71 see the end of the document for those.
  72
  73 While it is possible to use the ISP driver without any use of these private
  74 IOCTLs it is not possible to obtain optimal image quality this way. The AEWB,
  75 AF and histogram modules cannot be used without configuring them using the
  76 appropriate private IOCTLs.
  77
  78
  79 CCDC and preview block IOCTLs
  80 -----------------------------
  81
  82 The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to
  83 configure, enable and disable functions in the CCDC and preview blocks,
  84 respectively. Both IOCTLs control several functions in the blocks they
  85 control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct
  86 omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG
  87 accepts a pointer to struct omap3isp_prev_update_config. The definition of
  88 both structures is available in [#]_.
  89
  90 The update field in the structures tells whether to update the configuration
  91 for the specific function and the flag tells whether to enable or disable the
  92 function.
  93
  94 The update and flag bit masks accept the following values. Each separate
  95 functions in the CCDC and preview blocks is associated with a flag (either
  96 disable or enable; part of the flag field in the structure) and a pointer to
  97 configuration data for the function.
  98
  99 Valid values for the update and flag fields are listed here for
 100 VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one
 101 function 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
 112 The 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
 132 The associated configuration pointer for the function may not be NULL when
 133 enabling the function. When disabling a function the configuration pointer is
 134 ignored.
 135
 136
 137 Statistic blocks IOCTLs
 138 -----------------------
 139
 140 The statistics subdevs do offer more dynamic configuration options than the
 141 other subdevs. They can be enabled, disable and reconfigured when the pipeline
 142 is in streaming state.
 143
 144 The statistics blocks always get the input image data from the CCDC (as the
 145 histogram memory read isn't implemented). The statistics are dequeueable by
 146 the user from the statistics subdev nodes using private IOCTLs.
 147
 148 The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily
 149 reflected by the register level interface offered by the ISP hardware. There
 150 are aspects that are purely related to the driver implementation and these are
 151 discussed next.
 152
 153 VIDIOC_OMAP3ISP_STAT_EN
 154 -----------------------
 155
 156 This private IOCTL enables/disables a statistic module. If this request is
 157 done before streaming, it will take effect as soon as the pipeline starts to
 158 stream.  If the pipeline is already streaming, it will take effect as soon as
 159 the CCDC becomes idle.
 160
 161 VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
 162 -----------------------------------------------------------------------------
 163
 164 Those IOCTLs are used to configure the modules. They require user applications
 165 to have an in-depth knowledge of the hardware. Most of the fields explanation
 166 can be found on OMAP's TRMs. The two following fields common to all the above
 167 configure private IOCTLs require explanation for better understanding as they
 168 are not part of the TRM.
 169
 170 omap3isp_[h3a_af/h3a_aewb/hist]\_config.buf_size:
 171
 172 The modules handle their buffers internally. The necessary buffer size for the
 173 module's data output depends on the requested configuration. Although the
 174 driver supports reconfiguration while streaming, it does not support a
 175 reconfiguration which requires bigger buffer size than what is already
 176 internally allocated if the module is enabled. It will return -EBUSY on this
 177 case. In order to avoid such condition, either disable/reconfigure/enable the
 178 module or request the necessary buffer size during the first configuration
 179 while the module is disabled.
 180
 181 The internal buffer size allocation considers the requested configuration's
 182 minimum buffer size and the value set on buf_size field. If buf_size field is
 183 out of [minimum, maximum] buffer size range, it's clamped to fit in there.
 184 The driver then selects the biggest value. The corrected buf_size value is
 185 written back to user application.
 186
 187 omap3isp_[h3a_af/h3a_aewb/hist]\_config.config_counter:
 188
 189 As the configuration doesn't take effect synchronously to the request, the
 190 driver must provide a way to track this information to provide more accurate
 191 data. After a configuration is requested, the config_counter returned to user
 192 space application will be an unique value associated to that request. When
 193 user application receives an event for buffer availability or when a new
 194 buffer is requested, this config_counter is used to match a buffer data and a
 195 configuration.
 196
 197 VIDIOC_OMAP3ISP_STAT_REQ
 198 ------------------------
 199
 200 Send to user space the oldest data available in the internal buffer queue and
 201 discards such buffer afterwards. The field omap3isp_stat_data.frame_number
 202 matches with the video buffer's field_count.
 203
 204
 205 References
 206 ----------
 207
 208 .. [#] include/linux/omap3isp.h