.. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> OMAP 3 Image Signal Processor (ISP) driver ========================================== Copyright |copy| 2010 Nokia Corporation Copyright |copy| 2009 Texas Instruments, Inc. Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>, Sakari Ailus <sakari.ailus@iki.fi>, David Cohen <dacohen@gmail.com> Events ------ The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and statistics (AEWB, AF and histogram) subdevs. The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS interrupt which is used to signal frame start. Earlier version of this driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is triggered exactly when the reception of the first line of the frame starts in the CCDC module. The event can be subscribed on the CCDC subdev. (When using parallel interface one must pay account to correct configuration of the VS signal polarity. This is automatically correct when using the serial receivers.) Each of the statistics subdevs is able to produce events. An event is generated whenever a statistics buffer can be dequeued by a user space application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available are: - V4L2_EVENT_OMAP3ISP_AEWB - V4L2_EVENT_OMAP3ISP_AF - V4L2_EVENT_OMAP3ISP_HIST The type of the event data is struct omap3isp_stat_event_status for these ioctls. If there is an error calculating the statistics, there will be an event as usual, but no related statistics buffer. In this case omap3isp_stat_event_status.buf_err is set to non-zero. Private IOCTLs -------------- The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where possible and practical. Much of the functions provided by the ISP, however, does not fall under the standard IOCTLs --- gamma tables and configuration of statistics collection are examples of such. In general, there is a private ioctl for configuring each of the blocks containing hardware-dependent functions. The following private IOCTLs are supported: - VIDIOC_OMAP3ISP_CCDC_CFG - VIDIOC_OMAP3ISP_PRV_CFG - VIDIOC_OMAP3ISP_AEWB_CFG - VIDIOC_OMAP3ISP_HIST_CFG - VIDIOC_OMAP3ISP_AF_CFG - VIDIOC_OMAP3ISP_STAT_REQ - VIDIOC_OMAP3ISP_STAT_EN The parameter structures used by these ioctls are described in include/linux/omap3isp.h. The detailed functions of the ISP itself related to a given ISP block is described in the Technical Reference Manuals (TRMs) --- see the end of the document for those. While it is possible to use the ISP driver without any use of these private IOCTLs it is not possible to obtain optimal image quality this way. The AEWB, AF and histogram modules cannot be used without configuring them using the appropriate private IOCTLs. CCDC and preview block IOCTLs ----------------------------- The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to configure, enable and disable functions in the CCDC and preview blocks, respectively. Both IOCTLs control several functions in the blocks they control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG accepts a pointer to struct omap3isp_prev_update_config. The definition of both structures is available in [#]_. The update field in the structures tells whether to update the configuration for the specific function and the flag tells whether to enable or disable the function. The update and flag bit masks accept the following values. Each separate functions in the CCDC and preview blocks is associated with a flag (either disable or enable; part of the flag field in the structure) and a pointer to configuration data for the function. Valid values for the update and flag fields are listed here for VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one function in the same IOCTL call. - OMAP3ISP_CCDC_ALAW - OMAP3ISP_CCDC_LPF - OMAP3ISP_CCDC_BLCLAMP - OMAP3ISP_CCDC_BCOMP - OMAP3ISP_CCDC_FPC - OMAP3ISP_CCDC_CULL - OMAP3ISP_CCDC_CONFIG_LSC - OMAP3ISP_CCDC_TBL_LSC The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here: - OMAP3ISP_PREV_LUMAENH - OMAP3ISP_PREV_INVALAW - OMAP3ISP_PREV_HRZ_MED - OMAP3ISP_PREV_CFA - OMAP3ISP_PREV_CHROMA_SUPP - OMAP3ISP_PREV_WB - OMAP3ISP_PREV_BLKADJ - OMAP3ISP_PREV_RGB2RGB - OMAP3ISP_PREV_COLOR_CONV - OMAP3ISP_PREV_YC_LIMIT - OMAP3ISP_PREV_DEFECT_COR - OMAP3ISP_PREV_GAMMABYPASS - OMAP3ISP_PREV_DRK_FRM_CAPTURE - OMAP3ISP_PREV_DRK_FRM_SUBTRACT - OMAP3ISP_PREV_LENS_SHADING - OMAP3ISP_PREV_NF - OMAP3ISP_PREV_GAMMA The associated configuration pointer for the function may not be NULL when enabling the function. When disabling a function the configuration pointer is ignored. Statistic blocks IOCTLs ----------------------- The statistics subdevs do offer more dynamic configuration options than the other subdevs. They can be enabled, disable and reconfigured when the pipeline is in streaming state. The statistics blocks always get the input image data from the CCDC (as the histogram memory read isn't implemented). The statistics are dequeueable by the user from the statistics subdev nodes using private IOCTLs. The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily reflected by the register level interface offered by the ISP hardware. There are aspects that are purely related to the driver implementation and these are discussed next. VIDIOC_OMAP3ISP_STAT_EN ----------------------- This private IOCTL enables/disables a statistic module. If this request is done before streaming, it will take effect as soon as the pipeline starts to stream. If the pipeline is already streaming, it will take effect as soon as the CCDC becomes idle. VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG ----------------------------------------------------------------------------- Those IOCTLs are used to configure the modules. They require user applications to have an in-depth knowledge of the hardware. Most of the fields explanation can be found on OMAP's TRMs. The two following fields common to all the above configure private IOCTLs require explanation for better understanding as they are not part of the TRM. omap3isp_[h3a_af/h3a_aewb/hist]\_config.buf_size: The modules handle their buffers internally. The necessary buffer size for the module's data output depends on the requested configuration. Although the driver supports reconfiguration while streaming, it does not support a reconfiguration which requires bigger buffer size than what is already internally allocated if the module is enabled. It will return -EBUSY on this case. In order to avoid such condition, either disable/reconfigure/enable the module or request the necessary buffer size during the first configuration while the module is disabled. The internal buffer size allocation considers the requested configuration's minimum buffer size and the value set on buf_size field. If buf_size field is out of [minimum, maximum] buffer size range, it's clamped to fit in there. The driver then selects the biggest value. The corrected buf_size value is written back to user application. omap3isp_[h3a_af/h3a_aewb/hist]\_config.config_counter: As the configuration doesn't take effect synchronously to the request, the driver must provide a way to track this information to provide more accurate data. After a configuration is requested, the config_counter returned to user space application will be an unique value associated to that request. When user application receives an event for buffer availability or when a new buffer is requested, this config_counter is used to match a buffer data and a configuration. VIDIOC_OMAP3ISP_STAT_REQ ------------------------ Send to user space the oldest data available in the internal buffer queue and discards such buffer afterwards. The field omap3isp_stat_data.frame_number matches with the video buffer's field_count. References ---------- .. [#] include/linux/omap3isp.h