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