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