tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
media: Documentation: Added Digiteq Automotive MGB4 driver documentation
The "admin-guide" documentation for the Digiteq Automotive MGB4 driver.
Signed-off-by: Martin Tůma <martin.tuma@digiteqautomotive.com>
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
authored by
Martin Tůma
and committed by
Hans Verkuil
bd7e2477
0ab13674
+376
+374
Documentation/admin-guide/media/mgb4.rst
+374
Documentation/admin-guide/media/mgb4.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
====================
4
+
mgb4 sysfs interface
5
+
====================
6
+
7
+
The mgb4 driver provides a sysfs interface, that is used to configure video
8
+
stream related parameters (some of them must be set properly before the v4l2
9
+
device can be opened) and obtain the video device/stream status.
10
+
11
+
There are two types of parameters - global / PCI card related, found under
12
+
``/sys/class/video4linux/videoX/device`` and module specific found under
13
+
``/sys/class/video4linux/videoX``.
14
+
15
+
16
+
Global (PCI card) parameters
17
+
============================
18
+
19
+
**module_type** (R):
20
+
Module type.
21
+
22
+
| 0 - No module present
23
+
| 1 - FPDL3
24
+
| 2 - GMSL
25
+
26
+
**module_version** (R):
27
+
Module version number. Zero in case of a missing module.
28
+
29
+
**fw_type** (R):
30
+
Firmware type.
31
+
32
+
| 1 - FPDL3
33
+
| 2 - GMSL
34
+
35
+
**fw_version** (R):
36
+
Firmware version number.
37
+
38
+
**serial_number** (R):
39
+
Card serial number. The format is::
40
+
41
+
PRODUCT-REVISION-SERIES-SERIAL
42
+
43
+
where each component is a 8b number.
44
+
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
+
194
+
Common FPDL3/GMSL output parameters
195
+
===================================
196
+
197
+
**output_id** (R):
198
+
Output number ID, zero based.
199
+
200
+
**video_source** (RW):
201
+
Output video source. If set to 0 or 1, the source is the corresponding card
202
+
input and the v4l2 output devices are disabled. If set to 2 or 3, the source
203
+
is the corresponding v4l2 video output device. The default is
204
+
the corresponding v4l2 output, i.e. 2 for OUT1 and 3 for OUT2.
205
+
206
+
| 0 - input 0
207
+
| 1 - input 1
208
+
| 2 - v4l2 output 0
209
+
| 3 - v4l2 output 1
210
+
211
+
*Note: This parameter can not be changed while ANY of the input/output v4l2
212
+
devices is open.*
213
+
214
+
**display_width** (RW):
215
+
Display width. There is no autodetection of the connected display, so the
216
+
proper value must be set before the start of streaming. The default width
217
+
is 1280.
218
+
219
+
*Note: This parameter can not be changed while the output v4l2 device is
220
+
open.*
221
+
222
+
**display_height** (RW):
223
+
Display height. There is no autodetection of the connected display, so the
224
+
proper value must be set before the start of streaming. The default height
225
+
is 640.
226
+
227
+
*Note: This parameter can not be changed while the output v4l2 device is
228
+
open.*
229
+
230
+
**frame_rate** (RW):
231
+
Output video frame rate in frames per second. The default frame rate is
232
+
60Hz.
233
+
234
+
**hsync_polarity** (RW):
235
+
HSYNC signal polarity.
236
+
237
+
| 0 - active low (default)
238
+
| 1 - active high
239
+
240
+
**vsync_polarity** (RW):
241
+
VSYNC signal polarity.
242
+
243
+
| 0 - active low (default)
244
+
| 1 - active high
245
+
246
+
**de_polarity** (RW):
247
+
DE signal polarity.
248
+
249
+
| 0 - active low
250
+
| 1 - active high (default)
251
+
252
+
**pclk_frequency** (RW):
253
+
Output pixel clock frequency. Allowed values are between 25000-190000(kHz)
254
+
and there is a non-linear stepping between two consecutive allowed
255
+
frequencies. The driver finds the nearest allowed frequency to the given
256
+
value and sets it. When reading this property, you get the exact
257
+
frequency set by the driver. The default frequency is 70000kHz.
258
+
259
+
*Note: This parameter can not be changed while the output v4l2 device is
260
+
open.*
261
+
262
+
**hsync_width** (RW):
263
+
Width of the HSYNC signal in pixels. The default value is 16.
264
+
265
+
**vsync_width** (RW):
266
+
Width of the VSYNC signal in video lines. The default value is 2.
267
+
268
+
**hback_porch** (RW):
269
+
Number of PCLK pulses between deassertion of the HSYNC signal and the first
270
+
valid pixel in the video line (marked by DE=1). The default value is 32.
271
+
272
+
**hfront_porch** (RW):
273
+
Number of PCLK pulses between the end of the last valid pixel in the video
274
+
line (marked by DE=1) and assertion of the HSYNC signal. The default value
275
+
is 32.
276
+
277
+
**vback_porch** (RW):
278
+
Number of video lines between deassertion of the VSYNC signal and the video
279
+
line with the first valid pixel (marked by DE=1). The default value is 2.
280
+
281
+
**vfront_porch** (RW):
282
+
Number of video lines between the end of the last valid pixel line (marked
283
+
by DE=1) and assertion of the VSYNC signal. The default value is 2.
284
+
285
+
286
+
FPDL3 specific input parameters
287
+
===============================
288
+
289
+
**fpdl3_input_width** (RW):
290
+
Number of deserializer input lines.
291
+
292
+
| 0 - auto (default)
293
+
| 1 - single
294
+
| 2 - dual
295
+
296
+
FPDL3 specific output parameters
297
+
================================
298
+
299
+
**fpdl3_output_width** (RW):
300
+
Number of serializer output lines.
301
+
302
+
| 0 - auto (default)
303
+
| 1 - single
304
+
| 2 - dual
305
+
306
+
GMSL specific input parameters
307
+
==============================
308
+
309
+
**gmsl_mode** (RW):
310
+
GMSL speed mode.
311
+
312
+
| 0 - 12Gb/s (default)
313
+
| 1 - 6Gb/s
314
+
| 2 - 3Gb/s
315
+
| 3 - 1.5Gb/s
316
+
317
+
**gmsl_stream_id** (RW):
318
+
The GMSL multi-stream contains up to four video streams. This parameter
319
+
selects which stream is captured by the video input. The value is the
320
+
zero-based index of the stream. The default stream id is 0.
321
+
322
+
*Note: This parameter can not be changed while the input v4l2 device is
323
+
open.*
324
+
325
+
**gmsl_fec** (RW):
326
+
GMSL Forward Error Correction (FEC).
327
+
328
+
| 0 - disabled
329
+
| 1 - enabled (default)
330
+
331
+
332
+
====================
333
+
mgb4 mtd partitions
334
+
====================
335
+
336
+
The mgb4 driver creates a MTD device with two partitions:
337
+
- mgb4-fw.X - FPGA firmware.
338
+
- mgb4-data.X - Factory settings, e.g. card serial number.
339
+
340
+
The *mgb4-fw* partition is writable and is used for FW updates, *mgb4-data* is
341
+
read-only. The *X* attached to the partition name represents the card number.
342
+
Depending on the CONFIG_MTD_PARTITIONED_MASTER kernel configuration, you may
343
+
also have a third partition named *mgb4-flash* available in the system. This
344
+
partition represents the whole, unpartitioned, card's FLASH memory and one should
345
+
not fiddle with it...
346
+
347
+
====================
348
+
mgb4 iio (triggers)
349
+
====================
350
+
351
+
The mgb4 driver creates an Industrial I/O (IIO) device that provides trigger and
352
+
signal level status capability. The following scan elements are available:
353
+
354
+
**activity**:
355
+
The trigger levels and pending status.
356
+
357
+
| bit 1 - trigger 1 pending
358
+
| bit 2 - trigger 2 pending
359
+
| bit 5 - trigger 1 level
360
+
| bit 6 - trigger 2 level
361
+
362
+
**timestamp**:
363
+
The trigger event timestamp.
364
+
365
+
The iio device can operate either in "raw" mode where you can fetch the signal
366
+
levels (activity bits 5 and 6) using sysfs access or in triggered buffer mode.
367
+
In the triggered buffer mode you can follow the signal level changes (activity
368
+
bits 1 and 2) using the iio device in /dev. If you enable the timestamps, you
369
+
will also get the exact trigger event time that can be matched to a video frame
370
+
(every mgb4 video frame has a timestamp with the same clock source).
371
+
372
+
*Note: although the activity sample always contains all the status bits, it makes
373
+
no sense to get the pending bits in raw mode or the level bits in the triggered
374
+
buffer mode - the values do not represent valid data in such case.*
+1
Documentation/admin-guide/media/pci-cardlist.rst
+1
Documentation/admin-guide/media/pci-cardlist.rst
···
77
77
ivtv Conexant cx23416/cx23415 MPEG encoder/decoder
78
78
ivtvfb Conexant cx23415 framebuffer
79
79
mantis MANTIS based cards
80
+
mgb4 Digiteq Automotive MGB4 frame grabber
80
81
mxb Siemens-Nixdorf 'Multimedia eXtension Board'
81
82
netup-unidvb NetUP Universal DVB card
82
83
ngene Micronas nGene