209 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3.. include:: <isonum.txt>4 5OMAP 3 Image Signal Processor (ISP) driver6==========================================7 8Copyright |copy| 2010 Nokia Corporation9 10Copyright |copy| 2009 Texas Instruments, Inc.11 12Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,13Sakari Ailus <sakari.ailus@iki.fi>, David Cohen <dacohen@gmail.com>14 15 16Events17------18 19The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and20statistics (AEWB, AF and histogram) subdevs.21 22The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS23interrupt which is used to signal frame start. Earlier version of this24driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is25triggered exactly when the reception of the first line of the frame starts26in the CCDC module. The event can be subscribed on the CCDC subdev.27 28(When using parallel interface one must pay account to correct configuration29of the VS signal polarity. This is automatically correct when using the serial30receivers.)31 32Each of the statistics subdevs is able to produce events. An event is33generated whenever a statistics buffer can be dequeued by a user space34application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available35are:36 37- V4L2_EVENT_OMAP3ISP_AEWB38- V4L2_EVENT_OMAP3ISP_AF39- V4L2_EVENT_OMAP3ISP_HIST40 41The type of the event data is struct omap3isp_stat_event_status for these42ioctls. If there is an error calculating the statistics, there will be an43event as usual, but no related statistics buffer. In this case44omap3isp_stat_event_status.buf_err is set to non-zero.45 46 47Private IOCTLs48--------------49 50The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where51possible and practical. Much of the functions provided by the ISP, however,52does not fall under the standard IOCTLs --- gamma tables and configuration of53statistics collection are examples of such.54 55In general, there is a private ioctl for configuring each of the blocks56containing hardware-dependent functions.57 58The following private IOCTLs are supported:59 60- VIDIOC_OMAP3ISP_CCDC_CFG61- VIDIOC_OMAP3ISP_PRV_CFG62- VIDIOC_OMAP3ISP_AEWB_CFG63- VIDIOC_OMAP3ISP_HIST_CFG64- VIDIOC_OMAP3ISP_AF_CFG65- VIDIOC_OMAP3ISP_STAT_REQ66- VIDIOC_OMAP3ISP_STAT_EN67 68The parameter structures used by these ioctls are described in69include/linux/omap3isp.h. The detailed functions of the ISP itself related to70a given ISP block is described in the Technical Reference Manuals (TRMs) ---71see the end of the document for those.72 73While it is possible to use the ISP driver without any use of these private74IOCTLs it is not possible to obtain optimal image quality this way. The AEWB,75AF and histogram modules cannot be used without configuring them using the76appropriate private IOCTLs.77 78 79CCDC and preview block IOCTLs80-----------------------------81 82The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to83configure, enable and disable functions in the CCDC and preview blocks,84respectively. Both IOCTLs control several functions in the blocks they85control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct86omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG87accepts a pointer to struct omap3isp_prev_update_config. The definition of88both structures is available in [#]_.89 90The update field in the structures tells whether to update the configuration91for the specific function and the flag tells whether to enable or disable the92function.93 94The update and flag bit masks accept the following values. Each separate95functions in the CCDC and preview blocks is associated with a flag (either96disable or enable; part of the flag field in the structure) and a pointer to97configuration data for the function.98 99Valid values for the update and flag fields are listed here for100VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one101function in the same IOCTL call.102 103- OMAP3ISP_CCDC_ALAW104- OMAP3ISP_CCDC_LPF105- OMAP3ISP_CCDC_BLCLAMP106- OMAP3ISP_CCDC_BCOMP107- OMAP3ISP_CCDC_FPC108- OMAP3ISP_CCDC_CULL109- OMAP3ISP_CCDC_CONFIG_LSC110- OMAP3ISP_CCDC_TBL_LSC111 112The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here:113 114- OMAP3ISP_PREV_LUMAENH115- OMAP3ISP_PREV_INVALAW116- OMAP3ISP_PREV_HRZ_MED117- OMAP3ISP_PREV_CFA118- OMAP3ISP_PREV_CHROMA_SUPP119- OMAP3ISP_PREV_WB120- OMAP3ISP_PREV_BLKADJ121- OMAP3ISP_PREV_RGB2RGB122- OMAP3ISP_PREV_COLOR_CONV123- OMAP3ISP_PREV_YC_LIMIT124- OMAP3ISP_PREV_DEFECT_COR125- OMAP3ISP_PREV_GAMMABYPASS126- OMAP3ISP_PREV_DRK_FRM_CAPTURE127- OMAP3ISP_PREV_DRK_FRM_SUBTRACT128- OMAP3ISP_PREV_LENS_SHADING129- OMAP3ISP_PREV_NF130- OMAP3ISP_PREV_GAMMA131 132The associated configuration pointer for the function may not be NULL when133enabling the function. When disabling a function the configuration pointer is134ignored.135 136 137Statistic blocks IOCTLs138-----------------------139 140The statistics subdevs do offer more dynamic configuration options than the141other subdevs. They can be enabled, disable and reconfigured when the pipeline142is in streaming state.143 144The statistics blocks always get the input image data from the CCDC (as the145histogram memory read isn't implemented). The statistics are dequeueable by146the user from the statistics subdev nodes using private IOCTLs.147 148The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily149reflected by the register level interface offered by the ISP hardware. There150are aspects that are purely related to the driver implementation and these are151discussed next.152 153VIDIOC_OMAP3ISP_STAT_EN154-----------------------155 156This private IOCTL enables/disables a statistic module. If this request is157done before streaming, it will take effect as soon as the pipeline starts to158stream. If the pipeline is already streaming, it will take effect as soon as159the CCDC becomes idle.160 161VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG162-----------------------------------------------------------------------------163 164Those IOCTLs are used to configure the modules. They require user applications165to have an in-depth knowledge of the hardware. Most of the fields explanation166can be found on OMAP's TRMs. The two following fields common to all the above167configure private IOCTLs require explanation for better understanding as they168are not part of the TRM.169 170omap3isp_[h3a_af/h3a_aewb/hist]\_config.buf_size:171 172The modules handle their buffers internally. The necessary buffer size for the173module's data output depends on the requested configuration. Although the174driver supports reconfiguration while streaming, it does not support a175reconfiguration which requires bigger buffer size than what is already176internally allocated if the module is enabled. It will return -EBUSY on this177case. In order to avoid such condition, either disable/reconfigure/enable the178module or request the necessary buffer size during the first configuration179while the module is disabled.180 181The internal buffer size allocation considers the requested configuration's182minimum buffer size and the value set on buf_size field. If buf_size field is183out of [minimum, maximum] buffer size range, it's clamped to fit in there.184The driver then selects the biggest value. The corrected buf_size value is185written back to user application.186 187omap3isp_[h3a_af/h3a_aewb/hist]\_config.config_counter:188 189As the configuration doesn't take effect synchronously to the request, the190driver must provide a way to track this information to provide more accurate191data. After a configuration is requested, the config_counter returned to user192space application will be an unique value associated to that request. When193user application receives an event for buffer availability or when a new194buffer is requested, this config_counter is used to match a buffer data and a195configuration.196 197VIDIOC_OMAP3ISP_STAT_REQ198------------------------199 200Send to user space the oldest data available in the internal buffer queue and201discards such buffer afterwards. The field omap3isp_stat_data.frame_number202matches with the video buffer's field_count.203 204 205References206----------207 208.. [#] include/linux/omap3isp.h209