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