1 .. SPDX-License-Identifier: GPL-2.0 2 3 The mgb4 driver 4 =============== 5 6 sysfs interface 7 --------------- 8 9 The mgb4 driver provides a sysfs interface, that is used to configure video 10 stream related parameters (some of them must be set properly before the v4l2 11 device can be opened) and obtain the video device/stream status. 12 13 There 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 17 Global (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 46 Common 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 193 Common 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 frame rate in frames per second. The default frame rate is 231 60Hz. 232 233 **hsync_polarity** (RW): 234 HSYNC signal polarity. 235 236 | 0 - active low (default) 237 | 1 - active high 238 239 **vsync_polarity** (RW): 240 VSYNC signal polarity. 241 242 | 0 - active low (default) 243 | 1 - active high 244 245 **de_polarity** (RW): 246 DE signal polarity. 247 248 | 0 - active low 249 | 1 - active high (default) 250 251 **pclk_frequency** (RW): 252 Output pixel clock frequency. Allowed values are between 25000-190000(kHz) 253 and there is a non-linear stepping between two consecutive allowed 254 frequencies. The driver finds the nearest allowed frequency to the given 255 value and sets it. When reading this property, you get the exact 256 frequency set by the driver. The default frequency is 70000kHz. 257 258 *Note: This parameter can not be changed while the output v4l2 device is 259 open.* 260 261 **hsync_width** (RW): 262 Width of the HSYNC signal in pixels. The default value is 16. 263 264 **vsync_width** (RW): 265 Width of the VSYNC signal in video lines. The default value is 2. 266 267 **hback_porch** (RW): 268 Number of PCLK pulses between deassertion of the HSYNC signal and the first 269 valid pixel in the video line (marked by DE=1). The default value is 32. 270 271 **hfront_porch** (RW): 272 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 HSYNC signal. The default value 274 is 32. 275 276 **vback_porch** (RW): 277 Number of video lines between deassertion of the VSYNC signal and the video 278 line with the first valid pixel (marked by DE=1). The default value is 2. 279 280 **vfront_porch** (RW): 281 Number of video lines between the end of the last valid pixel line (marked 282 by DE=1) and assertion of the VSYNC signal. The default value is 2. 283 284 FPDL3 specific input parameters 285 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 286 287 **fpdl3_input_width** (RW): 288 Number of deserializer input lines. 289 290 | 0 - auto (default) 291 | 1 - single 292 | 2 - dual 293 294 FPDL3 specific output parameters 295 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 296 297 **fpdl3_output_width** (RW): 298 Number of serializer output lines. 299 300 | 0 - auto (default) 301 | 1 - single 302 | 2 - dual 303 304 GMSL specific input parameters 305 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 306 307 **gmsl_mode** (RW): 308 GMSL speed mode. 309 310 | 0 - 12Gb/s (default) 311 | 1 - 6Gb/s 312 | 2 - 3Gb/s 313 | 3 - 1.5Gb/s 314 315 **gmsl_stream_id** (RW): 316 The GMSL multi-stream contains up to four video streams. This parameter 317 selects which stream is captured by the video input. The value is the 318 zero-based index of the stream. The default stream id is 0. 319 320 *Note: This parameter can not be changed while the input v4l2 device is 321 open.* 322 323 **gmsl_fec** (RW): 324 GMSL Forward Error Correction (FEC). 325 326 | 0 - disabled 327 | 1 - enabled (default) 328 329 MTD partitions 330 -------------- 331 332 The mgb4 driver creates a MTD device with two partitions: 333 - mgb4-fw.X - FPGA firmware. 334 - mgb4-data.X - Factory settings, e.g. card serial number. 335 336 The *mgb4-fw* partition is writable and is used for FW updates, *mgb4-data* is 337 read-only. The *X* attached to the partition name represents the card number. 338 Depending on the CONFIG_MTD_PARTITIONED_MASTER kernel configuration, you may 339 also have a third partition named *mgb4-flash* available in the system. This 340 partition represents the whole, unpartitioned, card's FLASH memory and one should 341 not fiddle with it... 342 343 IIO (triggers) 344 -------------- 345 346 The mgb4 driver creates an Industrial I/O (IIO) device that provides trigger and 347 signal level status capability. The following scan elements are available: 348 349 **activity**: 350 The trigger levels and pending status. 351 352 | bit 1 - trigger 1 pending 353 | bit 2 - trigger 2 pending 354 | bit 5 - trigger 1 level 355 | bit 6 - trigger 2 level 356 357 **timestamp**: 358 The trigger event timestamp. 359 360 The iio device can operate either in "raw" mode where you can fetch the signal 361 levels (activity bits 5 and 6) using sysfs access or in triggered buffer mode. 362 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 you enable the timestamps, you 364 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 the same clock source). 366 367 *Note: although the activity sample always contains all the status bits, it makes 368 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 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.