Commit 5dfb8db5 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

media: docs: split uAPI info from imx.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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent 889a500e
.. SPDX-License-Identifier: GPL-2.0
=========================
i.MX Video Capture Driver
=========================
Events
======
.. _imx_api_ipuX_csiY:
ipuX_csiY
---------
This subdev can generate the following event when enabling the second
IDMAC source pad:
- V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR
The user application can subscribe to this event from the ipuX_csiY
subdev node. This event is generated by the Frame Interval Monitor
(see below for more on the FIM).
Controls
========
.. _imx_api_FIM:
Frame Interval Monitor in ipuX_csiY
-----------------------------------
The adv718x decoders can occasionally send corrupt fields during
NTSC/PAL signal re-sync (too little or too many video lines). When
this happens, the IPU triggers a mechanism to re-establish vertical
sync by adding 1 dummy line every frame, which causes a rolling effect
from image to image, and can last a long time before a stable image is
recovered. Or sometimes the mechanism doesn't work at all, causing a
permanent split image (one frame contains lines from two consecutive
captured images).
From experiment it was found that during image rolling, the frame
intervals (elapsed time between two EOF's) drop below the nominal
value for the current standard, by about one frame time (60 usec),
and remain at that value until rolling stops.
While the reason for this observation isn't known (the IPU dummy
line mechanism should show an increase in the intervals by 1 line
time every frame, not a fixed value), we can use it to detect the
corrupt fields using a frame interval monitor. If the FIM detects a
bad frame interval, the ipuX_csiY subdev will send the event
V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR. Userland can register with
the FIM event notification on the ipuX_csiY subdev device node.
Userland can issue a streaming restart when this event is received
to correct the rolling/split image.
The ipuX_csiY subdev includes custom controls to tweak some dials for
FIM. If one of these controls is changed during streaming, the FIM will
be reset and will continue at the new settings.
- V4L2_CID_IMX_FIM_ENABLE
Enable/disable the FIM.
- V4L2_CID_IMX_FIM_NUM
How many frame interval measurements to average before comparing against
the nominal frame interval reported by the sensor. This can reduce noise
caused by interrupt latency.
- V4L2_CID_IMX_FIM_TOLERANCE_MIN
If the averaged intervals fall outside nominal by this amount, in
microseconds, the V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR event is sent.
- V4L2_CID_IMX_FIM_TOLERANCE_MAX
If any intervals are higher than this value, those samples are
discarded and do not enter into the average. This can be used to
discard really high interval errors that might be due to interrupt
latency from high system load.
- V4L2_CID_IMX_FIM_NUM_SKIP
How many frames to skip after a FIM reset or stream restart before
FIM begins to average intervals.
- V4L2_CID_IMX_FIM_ICAP_CHANNEL / V4L2_CID_IMX_FIM_ICAP_EDGE
These controls will configure an input capture channel as the method
for measuring frame intervals. This is superior to the default method
of measuring frame intervals via EOF interrupt, since it is not subject
to uncertainty errors introduced by interrupt latency.
Input capture requires hardware support. A VSYNC signal must be routed
to one of the i.MX6 input capture channel pads.
V4L2_CID_IMX_FIM_ICAP_CHANNEL configures which i.MX6 input capture
channel to use. This must be 0 or 1.
V4L2_CID_IMX_FIM_ICAP_EDGE configures which signal edge will trigger
input capture events. By default the input capture method is disabled
with a value of IRQ_TYPE_NONE. Set this control to IRQ_TYPE_EDGE_RISING,
IRQ_TYPE_EDGE_FALLING, or IRQ_TYPE_EDGE_BOTH to enable input capture,
triggered on the given signal edge(s).
When input capture is disabled, frame intervals will be measured via
EOF interrupt.
File list
---------
drivers/staging/media/imx/
include/media/imx.h
include/linux/imx-media.h
Authors
-------
- Steve Longerbeam <steve_longerbeam@mentor.com>
- Philipp Zabel <kernel@pengutronix.de>
- Russell King <linux@armlinux.org.uk>
Copyright (C) 2012-2017 Mentor Graphics Inc.
......@@ -191,14 +191,7 @@ or unqualified interlaced). The capture interface will enforce the same
field order as the source pad field order (interlaced-bt if source pad
is seq-bt, interlaced-tb if source pad is seq-tb).
This subdev can generate the following event when enabling the second
IDMAC source pad:
- V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR
The user application can subscribe to this event from the ipuX_csiY
subdev node. This event is generated by the Frame Interval Monitor
(see below for more on the FIM).
For events produced by ipuX_csiY, see ref:`imx_api_ipuX_csiY`.
Cropping in ipuX_csiY
---------------------
......@@ -247,84 +240,7 @@ rate by half at the IDMAC output source pad:
Frame Interval Monitor in ipuX_csiY
-----------------------------------
The adv718x decoders can occasionally send corrupt fields during
NTSC/PAL signal re-sync (too little or too many video lines). When
this happens, the IPU triggers a mechanism to re-establish vertical
sync by adding 1 dummy line every frame, which causes a rolling effect
from image to image, and can last a long time before a stable image is
recovered. Or sometimes the mechanism doesn't work at all, causing a
permanent split image (one frame contains lines from two consecutive
captured images).
From experiment it was found that during image rolling, the frame
intervals (elapsed time between two EOF's) drop below the nominal
value for the current standard, by about one frame time (60 usec),
and remain at that value until rolling stops.
While the reason for this observation isn't known (the IPU dummy
line mechanism should show an increase in the intervals by 1 line
time every frame, not a fixed value), we can use it to detect the
corrupt fields using a frame interval monitor. If the FIM detects a
bad frame interval, the ipuX_csiY subdev will send the event
V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR. Userland can register with
the FIM event notification on the ipuX_csiY subdev device node.
Userland can issue a streaming restart when this event is received
to correct the rolling/split image.
The ipuX_csiY subdev includes custom controls to tweak some dials for
FIM. If one of these controls is changed during streaming, the FIM will
be reset and will continue at the new settings.
- V4L2_CID_IMX_FIM_ENABLE
Enable/disable the FIM.
- V4L2_CID_IMX_FIM_NUM
How many frame interval measurements to average before comparing against
the nominal frame interval reported by the sensor. This can reduce noise
caused by interrupt latency.
- V4L2_CID_IMX_FIM_TOLERANCE_MIN
If the averaged intervals fall outside nominal by this amount, in
microseconds, the V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR event is sent.
- V4L2_CID_IMX_FIM_TOLERANCE_MAX
If any intervals are higher than this value, those samples are
discarded and do not enter into the average. This can be used to
discard really high interval errors that might be due to interrupt
latency from high system load.
- V4L2_CID_IMX_FIM_NUM_SKIP
How many frames to skip after a FIM reset or stream restart before
FIM begins to average intervals.
- V4L2_CID_IMX_FIM_ICAP_CHANNEL
- V4L2_CID_IMX_FIM_ICAP_EDGE
These controls will configure an input capture channel as the method
for measuring frame intervals. This is superior to the default method
of measuring frame intervals via EOF interrupt, since it is not subject
to uncertainty errors introduced by interrupt latency.
Input capture requires hardware support. A VSYNC signal must be routed
to one of the i.MX6 input capture channel pads.
V4L2_CID_IMX_FIM_ICAP_CHANNEL configures which i.MX6 input capture
channel to use. This must be 0 or 1.
V4L2_CID_IMX_FIM_ICAP_EDGE configures which signal edge will trigger
input capture events. By default the input capture method is disabled
with a value of IRQ_TYPE_NONE. Set this control to IRQ_TYPE_EDGE_RISING,
IRQ_TYPE_EDGE_FALLING, or IRQ_TYPE_EDGE_BOTH to enable input capture,
triggered on the given signal edge(s).
When input capture is disabled, frame intervals will be measured via
EOF interrupt.
See ref:`imx_api_FIM`.
ipuX_vdic
---------
......
......@@ -75,5 +75,6 @@ For more details see the file COPYING in the source distribution of Linux.
vimc-devel
cx2341x-uapi
imx-uapi
meye-uapi
omap3isp-uapi
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment