media: docs: split uAPI info from omap3isp.rst
This file contains both driver develompent documentation and userspace API. Split on two, as they're usually read by different audiences. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab
parent
f8dd7a257d
commit
889a500ed5
|
|
@ -76,3 +76,4 @@ For more details see the file COPYING in the source distribution of Linux.
|
|||
|
||||
cx2341x-uapi
|
||||
meye-uapi
|
||||
omap3isp-uapi
|
||||
|
|
|
|||
|
|
@ -0,0 +1,208 @@
|
|||
.. 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 <laurent.pinchart@ideasonboard.com>,
|
||||
Sakari Ailus <sakari.ailus@iki.fi>, David Cohen <dacohen@gmail.com>
|
||||
|
||||
|
||||
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
|
||||
|
|
@ -49,7 +49,7 @@ interface to userspace.
|
|||
- OMAP3 ISP histogram
|
||||
|
||||
Each possible link in the ISP is modelled by a link in the Media controller
|
||||
interface. For an example program see [#f2]_.
|
||||
interface. For an example program see [#]_.
|
||||
|
||||
|
||||
Controlling the OMAP 3 ISP
|
||||
|
|
@ -68,196 +68,6 @@ Autoidle does have issues with some ISP blocks on the 3430, at least.
|
|||
Autoidle is only enabled on 3630 when the omap3isp module parameter autoidle
|
||||
is non-zero.
|
||||
|
||||
|
||||
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 [#f1]_.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Technical reference manuals (TRMs) and other documentation
|
||||
----------------------------------------------------------
|
||||
|
||||
|
|
@ -279,6 +89,4 @@ DM 3730 TRM:
|
|||
References
|
||||
----------
|
||||
|
||||
.. [#f1] include/linux/omap3isp.h
|
||||
|
||||
.. [#f2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
|
||||
.. [#] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
|
||||
|
|
|
|||
Loading…
Reference in New Issue