0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 .. include:: <isonum.txt>
0004
0005 OMAP 3 Image Signal Processor (ISP) driver
0006 ==========================================
0007
0008 Copyright |copy| 2010 Nokia Corporation
0009
0010 Copyright |copy| 2009 Texas Instruments, Inc.
0011
0012 Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
0013 Sakari Ailus <sakari.ailus@iki.fi>, David Cohen <dacohen@gmail.com>
0014
0015
0016 Events
0017 ------
0018
0019 The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and
0020 statistics (AEWB, AF and histogram) subdevs.
0021
0022 The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS
0023 interrupt which is used to signal frame start. Earlier version of this
0024 driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is
0025 triggered exactly when the reception of the first line of the frame starts
0026 in the CCDC module. The event can be subscribed on the CCDC subdev.
0027
0028 (When using parallel interface one must pay account to correct configuration
0029 of the VS signal polarity. This is automatically correct when using the serial
0030 receivers.)
0031
0032 Each of the statistics subdevs is able to produce events. An event is
0033 generated whenever a statistics buffer can be dequeued by a user space
0034 application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available
0035 are:
0036
0037 - V4L2_EVENT_OMAP3ISP_AEWB
0038 - V4L2_EVENT_OMAP3ISP_AF
0039 - V4L2_EVENT_OMAP3ISP_HIST
0040
0041 The type of the event data is struct omap3isp_stat_event_status for these
0042 ioctls. If there is an error calculating the statistics, there will be an
0043 event as usual, but no related statistics buffer. In this case
0044 omap3isp_stat_event_status.buf_err is set to non-zero.
0045
0046
0047 Private IOCTLs
0048 --------------
0049
0050 The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where
0051 possible and practical. Much of the functions provided by the ISP, however,
0052 does not fall under the standard IOCTLs --- gamma tables and configuration of
0053 statistics collection are examples of such.
0054
0055 In general, there is a private ioctl for configuring each of the blocks
0056 containing hardware-dependent functions.
0057
0058 The following private IOCTLs are supported:
0059
0060 - VIDIOC_OMAP3ISP_CCDC_CFG
0061 - VIDIOC_OMAP3ISP_PRV_CFG
0062 - VIDIOC_OMAP3ISP_AEWB_CFG
0063 - VIDIOC_OMAP3ISP_HIST_CFG
0064 - VIDIOC_OMAP3ISP_AF_CFG
0065 - VIDIOC_OMAP3ISP_STAT_REQ
0066 - VIDIOC_OMAP3ISP_STAT_EN
0067
0068 The parameter structures used by these ioctls are described in
0069 include/linux/omap3isp.h. The detailed functions of the ISP itself related to
0070 a given ISP block is described in the Technical Reference Manuals (TRMs) ---
0071 see the end of the document for those.
0072
0073 While it is possible to use the ISP driver without any use of these private
0074 IOCTLs it is not possible to obtain optimal image quality this way. The AEWB,
0075 AF and histogram modules cannot be used without configuring them using the
0076 appropriate private IOCTLs.
0077
0078
0079 CCDC and preview block IOCTLs
0080 -----------------------------
0081
0082 The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to
0083 configure, enable and disable functions in the CCDC and preview blocks,
0084 respectively. Both IOCTLs control several functions in the blocks they
0085 control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct
0086 omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG
0087 accepts a pointer to struct omap3isp_prev_update_config. The definition of
0088 both structures is available in [#]_.
0089
0090 The update field in the structures tells whether to update the configuration
0091 for the specific function and the flag tells whether to enable or disable the
0092 function.
0093
0094 The update and flag bit masks accept the following values. Each separate
0095 functions in the CCDC and preview blocks is associated with a flag (either
0096 disable or enable; part of the flag field in the structure) and a pointer to
0097 configuration data for the function.
0098
0099 Valid values for the update and flag fields are listed here for
0100 VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one
0101 function in the same IOCTL call.
0102
0103 - OMAP3ISP_CCDC_ALAW
0104 - OMAP3ISP_CCDC_LPF
0105 - OMAP3ISP_CCDC_BLCLAMP
0106 - OMAP3ISP_CCDC_BCOMP
0107 - OMAP3ISP_CCDC_FPC
0108 - OMAP3ISP_CCDC_CULL
0109 - OMAP3ISP_CCDC_CONFIG_LSC
0110 - OMAP3ISP_CCDC_TBL_LSC
0111
0112 The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here:
0113
0114 - OMAP3ISP_PREV_LUMAENH
0115 - OMAP3ISP_PREV_INVALAW
0116 - OMAP3ISP_PREV_HRZ_MED
0117 - OMAP3ISP_PREV_CFA
0118 - OMAP3ISP_PREV_CHROMA_SUPP
0119 - OMAP3ISP_PREV_WB
0120 - OMAP3ISP_PREV_BLKADJ
0121 - OMAP3ISP_PREV_RGB2RGB
0122 - OMAP3ISP_PREV_COLOR_CONV
0123 - OMAP3ISP_PREV_YC_LIMIT
0124 - OMAP3ISP_PREV_DEFECT_COR
0125 - OMAP3ISP_PREV_GAMMABYPASS
0126 - OMAP3ISP_PREV_DRK_FRM_CAPTURE
0127 - OMAP3ISP_PREV_DRK_FRM_SUBTRACT
0128 - OMAP3ISP_PREV_LENS_SHADING
0129 - OMAP3ISP_PREV_NF
0130 - OMAP3ISP_PREV_GAMMA
0131
0132 The associated configuration pointer for the function may not be NULL when
0133 enabling the function. When disabling a function the configuration pointer is
0134 ignored.
0135
0136
0137 Statistic blocks IOCTLs
0138 -----------------------
0139
0140 The statistics subdevs do offer more dynamic configuration options than the
0141 other subdevs. They can be enabled, disable and reconfigured when the pipeline
0142 is in streaming state.
0143
0144 The statistics blocks always get the input image data from the CCDC (as the
0145 histogram memory read isn't implemented). The statistics are dequeueable by
0146 the user from the statistics subdev nodes using private IOCTLs.
0147
0148 The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily
0149 reflected by the register level interface offered by the ISP hardware. There
0150 are aspects that are purely related to the driver implementation and these are
0151 discussed next.
0152
0153 VIDIOC_OMAP3ISP_STAT_EN
0154 -----------------------
0155
0156 This private IOCTL enables/disables a statistic module. If this request is
0157 done before streaming, it will take effect as soon as the pipeline starts to
0158 stream. If the pipeline is already streaming, it will take effect as soon as
0159 the CCDC becomes idle.
0160
0161 VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
0162 -----------------------------------------------------------------------------
0163
0164 Those IOCTLs are used to configure the modules. They require user applications
0165 to have an in-depth knowledge of the hardware. Most of the fields explanation
0166 can be found on OMAP's TRMs. The two following fields common to all the above
0167 configure private IOCTLs require explanation for better understanding as they
0168 are not part of the TRM.
0169
0170 omap3isp_[h3a_af/h3a_aewb/hist]\_config.buf_size:
0171
0172 The modules handle their buffers internally. The necessary buffer size for the
0173 module's data output depends on the requested configuration. Although the
0174 driver supports reconfiguration while streaming, it does not support a
0175 reconfiguration which requires bigger buffer size than what is already
0176 internally allocated if the module is enabled. It will return -EBUSY on this
0177 case. In order to avoid such condition, either disable/reconfigure/enable the
0178 module or request the necessary buffer size during the first configuration
0179 while the module is disabled.
0180
0181 The internal buffer size allocation considers the requested configuration's
0182 minimum buffer size and the value set on buf_size field. If buf_size field is
0183 out of [minimum, maximum] buffer size range, it's clamped to fit in there.
0184 The driver then selects the biggest value. The corrected buf_size value is
0185 written back to user application.
0186
0187 omap3isp_[h3a_af/h3a_aewb/hist]\_config.config_counter:
0188
0189 As the configuration doesn't take effect synchronously to the request, the
0190 driver must provide a way to track this information to provide more accurate
0191 data. After a configuration is requested, the config_counter returned to user
0192 space application will be an unique value associated to that request. When
0193 user application receives an event for buffer availability or when a new
0194 buffer is requested, this config_counter is used to match a buffer data and a
0195 configuration.
0196
0197 VIDIOC_OMAP3ISP_STAT_REQ
0198 ------------------------
0199
0200 Send to user space the oldest data available in the internal buffer queue and
0201 discards such buffer afterwards. The field omap3isp_stat_data.frame_number
0202 matches with the video buffer's field_count.
0203
0204
0205 References
0206 ----------
0207
0208 .. [#] include/linux/omap3isp.h
