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