Documentation/userspace-api/media/drivers/imx-uapi.rst

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