Based on kernel version 4.7.2. Page generated on 2016-08-22 22:48 EST.
1 OMAP 3 Image Signal Processor (ISP) driver 2 3 Copyright (C) 2010 Nokia Corporation 4 Copyright (C) 2009 Texas Instruments, Inc. 5 6 Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com> 7 Sakari Ailus <sakari.ailus@iki.fi> 8 David Cohen <dacohen@gmail.com> 9 10 11 Introduction 12 ============ 13 14 This file documents the Texas Instruments OMAP 3 Image Signal Processor (ISP) 15 driver located under drivers/media/platform/omap3isp. The original driver was 16 written by Texas Instruments but since that it has been rewritten (twice) at 17 Nokia. 18 19 The driver has been successfully used on the following versions of OMAP 3: 20 21 3430 22 3530 23 3630 24 25 The driver implements V4L2, Media controller and v4l2_subdev interfaces. 26 Sensor, lens and flash drivers using the v4l2_subdev interface in the kernel 27 are supported. 28 29 30 Split to subdevs 31 ================ 32 33 The OMAP 3 ISP is split into V4L2 subdevs, each of the blocks inside the ISP 34 having one subdev to represent it. Each of the subdevs provide a V4L2 subdev 35 interface to userspace. 36 37 OMAP3 ISP CCP2 38 OMAP3 ISP CSI2a 39 OMAP3 ISP CCDC 40 OMAP3 ISP preview 41 OMAP3 ISP resizer 42 OMAP3 ISP AEWB 43 OMAP3 ISP AF 44 OMAP3 ISP histogram 45 46 Each possible link in the ISP is modelled by a link in the Media controller 47 interface. For an example program see [2]. 48 49 50 Controlling the OMAP 3 ISP 51 ========================== 52 53 In general, the settings given to the OMAP 3 ISP take effect at the beginning 54 of the following frame. This is done when the module becomes idle during the 55 vertical blanking period on the sensor. In memory-to-memory operation the pipe 56 is run one frame at a time. Applying the settings is done between the frames. 57 58 All the blocks in the ISP, excluding the CSI-2 and possibly the CCP2 receiver, 59 insist on receiving complete frames. Sensors must thus never send the ISP 60 partial frames. 61 62 Autoidle does have issues with some ISP blocks on the 3430, at least. 63 Autoidle is only enabled on 3630 when the omap3isp module parameter autoidle 64 is non-zero. 65 66 67 Events 68 ====== 69 70 The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and 71 statistics (AEWB, AF and histogram) subdevs. 72 73 The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS 74 interrupt which is used to signal frame start. Earlier version of this 75 driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is 76 triggered exactly when the reception of the first line of the frame starts 77 in the CCDC module. The event can be subscribed on the CCDC subdev. 78 79 (When using parallel interface one must pay account to correct configuration 80 of the VS signal polarity. This is automatically correct when using the serial 81 receivers.) 82 83 Each of the statistics subdevs is able to produce events. An event is 84 generated whenever a statistics buffer can be dequeued by a user space 85 application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available 86 are: 87 88 V4L2_EVENT_OMAP3ISP_AEWB 89 V4L2_EVENT_OMAP3ISP_AF 90 V4L2_EVENT_OMAP3ISP_HIST 91 92 The type of the event data is struct omap3isp_stat_event_status for these 93 ioctls. If there is an error calculating the statistics, there will be an 94 event as usual, but no related statistics buffer. In this case 95 omap3isp_stat_event_status.buf_err is set to non-zero. 96 97 98 Private IOCTLs 99 ============== 100 101 The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where 102 possible and practical. Much of the functions provided by the ISP, however, 103 does not fall under the standard IOCTLs --- gamma tables and configuration of 104 statistics collection are examples of such. 105 106 In general, there is a private ioctl for configuring each of the blocks 107 containing hardware-dependent functions. 108 109 The following private IOCTLs are supported: 110 111 VIDIOC_OMAP3ISP_CCDC_CFG 112 VIDIOC_OMAP3ISP_PRV_CFG 113 VIDIOC_OMAP3ISP_AEWB_CFG 114 VIDIOC_OMAP3ISP_HIST_CFG 115 VIDIOC_OMAP3ISP_AF_CFG 116 VIDIOC_OMAP3ISP_STAT_REQ 117 VIDIOC_OMAP3ISP_STAT_EN 118 119 The parameter structures used by these ioctls are described in 120 include/linux/omap3isp.h. The detailed functions of the ISP itself related to 121 a given ISP block is described in the Technical Reference Manuals (TRMs) --- 122 see the end of the document for those. 123 124 While it is possible to use the ISP driver without any use of these private 125 IOCTLs it is not possible to obtain optimal image quality this way. The AEWB, 126 AF and histogram modules cannot be used without configuring them using the 127 appropriate private IOCTLs. 128 129 130 CCDC and preview block IOCTLs 131 ============================= 132 133 The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to 134 configure, enable and disable functions in the CCDC and preview blocks, 135 respectively. Both IOCTLs control several functions in the blocks they 136 control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct 137 omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG 138 accepts a pointer to struct omap3isp_prev_update_config. The definition of 139 both structures is available in [1]. 140 141 The update field in the structures tells whether to update the configuration 142 for the specific function and the flag tells whether to enable or disable the 143 function. 144 145 The update and flag bit masks accept the following values. Each separate 146 functions in the CCDC and preview blocks is associated with a flag (either 147 disable or enable; part of the flag field in the structure) and a pointer to 148 configuration data for the function. 149 150 Valid values for the update and flag fields are listed here for 151 VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one 152 function in the same IOCTL call. 153 154 OMAP3ISP_CCDC_ALAW 155 OMAP3ISP_CCDC_LPF 156 OMAP3ISP_CCDC_BLCLAMP 157 OMAP3ISP_CCDC_BCOMP 158 OMAP3ISP_CCDC_FPC 159 OMAP3ISP_CCDC_CULL 160 OMAP3ISP_CCDC_CONFIG_LSC 161 OMAP3ISP_CCDC_TBL_LSC 162 163 The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here: 164 165 OMAP3ISP_PREV_LUMAENH 166 OMAP3ISP_PREV_INVALAW 167 OMAP3ISP_PREV_HRZ_MED 168 OMAP3ISP_PREV_CFA 169 OMAP3ISP_PREV_CHROMA_SUPP 170 OMAP3ISP_PREV_WB 171 OMAP3ISP_PREV_BLKADJ 172 OMAP3ISP_PREV_RGB2RGB 173 OMAP3ISP_PREV_COLOR_CONV 174 OMAP3ISP_PREV_YC_LIMIT 175 OMAP3ISP_PREV_DEFECT_COR 176 OMAP3ISP_PREV_GAMMABYPASS 177 OMAP3ISP_PREV_DRK_FRM_CAPTURE 178 OMAP3ISP_PREV_DRK_FRM_SUBTRACT 179 OMAP3ISP_PREV_LENS_SHADING 180 OMAP3ISP_PREV_NF 181 OMAP3ISP_PREV_GAMMA 182 183 The associated configuration pointer for the function may not be NULL when 184 enabling the function. When disabling a function the configuration pointer is 185 ignored. 186 187 188 Statistic blocks IOCTLs 189 ======================= 190 191 The statistics subdevs do offer more dynamic configuration options than the 192 other subdevs. They can be enabled, disable and reconfigured when the pipeline 193 is in streaming state. 194 195 The statistics blocks always get the input image data from the CCDC (as the 196 histogram memory read isn't implemented). The statistics are dequeueable by 197 the user from the statistics subdev nodes using private IOCTLs. 198 199 The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily 200 reflected by the register level interface offered by the ISP hardware. There 201 are aspects that are purely related to the driver implementation and these are 202 discussed next. 203 204 VIDIOC_OMAP3ISP_STAT_EN 205 ----------------------- 206 207 This private IOCTL enables/disables a statistic module. If this request is 208 done before streaming, it will take effect as soon as the pipeline starts to 209 stream. If the pipeline is already streaming, it will take effect as soon as 210 the CCDC becomes idle. 211 212 VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG 213 ----------------------------------------------------------------------------- 214 215 Those IOCTLs are used to configure the modules. They require user applications 216 to have an in-depth knowledge of the hardware. Most of the fields explanation 217 can be found on OMAP's TRMs. The two following fields common to all the above 218 configure private IOCTLs require explanation for better understanding as they 219 are not part of the TRM. 220 221 omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size: 222 223 The modules handle their buffers internally. The necessary buffer size for the 224 module's data output depends on the requested configuration. Although the 225 driver supports reconfiguration while streaming, it does not support a 226 reconfiguration which requires bigger buffer size than what is already 227 internally allocated if the module is enabled. It will return -EBUSY on this 228 case. In order to avoid such condition, either disable/reconfigure/enable the 229 module or request the necessary buffer size during the first configuration 230 while the module is disabled. 231 232 The internal buffer size allocation considers the requested configuration's 233 minimum buffer size and the value set on buf_size field. If buf_size field is 234 out of [minimum, maximum] buffer size range, it's clamped to fit in there. 235 The driver then selects the biggest value. The corrected buf_size value is 236 written back to user application. 237 238 omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter: 239 240 As the configuration doesn't take effect synchronously to the request, the 241 driver must provide a way to track this information to provide more accurate 242 data. After a configuration is requested, the config_counter returned to user 243 space application will be an unique value associated to that request. When 244 user application receives an event for buffer availability or when a new 245 buffer is requested, this config_counter is used to match a buffer data and a 246 configuration. 247 248 VIDIOC_OMAP3ISP_STAT_REQ 249 ------------------------ 250 251 Send to user space the oldest data available in the internal buffer queue and 252 discards such buffer afterwards. The field omap3isp_stat_data.frame_number 253 matches with the video buffer's field_count. 254 255 256 Technical reference manuals (TRMs) and other documentation 257 ========================================================== 258 259 OMAP 3430 TRM: 260 <URL:http://focus.ti.com/pdfs/wtbu/OMAP34xx_ES3.1.x_PUBLIC_TRM_vZM.zip> 261 Referenced 2011-03-05. 262 263 OMAP 35xx TRM: 264 <URL:http://www.ti.com/litv/pdf/spruf98o> Referenced 2011-03-05. 265 266 OMAP 3630 TRM: 267 <URL:http://focus.ti.com/pdfs/wtbu/OMAP36xx_ES1.x_PUBLIC_TRM_vQ.zip> 268 Referenced 2011-03-05. 269 270 DM 3730 TRM: 271 <URL:http://www.ti.com/litv/pdf/sprugn4h> Referenced 2011-03-06. 272 273 274 References 275 ========== 276 277 [1] include/linux/omap3isp.h 278 279 [2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary