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