imx-uapi.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3=========================
  4i.MX Video Capture Driver
  5=========================
  6
  7Events
  8======
  9
 10.. _imx_api_ipuX_csiY:
 11
 12ipuX_csiY
 13---------
 14
 15This subdev can generate the following event when enabling the second
 16IDMAC source pad:
 17
 18- V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR
 19
 20The user application can subscribe to this event from the ipuX_csiY
 21subdev node. This event is generated by the Frame Interval Monitor
 22(see below for more on the FIM).
 23
 24Controls
 25========
 26
 27.. _imx_api_FIM:
 28
 29Frame Interval Monitor in ipuX_csiY
 30-----------------------------------
 31
 32The adv718x decoders can occasionally send corrupt fields during
 33NTSC/PAL signal re-sync (too little or too many video lines). When
 34this happens, the IPU triggers a mechanism to re-establish vertical
 35sync by adding 1 dummy line every frame, which causes a rolling effect
 36from image to image, and can last a long time before a stable image is
 37recovered. Or sometimes the mechanism doesn't work at all, causing a
 38permanent split image (one frame contains lines from two consecutive
 39captured images).
 40
 41From experiment it was found that during image rolling, the frame
 42intervals (elapsed time between two EOF's) drop below the nominal
 43value for the current standard, by about one frame time (60 usec),
 44and remain at that value until rolling stops.
 45
 46While the reason for this observation isn't known (the IPU dummy
 47line mechanism should show an increase in the intervals by 1 line
 48time every frame, not a fixed value), we can use it to detect the
 49corrupt fields using a frame interval monitor. If the FIM detects a
 50bad frame interval, the ipuX_csiY subdev will send the event
 51V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR. Userland can register with
 52the FIM event notification on the ipuX_csiY subdev device node.
 53Userland can issue a streaming restart when this event is received
 54to correct the rolling/split image.
 55
 56The ipuX_csiY subdev includes custom controls to tweak some dials for
 57FIM. If one of these controls is changed during streaming, the FIM will
 58be reset and will continue at the new settings.
 59
 60- V4L2_CID_IMX_FIM_ENABLE
 61
 62Enable/disable the FIM.
 63
 64- V4L2_CID_IMX_FIM_NUM
 65
 66How many frame interval measurements to average before comparing against
 67the nominal frame interval reported by the sensor. This can reduce noise
 68caused by interrupt latency.
 69
 70- V4L2_CID_IMX_FIM_TOLERANCE_MIN
 71
 72If the averaged intervals fall outside nominal by this amount, in
 73microseconds, the V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR event is sent.
 74
 75- V4L2_CID_IMX_FIM_TOLERANCE_MAX
 76
 77If any intervals are higher than this value, those samples are
 78discarded and do not enter into the average. This can be used to
 79discard really high interval errors that might be due to interrupt
 80latency from high system load.
 81
 82- V4L2_CID_IMX_FIM_NUM_SKIP
 83
 84How many frames to skip after a FIM reset or stream restart before
 85FIM begins to average intervals.
 86
 87- V4L2_CID_IMX_FIM_ICAP_CHANNEL / V4L2_CID_IMX_FIM_ICAP_EDGE
 88
 89These controls will configure an input capture channel as the method
 90for measuring frame intervals. This is superior to the default method
 91of measuring frame intervals via EOF interrupt, since it is not subject
 92to uncertainty errors introduced by interrupt latency.
 93
 94Input capture requires hardware support. A VSYNC signal must be routed
 95to one of the i.MX6 input capture channel pads.
 96
 97V4L2_CID_IMX_FIM_ICAP_CHANNEL configures which i.MX6 input capture
 98channel to use. This must be 0 or 1.
 99
100V4L2_CID_IMX_FIM_ICAP_EDGE configures which signal edge will trigger
101input capture events. By default the input capture method is disabled
102with a value of IRQ_TYPE_NONE. Set this control to IRQ_TYPE_EDGE_RISING,
103IRQ_TYPE_EDGE_FALLING, or IRQ_TYPE_EDGE_BOTH to enable input capture,
104triggered on the given signal edge(s).
105
106When input capture is disabled, frame intervals will be measured via
107EOF interrupt.
108
109
110File list
111---------
112
113drivers/staging/media/imx/
114include/media/imx.h
115include/linux/imx-media.h
116
117
118Authors
119-------
120
121- Steve Longerbeam <steve_longerbeam@mentor.com>
122- Philipp Zabel <kernel@pengutronix.de>
123- Russell King <linux@armlinux.org.uk>
124
125Copyright (C) 2012-2017 Mentor Graphics Inc.