Eric Lee / linux-smarc-t335x-v3.2

Download as
Browse Code ยป

Commit e83dd485ed04b21215c1283042e8d4712ab1a675

Authored by Sakari Ailus
Committed by Mauro Carvalho Chehab
1 parent 474966ee01
Exists in master and in 4 other branches v3.2_AM335xPSP_04.06.00.11, v3.2_NEWT335xPSP_04.06.00.11, v3.2_SBC_SMARTMEN, v3.2_SMARCT335xPSP_04.06.00.11

[media] omap3isp: Add documentation 

Add documentation on the OMAP 3 ISP driver. Document the subdevs, V4L2
events and private IOCTLs the driver implements

Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
Signed-off-by: David Cohen <dacohen@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

Showing 1 changed file with 278 additions and 0 deletions Side-by-side Diff

Documentation/video4linux/omap3isp.txt
Diff comments   View file @ e83dd48
  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