1*b3634386SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2*b3634386SMauro Carvalho Chehab 3*b3634386SMauro Carvalho Chehab.. include:: <isonum.txt> 4*b3634386SMauro Carvalho Chehab 5*b3634386SMauro Carvalho ChehabOMAP 3 Image Signal Processor (ISP) driver 6*b3634386SMauro Carvalho Chehab========================================== 7*b3634386SMauro Carvalho Chehab 8*b3634386SMauro Carvalho ChehabCopyright |copy| 2010 Nokia Corporation 9*b3634386SMauro Carvalho Chehab 10*b3634386SMauro Carvalho ChehabCopyright |copy| 2009 Texas Instruments, Inc. 11*b3634386SMauro Carvalho Chehab 12*b3634386SMauro Carvalho ChehabContacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>, 13*b3634386SMauro Carvalho ChehabSakari Ailus <sakari.ailus@iki.fi>, David Cohen <dacohen@gmail.com> 14*b3634386SMauro Carvalho Chehab 15*b3634386SMauro Carvalho Chehab 16*b3634386SMauro Carvalho ChehabEvents 17*b3634386SMauro Carvalho Chehab------ 18*b3634386SMauro Carvalho Chehab 19*b3634386SMauro Carvalho ChehabThe OMAP 3 ISP driver does support the V4L2 event interface on CCDC and 20*b3634386SMauro Carvalho Chehabstatistics (AEWB, AF and histogram) subdevs. 21*b3634386SMauro Carvalho Chehab 22*b3634386SMauro Carvalho ChehabThe CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS 23*b3634386SMauro Carvalho Chehabinterrupt which is used to signal frame start. Earlier version of this 24*b3634386SMauro Carvalho Chehabdriver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is 25*b3634386SMauro Carvalho Chehabtriggered exactly when the reception of the first line of the frame starts 26*b3634386SMauro Carvalho Chehabin the CCDC module. The event can be subscribed on the CCDC subdev. 27*b3634386SMauro Carvalho Chehab 28*b3634386SMauro Carvalho Chehab(When using parallel interface one must pay account to correct configuration 29*b3634386SMauro Carvalho Chehabof the VS signal polarity. This is automatically correct when using the serial 30*b3634386SMauro Carvalho Chehabreceivers.) 31*b3634386SMauro Carvalho Chehab 32*b3634386SMauro Carvalho ChehabEach of the statistics subdevs is able to produce events. An event is 33*b3634386SMauro Carvalho Chehabgenerated whenever a statistics buffer can be dequeued by a user space 34*b3634386SMauro Carvalho Chehabapplication using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available 35*b3634386SMauro Carvalho Chehabare: 36*b3634386SMauro Carvalho Chehab 37*b3634386SMauro Carvalho Chehab- V4L2_EVENT_OMAP3ISP_AEWB 38*b3634386SMauro Carvalho Chehab- V4L2_EVENT_OMAP3ISP_AF 39*b3634386SMauro Carvalho Chehab- V4L2_EVENT_OMAP3ISP_HIST 40*b3634386SMauro Carvalho Chehab 41*b3634386SMauro Carvalho ChehabThe type of the event data is struct omap3isp_stat_event_status for these 42*b3634386SMauro Carvalho Chehabioctls. If there is an error calculating the statistics, there will be an 43*b3634386SMauro Carvalho Chehabevent as usual, but no related statistics buffer. In this case 44*b3634386SMauro Carvalho Chehabomap3isp_stat_event_status.buf_err is set to non-zero. 45*b3634386SMauro Carvalho Chehab 46*b3634386SMauro Carvalho Chehab 47*b3634386SMauro Carvalho ChehabPrivate IOCTLs 48*b3634386SMauro Carvalho Chehab-------------- 49*b3634386SMauro Carvalho Chehab 50*b3634386SMauro Carvalho ChehabThe OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where 51*b3634386SMauro Carvalho Chehabpossible and practical. Much of the functions provided by the ISP, however, 52*b3634386SMauro Carvalho Chehabdoes not fall under the standard IOCTLs --- gamma tables and configuration of 53*b3634386SMauro Carvalho Chehabstatistics collection are examples of such. 54*b3634386SMauro Carvalho Chehab 55*b3634386SMauro Carvalho ChehabIn general, there is a private ioctl for configuring each of the blocks 56*b3634386SMauro Carvalho Chehabcontaining hardware-dependent functions. 57*b3634386SMauro Carvalho Chehab 58*b3634386SMauro Carvalho ChehabThe following private IOCTLs are supported: 59*b3634386SMauro Carvalho Chehab 60*b3634386SMauro Carvalho Chehab- VIDIOC_OMAP3ISP_CCDC_CFG 61*b3634386SMauro Carvalho Chehab- VIDIOC_OMAP3ISP_PRV_CFG 62*b3634386SMauro Carvalho Chehab- VIDIOC_OMAP3ISP_AEWB_CFG 63*b3634386SMauro Carvalho Chehab- VIDIOC_OMAP3ISP_HIST_CFG 64*b3634386SMauro Carvalho Chehab- VIDIOC_OMAP3ISP_AF_CFG 65*b3634386SMauro Carvalho Chehab- VIDIOC_OMAP3ISP_STAT_REQ 66*b3634386SMauro Carvalho Chehab- VIDIOC_OMAP3ISP_STAT_EN 67*b3634386SMauro Carvalho Chehab 68*b3634386SMauro Carvalho ChehabThe parameter structures used by these ioctls are described in 69*b3634386SMauro Carvalho Chehabinclude/linux/omap3isp.h. The detailed functions of the ISP itself related to 70*b3634386SMauro Carvalho Chehaba given ISP block is described in the Technical Reference Manuals (TRMs) --- 71*b3634386SMauro Carvalho Chehabsee the end of the document for those. 72*b3634386SMauro Carvalho Chehab 73*b3634386SMauro Carvalho ChehabWhile it is possible to use the ISP driver without any use of these private 74*b3634386SMauro Carvalho ChehabIOCTLs it is not possible to obtain optimal image quality this way. The AEWB, 75*b3634386SMauro Carvalho ChehabAF and histogram modules cannot be used without configuring them using the 76*b3634386SMauro Carvalho Chehabappropriate private IOCTLs. 77*b3634386SMauro Carvalho Chehab 78*b3634386SMauro Carvalho Chehab 79*b3634386SMauro Carvalho ChehabCCDC and preview block IOCTLs 80*b3634386SMauro Carvalho Chehab----------------------------- 81*b3634386SMauro Carvalho Chehab 82*b3634386SMauro Carvalho ChehabThe VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to 83*b3634386SMauro Carvalho Chehabconfigure, enable and disable functions in the CCDC and preview blocks, 84*b3634386SMauro Carvalho Chehabrespectively. Both IOCTLs control several functions in the blocks they 85*b3634386SMauro Carvalho Chehabcontrol. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct 86*b3634386SMauro Carvalho Chehabomap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG 87*b3634386SMauro Carvalho Chehabaccepts a pointer to struct omap3isp_prev_update_config. The definition of 88*b3634386SMauro Carvalho Chehabboth structures is available in [#]_. 89*b3634386SMauro Carvalho Chehab 90*b3634386SMauro Carvalho ChehabThe update field in the structures tells whether to update the configuration 91*b3634386SMauro Carvalho Chehabfor the specific function and the flag tells whether to enable or disable the 92*b3634386SMauro Carvalho Chehabfunction. 93*b3634386SMauro Carvalho Chehab 94*b3634386SMauro Carvalho ChehabThe update and flag bit masks accept the following values. Each separate 95*b3634386SMauro Carvalho Chehabfunctions in the CCDC and preview blocks is associated with a flag (either 96*b3634386SMauro Carvalho Chehabdisable or enable; part of the flag field in the structure) and a pointer to 97*b3634386SMauro Carvalho Chehabconfiguration data for the function. 98*b3634386SMauro Carvalho Chehab 99*b3634386SMauro Carvalho ChehabValid values for the update and flag fields are listed here for 100*b3634386SMauro Carvalho ChehabVIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one 101*b3634386SMauro Carvalho Chehabfunction in the same IOCTL call. 102*b3634386SMauro Carvalho Chehab 103*b3634386SMauro Carvalho Chehab- OMAP3ISP_CCDC_ALAW 104*b3634386SMauro Carvalho Chehab- OMAP3ISP_CCDC_LPF 105*b3634386SMauro Carvalho Chehab- OMAP3ISP_CCDC_BLCLAMP 106*b3634386SMauro Carvalho Chehab- OMAP3ISP_CCDC_BCOMP 107*b3634386SMauro Carvalho Chehab- OMAP3ISP_CCDC_FPC 108*b3634386SMauro Carvalho Chehab- OMAP3ISP_CCDC_CULL 109*b3634386SMauro Carvalho Chehab- OMAP3ISP_CCDC_CONFIG_LSC 110*b3634386SMauro Carvalho Chehab- OMAP3ISP_CCDC_TBL_LSC 111*b3634386SMauro Carvalho Chehab 112*b3634386SMauro Carvalho ChehabThe corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here: 113*b3634386SMauro Carvalho Chehab 114*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_LUMAENH 115*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_INVALAW 116*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_HRZ_MED 117*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_CFA 118*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_CHROMA_SUPP 119*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_WB 120*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_BLKADJ 121*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_RGB2RGB 122*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_COLOR_CONV 123*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_YC_LIMIT 124*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_DEFECT_COR 125*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_GAMMABYPASS 126*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_DRK_FRM_CAPTURE 127*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_DRK_FRM_SUBTRACT 128*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_LENS_SHADING 129*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_NF 130*b3634386SMauro Carvalho Chehab- OMAP3ISP_PREV_GAMMA 131*b3634386SMauro Carvalho Chehab 132*b3634386SMauro Carvalho ChehabThe associated configuration pointer for the function may not be NULL when 133*b3634386SMauro Carvalho Chehabenabling the function. When disabling a function the configuration pointer is 134*b3634386SMauro Carvalho Chehabignored. 135*b3634386SMauro Carvalho Chehab 136*b3634386SMauro Carvalho Chehab 137*b3634386SMauro Carvalho ChehabStatistic blocks IOCTLs 138*b3634386SMauro Carvalho Chehab----------------------- 139*b3634386SMauro Carvalho Chehab 140*b3634386SMauro Carvalho ChehabThe statistics subdevs do offer more dynamic configuration options than the 141*b3634386SMauro Carvalho Chehabother subdevs. They can be enabled, disable and reconfigured when the pipeline 142*b3634386SMauro Carvalho Chehabis in streaming state. 143*b3634386SMauro Carvalho Chehab 144*b3634386SMauro Carvalho ChehabThe statistics blocks always get the input image data from the CCDC (as the 145*b3634386SMauro Carvalho Chehabhistogram memory read isn't implemented). The statistics are dequeueable by 146*b3634386SMauro Carvalho Chehabthe user from the statistics subdev nodes using private IOCTLs. 147*b3634386SMauro Carvalho Chehab 148*b3634386SMauro Carvalho ChehabThe private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily 149*b3634386SMauro Carvalho Chehabreflected by the register level interface offered by the ISP hardware. There 150*b3634386SMauro Carvalho Chehabare aspects that are purely related to the driver implementation and these are 151*b3634386SMauro Carvalho Chehabdiscussed next. 152*b3634386SMauro Carvalho Chehab 153*b3634386SMauro Carvalho ChehabVIDIOC_OMAP3ISP_STAT_EN 154*b3634386SMauro Carvalho Chehab----------------------- 155*b3634386SMauro Carvalho Chehab 156*b3634386SMauro Carvalho ChehabThis private IOCTL enables/disables a statistic module. If this request is 157*b3634386SMauro Carvalho Chehabdone before streaming, it will take effect as soon as the pipeline starts to 158*b3634386SMauro Carvalho Chehabstream. If the pipeline is already streaming, it will take effect as soon as 159*b3634386SMauro Carvalho Chehabthe CCDC becomes idle. 160*b3634386SMauro Carvalho Chehab 161*b3634386SMauro Carvalho ChehabVIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG 162*b3634386SMauro Carvalho Chehab----------------------------------------------------------------------------- 163*b3634386SMauro Carvalho Chehab 164*b3634386SMauro Carvalho ChehabThose IOCTLs are used to configure the modules. They require user applications 165*b3634386SMauro Carvalho Chehabto have an in-depth knowledge of the hardware. Most of the fields explanation 166*b3634386SMauro Carvalho Chehabcan be found on OMAP's TRMs. The two following fields common to all the above 167*b3634386SMauro Carvalho Chehabconfigure private IOCTLs require explanation for better understanding as they 168*b3634386SMauro Carvalho Chehabare not part of the TRM. 169*b3634386SMauro Carvalho Chehab 170*b3634386SMauro Carvalho Chehabomap3isp_[h3a_af/h3a_aewb/hist]\_config.buf_size: 171*b3634386SMauro Carvalho Chehab 172*b3634386SMauro Carvalho ChehabThe modules handle their buffers internally. The necessary buffer size for the 173*b3634386SMauro Carvalho Chehabmodule's data output depends on the requested configuration. Although the 174*b3634386SMauro Carvalho Chehabdriver supports reconfiguration while streaming, it does not support a 175*b3634386SMauro Carvalho Chehabreconfiguration which requires bigger buffer size than what is already 176*b3634386SMauro Carvalho Chehabinternally allocated if the module is enabled. It will return -EBUSY on this 177*b3634386SMauro Carvalho Chehabcase. In order to avoid such condition, either disable/reconfigure/enable the 178*b3634386SMauro Carvalho Chehabmodule or request the necessary buffer size during the first configuration 179*b3634386SMauro Carvalho Chehabwhile the module is disabled. 180*b3634386SMauro Carvalho Chehab 181*b3634386SMauro Carvalho ChehabThe internal buffer size allocation considers the requested configuration's 182*b3634386SMauro Carvalho Chehabminimum buffer size and the value set on buf_size field. If buf_size field is 183*b3634386SMauro Carvalho Chehabout of [minimum, maximum] buffer size range, it's clamped to fit in there. 184*b3634386SMauro Carvalho ChehabThe driver then selects the biggest value. The corrected buf_size value is 185*b3634386SMauro Carvalho Chehabwritten back to user application. 186*b3634386SMauro Carvalho Chehab 187*b3634386SMauro Carvalho Chehabomap3isp_[h3a_af/h3a_aewb/hist]\_config.config_counter: 188*b3634386SMauro Carvalho Chehab 189*b3634386SMauro Carvalho ChehabAs the configuration doesn't take effect synchronously to the request, the 190*b3634386SMauro Carvalho Chehabdriver must provide a way to track this information to provide more accurate 191*b3634386SMauro Carvalho Chehabdata. After a configuration is requested, the config_counter returned to user 192*b3634386SMauro Carvalho Chehabspace application will be an unique value associated to that request. When 193*b3634386SMauro Carvalho Chehabuser application receives an event for buffer availability or when a new 194*b3634386SMauro Carvalho Chehabbuffer is requested, this config_counter is used to match a buffer data and a 195*b3634386SMauro Carvalho Chehabconfiguration. 196*b3634386SMauro Carvalho Chehab 197*b3634386SMauro Carvalho ChehabVIDIOC_OMAP3ISP_STAT_REQ 198*b3634386SMauro Carvalho Chehab------------------------ 199*b3634386SMauro Carvalho Chehab 200*b3634386SMauro Carvalho ChehabSend to user space the oldest data available in the internal buffer queue and 201*b3634386SMauro Carvalho Chehabdiscards such buffer afterwards. The field omap3isp_stat_data.frame_number 202*b3634386SMauro Carvalho Chehabmatches with the video buffer's field_count. 203*b3634386SMauro Carvalho Chehab 204*b3634386SMauro Carvalho Chehab 205*b3634386SMauro Carvalho ChehabReferences 206*b3634386SMauro Carvalho Chehab---------- 207*b3634386SMauro Carvalho Chehab 208*b3634386SMauro Carvalho Chehab.. [#] include/linux/omap3isp.h 209