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