mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
208 lines
7.8 KiB
208 lines
7.8 KiB
.. 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 <[email protected]>, |
|
Sakari Ailus <[email protected]>, David Cohen <[email protected]> |
|
|
|
|
|
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
|
|
|