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