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