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