Debian Codegraph @

Documentation/admin-guide/media/mgb4.rst

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 .. include:: <isonum.txt>
4
5 The mgb4 driver
6 ===============
7
8 Copyright |copy| 2023 - 2025 Digiteq Automotive
9 author: Martin Tůma <[email protected]>
10
11 This is a v4l2 device driver for the Digiteq Automotive FrameGrabber 4, a PCIe
12 card capable of capturing and generating FPD-Link III and GMSL2/3 video streams
13 as used in the automotive industry.
14
15 sysfs interface
16 ---------------
17
18 The mgb4 driver provides a sysfs interface, that is used to configure video
19 stream related parameters (some of them must be set properly before the v4l2
20 device can be opened) and obtain the video device/stream status.
21
22 There are two types of parameters - global / PCI card related, found under
23 ``/sys/class/video4linux/videoX/device`` and module specific found under
24 ``/sys/class/video4linux/videoX``.
25
26 Global (PCI card) parameters
27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
28
29 **module_type** (R):
30 Module type.
31
32 | 0 - No module present
33 | 1 - FPDL3
34 | 2 - GMSL3 (one serializer, two daisy chained deserializers)
35 | 3 - GMSL3 (one serializer, two deserializers)
36 | 4 - GMSL3 (two deserializers with two daisy chain outputs)
37 | 6 - GMSL1
38 | 8 - GMSL3 coax
39
40 **module_version** (R):
41 Module version number. Zero in case of a missing module.
42
43 **fw_type** (R):
44 Firmware type.
45
46 | 1 - FPDL3
47 | 2 - GMSL3
48 | 3 - GMSL1
49
50 **fw_version** (R):
51 Firmware version number.
52
53 **serial_number** (R):
54 Card serial number. The format is::
55
56 PRODUCT-REVISION-SERIES-SERIAL
57
58 where each component is a 8b number.
59
60 Common FPDL3/GMSL input parameters
61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
63 **input_id** (R):
64 Input number ID, zero based.
65
66 **oldi_lane_width** (RW):
67 Number of deserializer output lanes.
68
69 | 0 - single
70 | 1 - dual (default)
71
72 **color_mapping** (RW):
73 Mapping of the incoming bits in the signal to the colour bits of the pixels.
74
75 | 0 - OLDI/JEIDA
76 | 1 - SPWG/VESA (default)
77
78 **link_status** (R):
79 Video link status. If the link is locked, chips are properly connected and
80 communicating at the same speed and protocol. The link can be locked without
81 an active video stream.
82
83 A value of 0 is equivalent to the V4L2_IN_ST_NO_SYNC flag of the V4L2
84 VIDIOC_ENUMINPUT status bits.
85
86 | 0 - unlocked
87 | 1 - locked
88
89 **stream_status** (R):
90 Video stream status. A stream is detected if the link is locked, the input
91 pixel clock is running and the DE signal is moving.
92
93 A value of 0 is equivalent to the V4L2_IN_ST_NO_SIGNAL flag of the V4L2
94 VIDIOC_ENUMINPUT status bits.
95
96 | 0 - not detected
97 | 1 - detected
98
99 **video_width** (R):
100 Video stream width. This is the actual width as detected by the HW.
101
102 The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in the width
103 field of the v4l2_bt_timings struct.
104
105 **video_height** (R):
106 Video stream height. This is the actual height as detected by the HW.
107
108 The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in the height
109 field of the v4l2_bt_timings struct.
110
111 **vsync_status** (R):
112 The type of VSYNC pulses as detected by the video format detector.
113
114 The value is equivalent to the flags returned by VIDIOC_QUERY_DV_TIMINGS in
115 the polarities field of the v4l2_bt_timings struct.
116
117 | 0 - active low
118 | 1 - active high
119 | 2 - not available
120
121 **hsync_status** (R):
122 The type of HSYNC pulses as detected by the video format detector.
123
124 The value is equivalent to the flags returned by VIDIOC_QUERY_DV_TIMINGS in
125 the polarities field of the v4l2_bt_timings struct.
126
127 | 0 - active low
128 | 1 - active high
129 | 2 - not available
130
131 **vsync_gap_length** (RW):
132 If the incoming video signal does not contain synchronization VSYNC and
133 HSYNC pulses, these must be generated internally in the FPGA to achieve
134 the correct frame ordering. This value indicates, how many "empty" pixels
135 (pixels with deasserted Data Enable signal) are necessary to generate the
136 internal VSYNC pulse.
137
138 **hsync_gap_length** (RW):
139 If the incoming video signal does not contain synchronization VSYNC and
140 HSYNC pulses, these must be generated internally in the FPGA to achieve
141 the correct frame ordering. This value indicates, how many "empty" pixels
142 (pixels with deasserted Data Enable signal) are necessary to generate the
143 internal HSYNC pulse. The value must be greater than 1 and smaller than
144 vsync_gap_length.
145
146 **pclk_frequency** (R):
147 Input pixel clock frequency in kHz.
148
149 The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in
150 the pixelclock field of the v4l2_bt_timings struct.
151
152 *Note: The frequency_range parameter must be set properly first to get
153 a valid frequency here.*
154
155 **hsync_width** (R):
156 Width of the HSYNC signal in PCLK clock ticks.
157
158 The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in
159 the hsync field of the v4l2_bt_timings struct.
160
161 **vsync_width** (R):
162 Width of the VSYNC signal in PCLK clock ticks.
163
164 The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in
165 the vsync field of the v4l2_bt_timings struct.
166
167 **hback_porch** (R):
168 Number of PCLK pulses between deassertion of the HSYNC signal and the first
169 valid pixel in the video line (marked by DE=1).
170
171 The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in
172 the hbackporch field of the v4l2_bt_timings struct.
173
174 **hfront_porch** (R):
175 Number of PCLK pulses between the end of the last valid pixel in the video
176 line (marked by DE=1) and assertion of the HSYNC signal.
177
178 The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in
179 the hfrontporch field of the v4l2_bt_timings struct.
180
181 **vback_porch** (R):
182 Number of video lines between deassertion of the VSYNC signal and the video
183 line with the first valid pixel (marked by DE=1).
184
185 The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in
186 the vbackporch field of the v4l2_bt_timings struct.
187
188 **vfront_porch** (R):
189 Number of video lines between the end of the last valid pixel line (marked
190 by DE=1) and assertion of the VSYNC signal.
191
192 The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in
193 the vfrontporch field of the v4l2_bt_timings struct.
194
195 **frequency_range** (RW)
196 PLL frequency range of the OLDI input clock generator. The PLL frequency is
197 derived from the Pixel Clock Frequency (PCLK) and is equal to PCLK if
198 oldi_lane_width is set to "single" and PCLK/2 if oldi_lane_width is set to
199 "dual".
200
201 | 0 - PLL < 50MHz (default)
202 | 1 - PLL >= 50MHz
203
204 *Note: This parameter can not be changed while the input v4l2 device is
205 open.*
206
207 Common FPDL3/GMSL output parameters
208 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
209
210 **output_id** (R):
211 Output number ID, zero based.
212
213 **video_source** (RW):
214 Output video source. If set to 0 or 1, the source is the corresponding card
215 input and the v4l2 output devices are disabled. If set to 2 or 3, the source
216 is the corresponding v4l2 video output device. The default is
217 the corresponding v4l2 output, i.e. 2 for OUT1 and 3 for OUT2.
218
219 | 0 - input 0
220 | 1 - input 1
221 | 2 - v4l2 output 0
222 | 3 - v4l2 output 1
223
224 *Note: This parameter can not be changed while ANY of the input/output v4l2
225 devices is open.*
226
227 **display_width** (RW):
228 Display width. There is no autodetection of the connected display, so the
229 proper value must be set before the start of streaming. The default width
230 is 1280.
231
232 *Note: This parameter can not be changed while the output v4l2 device is
233 open.*
234
235 **display_height** (RW):
236 Display height. There is no autodetection of the connected display, so the
237 proper value must be set before the start of streaming. The default height
238 is 640.
239
240 *Note: This parameter can not be changed while the output v4l2 device is
241 open.*
242
243 **frame_rate** (RW):
244 Output video signal frame rate limit in frames per second. Due to
245 the limited output pixel clock steps, the card can not always generate
246 a frame rate perfectly matching the value required by the connected display.
247 Using this parameter one can limit the frame rate by "crippling" the signal
248 so that the lines are not equal (the porches of the last line differ) but
249 the signal appears like having the exact frame rate to the connected display.
250 The default frame rate limit is 60Hz.
251
252 **hsync_polarity** (RW):
253 HSYNC signal polarity.
254
255 | 0 - active low (default)
256 | 1 - active high
257
258 **vsync_polarity** (RW):
259 VSYNC signal polarity.
260
261 | 0 - active low (default)
262 | 1 - active high
263
264 **de_polarity** (RW):
265 DE signal polarity.
266
267 | 0 - active low
268 | 1 - active high (default)
269
270 **pclk_frequency** (RW):
271 Output pixel clock frequency. Allowed values are between 25000-190000(kHz)
272 and there is a non-linear stepping between two consecutive allowed
273 frequencies. The driver finds the nearest allowed frequency to the given
274 value and sets it. When reading this property, you get the exact
275 frequency set by the driver. The default frequency is 61150kHz.
276
277 *Note: This parameter can not be changed while the output v4l2 device is
278 open.*
279
280 **hsync_width** (RW):
281 Width of the HSYNC signal in pixels. The default value is 40.
282
283 **vsync_width** (RW):
284 Width of the VSYNC signal in video lines. The default value is 20.
285
286 **hback_porch** (RW):
287 Number of PCLK pulses between deassertion of the HSYNC signal and the first
288 valid pixel in the video line (marked by DE=1). The default value is 50.
289
290 **hfront_porch** (RW):
291 Number of PCLK pulses between the end of the last valid pixel in the video
292 line (marked by DE=1) and assertion of the HSYNC signal. The default value
293 is 50.
294
295 **vback_porch** (RW):
296 Number of video lines between deassertion of the VSYNC signal and the video
297 line with the first valid pixel (marked by DE=1). The default value is 31.
298
299 **vfront_porch** (RW):
300 Number of video lines between the end of the last valid pixel line (marked
301 by DE=1) and assertion of the VSYNC signal. The default value is 30.
302
303 FPDL3 specific input parameters
304 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
305
306 **fpdl3_input_width** (RW):
307 Number of deserializer input lines.
308
309 | 0 - auto (default)
310 | 1 - single
311 | 2 - dual
312
313 FPDL3 specific output parameters
314 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
315
316 **fpdl3_output_width** (RW):
317 Number of serializer output lines.
318
319 | 0 - auto (default)
320 | 1 - single
321 | 2 - dual
322
323 GMSL specific input parameters
324 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
325
326 **gmsl_mode** (RW):
327 GMSL speed mode.
328
329 | 0 - 12Gb/s (default)
330 | 1 - 6Gb/s
331 | 2 - 3Gb/s
332 | 3 - 1.5Gb/s
333
334 **gmsl_stream_id** (RW):
335 The GMSL multi-stream contains up to four video streams. This parameter
336 selects which stream is captured by the video input. The value is the
337 zero-based index of the stream. The default stream id is 0.
338
339 *Note: This parameter can not be changed while the input v4l2 device is
340 open.*
341
342 **gmsl_fec** (RW):
343 GMSL Forward Error Correction (FEC).
344
345 | 0 - disabled
346 | 1 - enabled (default)
347
348 MTD partitions
349 --------------
350
351 The mgb4 driver creates a MTD device with two partitions:
352 - mgb4-fw.X - FPGA firmware.
353 - mgb4-data.X - Factory settings, e.g. card serial number.
354
355 The *mgb4-fw* partition is writable and is used for FW updates, *mgb4-data* is
356 read-only. The *X* attached to the partition name represents the card number.
357 Depending on the CONFIG_MTD_PARTITIONED_MASTER kernel configuration, you may
358 also have a third partition named *mgb4-flash* available in the system. This
359 partition represents the whole, unpartitioned, card's FLASH memory and one should
360 not fiddle with it...
361
362 IIO (triggers)
363 --------------
364
365 The mgb4 driver creates an Industrial I/O (IIO) device that provides trigger and
366 signal level status capability. The following scan elements are available:
367
368 **activity**:
369 The trigger levels and pending status.
370
371 | bit 1 - trigger 1 pending
372 | bit 2 - trigger 2 pending
373 | bit 5 - trigger 1 level
374 | bit 6 - trigger 2 level
375
376 **timestamp**:
377 The trigger event timestamp.
378
379 The iio device can operate either in "raw" mode where you can fetch the signal
380 levels (activity bits 5 and 6) using sysfs access or in triggered buffer mode.
381 In the triggered buffer mode you can follow the signal level changes (activity
382 bits 1 and 2) using the iio device in /dev. If you enable the timestamps, you
383 will also get the exact trigger event time that can be matched to a video frame
384 (every mgb4 video frame has a timestamp with the same clock source).
385
386 *Note: although the activity sample always contains all the status bits, it makes
387 no sense to get the pending bits in raw mode or the level bits in the triggered
388 buffer mode - the values do not represent valid data in such case.*