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