Commit | Line | Data |
---|---|---|
f2ac8ce8 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
cff4c8ac MCC |
3 | The Virtual Video Test Driver (vivid) |
4 | ===================================== | |
6a683493 HV |
5 | |
6 | This driver emulates video4linux hardware of various types: video capture, video | |
7 | output, vbi capture and output, radio receivers and transmitters and a software | |
8 | defined radio receiver. In addition a simple framebuffer device is available for | |
9 | testing capture and output overlays. | |
10 | ||
11 | Up to 64 vivid instances can be created, each with up to 16 inputs and 16 outputs. | |
12 | ||
13 | Each input can be a webcam, TV capture device, S-Video capture device or an HDMI | |
14 | capture device. Each output can be an S-Video output device or an HDMI output | |
15 | device. | |
16 | ||
17 | These inputs and outputs act exactly as a real hardware device would behave. This | |
18 | allows you to use this driver as a test input for application development, since | |
19 | you can test the various features without requiring special hardware. | |
20 | ||
21 | This document describes the features implemented by this driver: | |
22 | ||
23 | - Support for read()/write(), MMAP, USERPTR and DMABUF streaming I/O. | |
24 | - A large list of test patterns and variations thereof | |
25 | - Working brightness, contrast, saturation and hue controls | |
26 | - Support for the alpha color component | |
27 | - Full colorspace support, including limited/full RGB range | |
28 | - All possible control types are present | |
29 | - Support for various pixel aspect ratios and video aspect ratios | |
30 | - Error injection to test what happens if errors occur | |
31 | - Supports crop/compose/scale in any combination for both input and output | |
32 | - Can emulate up to 4K resolutions | |
33 | - All Field settings are supported for testing interlaced capturing | |
34 | - Supports all standard YUV and RGB formats, including two multiplanar YUV formats | |
35 | - Raw and Sliced VBI capture and output support | |
36 | - Radio receiver and transmitter support, including RDS support | |
37 | - Software defined radio (SDR) support | |
38 | - Capture and output overlay support | |
39 | ||
40 | These features will be described in more detail below. | |
41 | ||
cff4c8ac MCC |
42 | Configuring the driver |
43 | ---------------------- | |
6a683493 HV |
44 | |
45 | By default the driver will create a single instance that has a video capture | |
46 | device with webcam, TV, S-Video and HDMI inputs, a video output device with | |
47 | S-Video and HDMI outputs, one vbi capture device, one vbi output device, one | |
48 | radio receiver device, one radio transmitter device and one SDR device. | |
49 | ||
50 | The number of instances, devices, video inputs and outputs and their types are | |
51 | all configurable using the following module options: | |
52 | ||
cff4c8ac MCC |
53 | - n_devs: |
54 | ||
55 | number of driver instances to create. By default set to 1. Up to 64 | |
6a683493 HV |
56 | instances can be created. |
57 | ||
cff4c8ac MCC |
58 | - node_types: |
59 | ||
60 | which devices should each driver instance create. An array of | |
6a683493 HV |
61 | hexadecimal values, one for each instance. The default is 0x1d3d. |
62 | Each value is a bitmask with the following meaning: | |
cff4c8ac MCC |
63 | |
64 | - bit 0: Video Capture node | |
65 | - bit 2-3: VBI Capture node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both | |
66 | - bit 4: Radio Receiver node | |
67 | - bit 5: Software Defined Radio Receiver node | |
68 | - bit 8: Video Output node | |
69 | - bit 10-11: VBI Output node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both | |
70 | - bit 12: Radio Transmitter node | |
71 | - bit 16: Framebuffer for testing overlays | |
6a683493 HV |
72 | |
73 | So to create four instances, the first two with just one video capture | |
74 | device, the second two with just one video output device you would pass | |
75 | these module options to vivid: | |
76 | ||
cff4c8ac MCC |
77 | .. code-block:: none |
78 | ||
6a683493 HV |
79 | n_devs=4 node_types=0x1,0x1,0x100,0x100 |
80 | ||
cff4c8ac MCC |
81 | - num_inputs: |
82 | ||
83 | the number of inputs, one for each instance. By default 4 inputs | |
6a683493 HV |
84 | are created for each video capture device. At most 16 inputs can be created, |
85 | and there must be at least one. | |
86 | ||
cff4c8ac MCC |
87 | - input_types: |
88 | ||
89 | the input types for each instance, the default is 0xe4. This defines | |
6a683493 HV |
90 | what the type of each input is when the inputs are created for each driver |
91 | instance. This is a hexadecimal value with up to 16 pairs of bits, each | |
92 | pair gives the type and bits 0-1 map to input 0, bits 2-3 map to input 1, | |
93 | 30-31 map to input 15. Each pair of bits has the following meaning: | |
94 | ||
cff4c8ac MCC |
95 | - 00: this is a webcam input |
96 | - 01: this is a TV tuner input | |
97 | - 10: this is an S-Video input | |
98 | - 11: this is an HDMI input | |
6a683493 HV |
99 | |
100 | So to create a video capture device with 8 inputs where input 0 is a TV | |
101 | tuner, inputs 1-3 are S-Video inputs and inputs 4-7 are HDMI inputs you | |
102 | would use the following module options: | |
103 | ||
cff4c8ac MCC |
104 | .. code-block:: none |
105 | ||
6a683493 HV |
106 | num_inputs=8 input_types=0xffa9 |
107 | ||
cff4c8ac MCC |
108 | - num_outputs: |
109 | ||
110 | the number of outputs, one for each instance. By default 2 outputs | |
6a683493 HV |
111 | are created for each video output device. At most 16 outputs can be |
112 | created, and there must be at least one. | |
113 | ||
cff4c8ac MCC |
114 | - output_types: |
115 | ||
116 | the output types for each instance, the default is 0x02. This defines | |
6a683493 HV |
117 | what the type of each output is when the outputs are created for each |
118 | driver instance. This is a hexadecimal value with up to 16 bits, each bit | |
119 | gives the type and bit 0 maps to output 0, bit 1 maps to output 1, bit | |
120 | 15 maps to output 15. The meaning of each bit is as follows: | |
121 | ||
cff4c8ac MCC |
122 | - 0: this is an S-Video output |
123 | - 1: this is an HDMI output | |
6a683493 HV |
124 | |
125 | So to create a video output device with 8 outputs where outputs 0-3 are | |
126 | S-Video outputs and outputs 4-7 are HDMI outputs you would use the | |
127 | following module options: | |
128 | ||
cff4c8ac MCC |
129 | .. code-block:: none |
130 | ||
6a683493 HV |
131 | num_outputs=8 output_types=0xf0 |
132 | ||
cff4c8ac MCC |
133 | - vid_cap_nr: |
134 | ||
135 | give the desired videoX start number for each video capture device. | |
6a683493 HV |
136 | The default is -1 which will just take the first free number. This allows |
137 | you to map capture video nodes to specific videoX device nodes. Example: | |
138 | ||
cff4c8ac MCC |
139 | .. code-block:: none |
140 | ||
6a683493 HV |
141 | n_devs=4 vid_cap_nr=2,4,6,8 |
142 | ||
143 | This will attempt to assign /dev/video2 for the video capture device of | |
144 | the first vivid instance, video4 for the next up to video8 for the last | |
145 | instance. If it can't succeed, then it will just take the next free | |
146 | number. | |
147 | ||
cff4c8ac MCC |
148 | - vid_out_nr: |
149 | ||
150 | give the desired videoX start number for each video output device. | |
151 | The default is -1 which will just take the first free number. | |
152 | ||
153 | - vbi_cap_nr: | |
6a683493 | 154 | |
cff4c8ac MCC |
155 | give the desired vbiX start number for each vbi capture device. |
156 | The default is -1 which will just take the first free number. | |
6a683493 | 157 | |
cff4c8ac | 158 | - vbi_out_nr: |
6a683493 | 159 | |
cff4c8ac MCC |
160 | give the desired vbiX start number for each vbi output device. |
161 | The default is -1 which will just take the first free number. | |
6a683493 | 162 | |
cff4c8ac MCC |
163 | - radio_rx_nr: |
164 | ||
165 | give the desired radioX start number for each radio receiver device. | |
166 | The default is -1 which will just take the first free number. | |
167 | ||
168 | - radio_tx_nr: | |
169 | ||
170 | give the desired radioX start number for each radio transmitter | |
6a683493 HV |
171 | device. The default is -1 which will just take the first free number. |
172 | ||
cff4c8ac MCC |
173 | - sdr_cap_nr: |
174 | ||
175 | give the desired swradioX start number for each SDR capture device. | |
176 | The default is -1 which will just take the first free number. | |
177 | ||
178 | - ccs_cap_mode: | |
6a683493 | 179 | |
cff4c8ac | 180 | specify the allowed video capture crop/compose/scaling combination |
6a683493 HV |
181 | for each driver instance. Video capture devices can have any combination |
182 | of cropping, composing and scaling capabilities and this will tell the | |
183 | vivid driver which of those is should emulate. By default the user can | |
184 | select this through controls. | |
185 | ||
186 | The value is either -1 (controlled by the user) or a set of three bits, | |
187 | each enabling (1) or disabling (0) one of the features: | |
188 | ||
cff4c8ac MCC |
189 | - bit 0: |
190 | ||
191 | Enable crop support. Cropping will take only part of the | |
192 | incoming picture. | |
193 | - bit 1: | |
194 | ||
195 | Enable compose support. Composing will copy the incoming | |
196 | picture into a larger buffer. | |
197 | ||
198 | - bit 2: | |
199 | ||
200 | Enable scaling support. Scaling can scale the incoming | |
201 | picture. The scaler of the vivid driver can enlarge up | |
202 | or down to four times the original size. The scaler is | |
203 | very simple and low-quality. Simplicity and speed were | |
204 | key, not quality. | |
6a683493 HV |
205 | |
206 | Note that this value is ignored by webcam inputs: those enumerate | |
207 | discrete framesizes and that is incompatible with cropping, composing | |
208 | or scaling. | |
209 | ||
cff4c8ac MCC |
210 | - ccs_out_mode: |
211 | ||
212 | specify the allowed video output crop/compose/scaling combination | |
6a683493 HV |
213 | for each driver instance. Video output devices can have any combination |
214 | of cropping, composing and scaling capabilities and this will tell the | |
215 | vivid driver which of those is should emulate. By default the user can | |
216 | select this through controls. | |
217 | ||
218 | The value is either -1 (controlled by the user) or a set of three bits, | |
219 | each enabling (1) or disabling (0) one of the features: | |
220 | ||
cff4c8ac MCC |
221 | - bit 0: |
222 | ||
223 | Enable crop support. Cropping will take only part of the | |
224 | outgoing buffer. | |
225 | ||
226 | - bit 1: | |
227 | ||
228 | Enable compose support. Composing will copy the incoming | |
229 | buffer into a larger picture frame. | |
230 | ||
231 | - bit 2: | |
232 | ||
233 | Enable scaling support. Scaling can scale the incoming | |
234 | buffer. The scaler of the vivid driver can enlarge up | |
235 | or down to four times the original size. The scaler is | |
236 | very simple and low-quality. Simplicity and speed were | |
237 | key, not quality. | |
238 | ||
239 | - multiplanar: | |
240 | ||
241 | select whether each device instance supports multi-planar formats, | |
cba63cf8 HV |
242 | and thus the V4L2 multi-planar API. By default device instances are |
243 | single-planar. | |
6a683493 HV |
244 | |
245 | This module option can override that for each instance. Values are: | |
246 | ||
cff4c8ac MCC |
247 | - 1: this is a single-planar instance. |
248 | - 2: this is a multi-planar instance. | |
6a683493 | 249 | |
cff4c8ac | 250 | - vivid_debug: |
6a683493 | 251 | |
cff4c8ac MCC |
252 | enable driver debugging info |
253 | ||
254 | - no_error_inj: | |
255 | ||
256 | if set disable the error injecting controls. This option is | |
6a683493 HV |
257 | needed in order to run a tool like v4l2-compliance. Tools like that |
258 | exercise all controls including a control like 'Disconnect' which | |
259 | emulates a USB disconnect, making the device inaccessible and so | |
260 | all tests that v4l2-compliance is doing will fail afterwards. | |
261 | ||
262 | There may be other situations as well where you want to disable the | |
263 | error injection support of vivid. When this option is set, then the | |
264 | controls that select crop, compose and scale behavior are also | |
265 | removed. Unless overridden by ccs_cap_mode and/or ccs_out_mode the | |
266 | will default to enabling crop, compose and scaling. | |
267 | ||
8ecc5413 VA |
268 | - allocators: |
269 | ||
270 | memory allocator selection, default is 0. It specifies the way buffers | |
271 | will be allocated. | |
272 | ||
273 | - 0: vmalloc | |
274 | - 1: dma-contig | |
275 | ||
6a683493 HV |
276 | Taken together, all these module options allow you to precisely customize |
277 | the driver behavior and test your application with all sorts of permutations. | |
278 | It is also very suitable to emulate hardware that is not yet available, e.g. | |
279 | when developing software for a new upcoming device. | |
280 | ||
281 | ||
cff4c8ac MCC |
282 | Video Capture |
283 | ------------- | |
6a683493 HV |
284 | |
285 | This is probably the most frequently used feature. The video capture device | |
286 | can be configured by using the module options num_inputs, input_types and | |
287 | ccs_cap_mode (see section 1 for more detailed information), but by default | |
288 | four inputs are configured: a webcam, a TV tuner, an S-Video and an HDMI | |
289 | input, one input for each input type. Those are described in more detail | |
290 | below. | |
291 | ||
292 | Special attention has been given to the rate at which new frames become | |
293 | available. The jitter will be around 1 jiffie (that depends on the HZ | |
294 | configuration of your kernel, so usually 1/100, 1/250 or 1/1000 of a second), | |
295 | but the long-term behavior is exactly following the framerate. So a | |
296 | framerate of 59.94 Hz is really different from 60 Hz. If the framerate | |
297 | exceeds your kernel's HZ value, then you will get dropped frames, but the | |
298 | frame/field sequence counting will keep track of that so the sequence | |
299 | count will skip whenever frames are dropped. | |
300 | ||
301 | ||
cff4c8ac MCC |
302 | Webcam Input |
303 | ~~~~~~~~~~~~ | |
6a683493 HV |
304 | |
305 | The webcam input supports three framesizes: 320x180, 640x360 and 1280x720. It | |
306 | supports frames per second settings of 10, 15, 25, 30, 50 and 60 fps. Which ones | |
307 | are available depends on the chosen framesize: the larger the framesize, the | |
308 | lower the maximum frames per second. | |
309 | ||
310 | The initially selected colorspace when you switch to the webcam input will be | |
311 | sRGB. | |
312 | ||
313 | ||
cff4c8ac MCC |
314 | TV and S-Video Inputs |
315 | ~~~~~~~~~~~~~~~~~~~~~ | |
6a683493 HV |
316 | |
317 | The only difference between the TV and S-Video input is that the TV has a | |
318 | tuner. Otherwise they behave identically. | |
319 | ||
320 | These inputs support audio inputs as well: one TV and one Line-In. They | |
321 | both support all TV standards. If the standard is queried, then the Vivid | |
322 | controls 'Standard Signal Mode' and 'Standard' determine what | |
323 | the result will be. | |
324 | ||
325 | These inputs support all combinations of the field setting. Special care has | |
326 | been taken to faithfully reproduce how fields are handled for the different | |
1a2b2c70 | 327 | TV standards. This is particularly noticeable when generating a horizontally |
6a683493 HV |
328 | moving image so the temporal effect of using interlaced formats becomes clearly |
329 | visible. For 50 Hz standards the top field is the oldest and the bottom field | |
330 | is the newest in time. For 60 Hz standards that is reversed: the bottom field | |
331 | is the oldest and the top field is the newest in time. | |
332 | ||
333 | When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will | |
334 | contain the top field for 50 Hz standards and the bottom field for 60 Hz | |
335 | standards. This is what capture hardware does as well. | |
336 | ||
337 | Finally, for PAL/SECAM standards the first half of the top line contains noise. | |
338 | This simulates the Wide Screen Signal that is commonly placed there. | |
339 | ||
340 | The initially selected colorspace when you switch to the TV or S-Video input | |
341 | will be SMPTE-170M. | |
342 | ||
343 | The pixel aspect ratio will depend on the TV standard. The video aspect ratio | |
344 | can be selected through the 'Standard Aspect Ratio' Vivid control. | |
345 | Choices are '4x3', '16x9' which will give letterboxed widescreen video and | |
1a2b2c70 | 346 | '16x9 Anamorphic' which will give full screen squashed anamorphic widescreen |
6a683493 HV |
347 | video that will need to be scaled accordingly. |
348 | ||
349 | The TV 'tuner' supports a frequency range of 44-958 MHz. Channels are available | |
350 | every 6 MHz, starting from 49.25 MHz. For each channel the generated image | |
351 | will be in color for the +/- 0.25 MHz around it, and in grayscale for | |
352 | +/- 1 MHz around the channel. Beyond that it is just noise. The VIDIOC_G_TUNER | |
353 | ioctl will return 100% signal strength for +/- 0.25 MHz and 50% for +/- 1 MHz. | |
354 | It will also return correct afc values to show whether the frequency is too | |
355 | low or too high. | |
356 | ||
357 | The audio subchannels that are returned are MONO for the +/- 1 MHz range around | |
358 | a valid channel frequency. When the frequency is within +/- 0.25 MHz of the | |
359 | channel it will return either MONO, STEREO, either MONO | SAP (for NTSC) or | |
360 | LANG1 | LANG2 (for others), or STEREO | SAP. | |
361 | ||
362 | Which one is returned depends on the chosen channel, each next valid channel | |
363 | will cycle through the possible audio subchannel combinations. This allows | |
364 | you to test the various combinations by just switching channels.. | |
365 | ||
366 | Finally, for these inputs the v4l2_timecode struct is filled in in the | |
367 | dequeued v4l2_buffer struct. | |
368 | ||
369 | ||
cff4c8ac MCC |
370 | HDMI Input |
371 | ~~~~~~~~~~ | |
6a683493 HV |
372 | |
373 | The HDMI inputs supports all CEA-861 and DMT timings, both progressive and | |
374 | interlaced, for pixelclock frequencies between 25 and 600 MHz. The field | |
375 | mode for interlaced formats is always V4L2_FIELD_ALTERNATE. For HDMI the | |
376 | field order is always top field first, and when you start capturing an | |
377 | interlaced format you will receive the top field first. | |
378 | ||
379 | The initially selected colorspace when you switch to the HDMI input or | |
380 | select an HDMI timing is based on the format resolution: for resolutions | |
381 | less than or equal to 720x576 the colorspace is set to SMPTE-170M, for | |
382 | others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings). | |
383 | ||
384 | The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it | |
385 | set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV | |
386 | standard, and for all others a 1:1 pixel aspect ratio is returned. | |
387 | ||
388 | The video aspect ratio can be selected through the 'DV Timings Aspect Ratio' | |
389 | Vivid control. Choices are 'Source Width x Height' (just use the | |
390 | same ratio as the chosen format), '4x3' or '16x9', either of which can | |
391 | result in pillarboxed or letterboxed video. | |
392 | ||
393 | For HDMI inputs it is possible to set the EDID. By default a simple EDID | |
394 | is provided. You can only set the EDID for HDMI inputs. Internally, however, | |
395 | the EDID is shared between all HDMI inputs. | |
396 | ||
6f8adea2 HV |
397 | No interpretation is done of the EDID data with the exception of the |
398 | physical address. See the CEC section for more details. | |
399 | ||
400 | There is a maximum of 15 HDMI inputs (if there are more, then they will be | |
401 | reduced to 15) since that's the limitation of the EDID physical address. | |
6a683493 HV |
402 | |
403 | ||
cff4c8ac MCC |
404 | Video Output |
405 | ------------ | |
6a683493 HV |
406 | |
407 | The video output device can be configured by using the module options | |
408 | num_outputs, output_types and ccs_out_mode (see section 1 for more detailed | |
409 | information), but by default two outputs are configured: an S-Video and an | |
410 | HDMI input, one output for each output type. Those are described in more detail | |
411 | below. | |
412 | ||
413 | Like with video capture the framerate is also exact in the long term. | |
414 | ||
415 | ||
cff4c8ac MCC |
416 | S-Video Output |
417 | ~~~~~~~~~~~~~~ | |
6a683493 HV |
418 | |
419 | This output supports audio outputs as well: "Line-Out 1" and "Line-Out 2". | |
420 | The S-Video output supports all TV standards. | |
421 | ||
422 | This output supports all combinations of the field setting. | |
423 | ||
424 | The initially selected colorspace when you switch to the TV or S-Video input | |
425 | will be SMPTE-170M. | |
426 | ||
427 | ||
cff4c8ac MCC |
428 | HDMI Output |
429 | ~~~~~~~~~~~ | |
6a683493 HV |
430 | |
431 | The HDMI output supports all CEA-861 and DMT timings, both progressive and | |
432 | interlaced, for pixelclock frequencies between 25 and 600 MHz. The field | |
433 | mode for interlaced formats is always V4L2_FIELD_ALTERNATE. | |
434 | ||
435 | The initially selected colorspace when you switch to the HDMI output or | |
436 | select an HDMI timing is based on the format resolution: for resolutions | |
437 | less than or equal to 720x576 the colorspace is set to SMPTE-170M, for | |
438 | others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings). | |
439 | ||
440 | The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it | |
441 | set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV | |
442 | standard, and for all others a 1:1 pixel aspect ratio is returned. | |
443 | ||
444 | An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID. | |
445 | ||
6f8adea2 HV |
446 | There is a maximum of 15 HDMI outputs (if there are more, then they will be |
447 | reduced to 15) since that's the limitation of the EDID physical address. See | |
448 | also the CEC section for more details. | |
6a683493 | 449 | |
cff4c8ac MCC |
450 | VBI Capture |
451 | ----------- | |
6a683493 HV |
452 | |
453 | There are three types of VBI capture devices: those that only support raw | |
454 | (undecoded) VBI, those that only support sliced (decoded) VBI and those that | |
455 | support both. This is determined by the node_types module option. In all | |
456 | cases the driver will generate valid VBI data: for 60 Hz standards it will | |
457 | generate Closed Caption and XDS data. The closed caption stream will | |
458 | alternate between "Hello world!" and "Closed captions test" every second. | |
459 | The XDS stream will give the current time once a minute. For 50 Hz standards | |
460 | it will generate the Wide Screen Signal which is based on the actual Video | |
62f28725 | 461 | Aspect Ratio control setting and teletext pages 100-159, one page per frame. |
6a683493 HV |
462 | |
463 | The VBI device will only work for the S-Video and TV inputs, it will give | |
464 | back an error if the current input is a webcam or HDMI. | |
465 | ||
466 | ||
cff4c8ac MCC |
467 | VBI Output |
468 | ---------- | |
6a683493 HV |
469 | |
470 | There are three types of VBI output devices: those that only support raw | |
471 | (undecoded) VBI, those that only support sliced (decoded) VBI and those that | |
472 | support both. This is determined by the node_types module option. | |
473 | ||
62f28725 HV |
474 | The sliced VBI output supports the Wide Screen Signal and the teletext signal |
475 | for 50 Hz standards and Closed Captioning + XDS for 60 Hz standards. | |
6a683493 HV |
476 | |
477 | The VBI device will only work for the S-Video output, it will give | |
478 | back an error if the current output is HDMI. | |
479 | ||
480 | ||
cff4c8ac MCC |
481 | Radio Receiver |
482 | -------------- | |
6a683493 HV |
483 | |
484 | The radio receiver emulates an FM/AM/SW receiver. The FM band also supports RDS. | |
485 | The frequency ranges are: | |
486 | ||
cff4c8ac MCC |
487 | - FM: 64 MHz - 108 MHz |
488 | - AM: 520 kHz - 1710 kHz | |
489 | - SW: 2300 kHz - 26.1 MHz | |
6a683493 HV |
490 | |
491 | Valid channels are emulated every 1 MHz for FM and every 100 kHz for AM and SW. | |
492 | The signal strength decreases the further the frequency is from the valid | |
493 | frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the | |
494 | ideal frequency. The initial frequency when the driver is loaded is set to | |
495 | 95 MHz. | |
496 | ||
497 | The FM receiver supports RDS as well, both using 'Block I/O' and 'Controls' | |
498 | modes. In the 'Controls' mode the RDS information is stored in read-only | |
499 | controls. These controls are updated every time the frequency is changed, | |
500 | or when the tuner status is requested. The Block I/O method uses the read() | |
501 | interface to pass the RDS blocks on to the application for decoding. | |
502 | ||
503 | The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency, | |
504 | and the further the frequency is away from the valid frequency the more RDS | |
505 | errors are randomly introduced into the block I/O stream, up to 50% of all | |
506 | blocks if you are +/- 12.5 kHz from the channel frequency. All four errors | |
507 | can occur in equal proportions: blocks marked 'CORRECTED', blocks marked | |
508 | 'ERROR', blocks marked 'INVALID' and dropped blocks. | |
509 | ||
510 | The generated RDS stream contains all the standard fields contained in a | |
511 | 0B group, and also radio text and the current time. | |
512 | ||
513 | The receiver supports HW frequency seek, either in Bounded mode, Wrap Around | |
514 | mode or both, which is configurable with the "Radio HW Seek Mode" control. | |
515 | ||
516 | ||
cff4c8ac MCC |
517 | Radio Transmitter |
518 | ----------------- | |
6a683493 HV |
519 | |
520 | The radio transmitter emulates an FM/AM/SW transmitter. The FM band also supports RDS. | |
521 | The frequency ranges are: | |
522 | ||
cff4c8ac MCC |
523 | - FM: 64 MHz - 108 MHz |
524 | - AM: 520 kHz - 1710 kHz | |
525 | - SW: 2300 kHz - 26.1 MHz | |
6a683493 HV |
526 | |
527 | The initial frequency when the driver is loaded is 95.5 MHz. | |
528 | ||
529 | The FM transmitter supports RDS as well, both using 'Block I/O' and 'Controls' | |
530 | modes. In the 'Controls' mode the transmitted RDS information is configured | |
531 | using controls, and in 'Block I/O' mode the blocks are passed to the driver | |
532 | using write(). | |
533 | ||
534 | ||
cff4c8ac MCC |
535 | Software Defined Radio Receiver |
536 | ------------------------------- | |
6a683493 HV |
537 | |
538 | The SDR receiver has three frequency bands for the ADC tuner: | |
539 | ||
540 | - 300 kHz | |
541 | - 900 kHz - 2800 kHz | |
542 | - 3200 kHz | |
543 | ||
544 | The RF tuner supports 50 MHz - 2000 MHz. | |
545 | ||
546 | The generated data contains the In-phase and Quadrature components of a | |
547 | 1 kHz tone that has an amplitude of sqrt(2). | |
548 | ||
549 | ||
cff4c8ac MCC |
550 | Controls |
551 | -------- | |
6a683493 HV |
552 | |
553 | Different devices support different controls. The sections below will describe | |
554 | each control and which devices support them. | |
555 | ||
556 | ||
cff4c8ac MCC |
557 | User Controls - Test Controls |
558 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
6a683493 HV |
559 | |
560 | The Button, Boolean, Integer 32 Bits, Integer 64 Bits, Menu, String, Bitmask and | |
561 | Integer Menu are controls that represent all possible control types. The Menu | |
562 | control and the Integer Menu control both have 'holes' in their menu list, | |
563 | meaning that one or more menu items return EINVAL when VIDIOC_QUERYMENU is called. | |
564 | Both menu controls also have a non-zero minimum control value. These features | |
565 | allow you to check if your application can handle such things correctly. | |
566 | These controls are supported for every device type. | |
567 | ||
568 | ||
cff4c8ac MCC |
569 | User Controls - Video Capture |
570 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
6a683493 HV |
571 | |
572 | The following controls are specific to video capture. | |
573 | ||
574 | The Brightness, Contrast, Saturation and Hue controls actually work and are | |
575 | standard. There is one special feature with the Brightness control: each | |
576 | video input has its own brightness value, so changing input will restore | |
577 | the brightness for that input. In addition, each video input uses a different | |
578 | brightness range (minimum and maximum control values). Switching inputs will | |
579 | cause a control event to be sent with the V4L2_EVENT_CTRL_CH_RANGE flag set. | |
580 | This allows you to test controls that can change their range. | |
581 | ||
582 | The 'Gain, Automatic' and Gain controls can be used to test volatile controls: | |
583 | if 'Gain, Automatic' is set, then the Gain control is volatile and changes | |
584 | constantly. If 'Gain, Automatic' is cleared, then the Gain control is a normal | |
585 | control. | |
586 | ||
587 | The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the | |
588 | image. These combine with the 'Sensor Flipped Horizontally/Vertically' Vivid | |
589 | controls. | |
590 | ||
591 | The 'Alpha Component' control can be used to set the alpha component for | |
592 | formats containing an alpha channel. | |
593 | ||
594 | ||
cff4c8ac MCC |
595 | User Controls - Audio |
596 | ~~~~~~~~~~~~~~~~~~~~~ | |
6a683493 HV |
597 | |
598 | The following controls are specific to video capture and output and radio | |
599 | receivers and transmitters. | |
600 | ||
601 | The 'Volume' and 'Mute' audio controls are typical for such devices to | |
602 | control the volume and mute the audio. They don't actually do anything in | |
603 | the vivid driver. | |
604 | ||
605 | ||
cff4c8ac MCC |
606 | Vivid Controls |
607 | ~~~~~~~~~~~~~~ | |
6a683493 HV |
608 | |
609 | These vivid custom controls control the image generation, error injection, etc. | |
610 | ||
611 | ||
cff4c8ac MCC |
612 | Test Pattern Controls |
613 | ^^^^^^^^^^^^^^^^^^^^^ | |
6a683493 HV |
614 | |
615 | The Test Pattern Controls are all specific to video capture. | |
616 | ||
cff4c8ac MCC |
617 | - Test Pattern: |
618 | ||
619 | selects which test pattern to use. Use the CSC Colorbar for | |
6a683493 HV |
620 | testing colorspace conversions: the colors used in that test pattern |
621 | map to valid colors in all colorspaces. The colorspace conversion | |
622 | is disabled for the other test patterns. | |
623 | ||
cff4c8ac MCC |
624 | - OSD Text Mode: |
625 | ||
626 | selects whether the text superimposed on the | |
6a683493 HV |
627 | test pattern should be shown, and if so, whether only counters should |
628 | be displayed or the full text. | |
629 | ||
cff4c8ac MCC |
630 | - Horizontal Movement: |
631 | ||
632 | selects whether the test pattern should | |
6a683493 HV |
633 | move to the left or right and at what speed. |
634 | ||
cff4c8ac MCC |
635 | - Vertical Movement: |
636 | ||
637 | does the same for the vertical direction. | |
638 | ||
639 | - Show Border: | |
6a683493 | 640 | |
cff4c8ac | 641 | show a two-pixel wide border at the edge of the actual image, |
6a683493 HV |
642 | excluding letter or pillarboxing. |
643 | ||
cff4c8ac MCC |
644 | - Show Square: |
645 | ||
646 | show a square in the middle of the image. If the image is | |
6a683493 HV |
647 | displayed with the correct pixel and image aspect ratio corrections, |
648 | then the width and height of the square on the monitor should be | |
649 | the same. | |
650 | ||
cff4c8ac MCC |
651 | - Insert SAV Code in Image: |
652 | ||
653 | adds a SAV (Start of Active Video) code to the image. | |
6a683493 HV |
654 | This can be used to check if such codes in the image are inadvertently |
655 | interpreted instead of being ignored. | |
656 | ||
cff4c8ac | 657 | - Insert EAV Code in Image: |
6a683493 | 658 | |
cff4c8ac | 659 | does the same for the EAV (End of Active Video) code. |
6a683493 | 660 | |
cff4c8ac MCC |
661 | |
662 | Capture Feature Selection Controls | |
663 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
6a683493 HV |
664 | |
665 | These controls are all specific to video capture. | |
666 | ||
cff4c8ac MCC |
667 | - Sensor Flipped Horizontally: |
668 | ||
669 | the image is flipped horizontally and the | |
6a683493 HV |
670 | V4L2_IN_ST_HFLIP input status flag is set. This emulates the case where |
671 | a sensor is for example mounted upside down. | |
672 | ||
cff4c8ac MCC |
673 | - Sensor Flipped Vertically: |
674 | ||
675 | the image is flipped vertically and the | |
6a683493 | 676 | V4L2_IN_ST_VFLIP input status flag is set. This emulates the case where |
cff4c8ac MCC |
677 | a sensor is for example mounted upside down. |
678 | ||
679 | - Standard Aspect Ratio: | |
6a683493 | 680 | |
cff4c8ac | 681 | selects if the image aspect ratio as used for the TV or |
6a683493 HV |
682 | S-Video input should be 4x3, 16x9 or anamorphic widescreen. This may |
683 | introduce letterboxing. | |
684 | ||
cff4c8ac MCC |
685 | - DV Timings Aspect Ratio: |
686 | ||
687 | selects if the image aspect ratio as used for the HDMI | |
6a683493 HV |
688 | input should be the same as the source width and height ratio, or if |
689 | it should be 4x3 or 16x9. This may introduce letter or pillarboxing. | |
690 | ||
cff4c8ac MCC |
691 | - Timestamp Source: |
692 | ||
693 | selects when the timestamp for each buffer is taken. | |
6a683493 | 694 | |
cff4c8ac MCC |
695 | - Colorspace: |
696 | ||
697 | selects which colorspace should be used when generating the image. | |
6a683493 | 698 | This only applies if the CSC Colorbar test pattern is selected, |
64d57022 HV |
699 | otherwise the test pattern will go through unconverted. |
700 | This behavior is also what you want, since a 75% Colorbar | |
6a683493 HV |
701 | should really have 75% signal intensity and should not be affected |
702 | by colorspace conversions. | |
703 | ||
704 | Changing the colorspace will result in the V4L2_EVENT_SOURCE_CHANGE | |
705 | to be sent since it emulates a detected colorspace change. | |
706 | ||
cff4c8ac MCC |
707 | - Transfer Function: |
708 | ||
709 | selects which colorspace transfer function should be used when | |
64d57022 HV |
710 | generating an image. This only applies if the CSC Colorbar test pattern is |
711 | selected, otherwise the test pattern will go through unconverted. | |
cff4c8ac MCC |
712 | This behavior is also what you want, since a 75% Colorbar |
713 | should really have 75% signal intensity and should not be affected | |
714 | by colorspace conversions. | |
64d57022 HV |
715 | |
716 | Changing the transfer function will result in the V4L2_EVENT_SOURCE_CHANGE | |
717 | to be sent since it emulates a detected colorspace change. | |
718 | ||
cff4c8ac MCC |
719 | - Y'CbCr Encoding: |
720 | ||
721 | selects which Y'CbCr encoding should be used when generating | |
64d57022 HV |
722 | a Y'CbCr image. This only applies if the format is set to a Y'CbCr format |
723 | as opposed to an RGB format. | |
38913a5c HV |
724 | |
725 | Changing the Y'CbCr encoding will result in the V4L2_EVENT_SOURCE_CHANGE | |
726 | to be sent since it emulates a detected colorspace change. | |
727 | ||
cff4c8ac MCC |
728 | - Quantization: |
729 | ||
730 | selects which quantization should be used for the RGB or Y'CbCr | |
64d57022 | 731 | encoding when generating the test pattern. |
38913a5c HV |
732 | |
733 | Changing the quantization will result in the V4L2_EVENT_SOURCE_CHANGE | |
734 | to be sent since it emulates a detected colorspace change. | |
735 | ||
cff4c8ac MCC |
736 | - Limited RGB Range (16-235): |
737 | ||
738 | selects if the RGB range of the HDMI source should | |
6a683493 HV |
739 | be limited or full range. This combines with the Digital Video 'Rx RGB |
740 | Quantization Range' control and can be used to test what happens if | |
741 | a source provides you with the wrong quantization range information. | |
742 | See the description of that control for more details. | |
743 | ||
cff4c8ac MCC |
744 | - Apply Alpha To Red Only: |
745 | ||
746 | apply the alpha channel as set by the 'Alpha Component' | |
6a683493 HV |
747 | user control to the red color of the test pattern only. |
748 | ||
cff4c8ac MCC |
749 | - Enable Capture Cropping: |
750 | ||
751 | enables crop support. This control is only present if | |
6a683493 HV |
752 | the ccs_cap_mode module option is set to the default value of -1 and if |
753 | the no_error_inj module option is set to 0 (the default). | |
754 | ||
cff4c8ac MCC |
755 | - Enable Capture Composing: |
756 | ||
757 | enables composing support. This control is only | |
6a683493 HV |
758 | present if the ccs_cap_mode module option is set to the default value of |
759 | -1 and if the no_error_inj module option is set to 0 (the default). | |
760 | ||
cff4c8ac MCC |
761 | - Enable Capture Scaler: |
762 | ||
763 | enables support for a scaler (maximum 4 times upscaling | |
6a683493 HV |
764 | and downscaling). This control is only present if the ccs_cap_mode |
765 | module option is set to the default value of -1 and if the no_error_inj | |
766 | module option is set to 0 (the default). | |
767 | ||
cff4c8ac MCC |
768 | - Maximum EDID Blocks: |
769 | ||
770 | determines how many EDID blocks the driver supports. | |
6a683493 HV |
771 | Note that the vivid driver does not actually interpret new EDID |
772 | data, it just stores it. It allows for up to 256 EDID blocks | |
773 | which is the maximum supported by the standard. | |
774 | ||
cff4c8ac MCC |
775 | - Fill Percentage of Frame: |
776 | ||
777 | can be used to draw only the top X percent | |
6a683493 HV |
778 | of the image. Since each frame has to be drawn by the driver, this |
779 | demands a lot of the CPU. For large resolutions this becomes | |
780 | problematic. By drawing only part of the image this CPU load can | |
781 | be reduced. | |
782 | ||
783 | ||
cff4c8ac MCC |
784 | Output Feature Selection Controls |
785 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
6a683493 HV |
786 | |
787 | These controls are all specific to video output. | |
788 | ||
cff4c8ac MCC |
789 | - Enable Output Cropping: |
790 | ||
791 | enables crop support. This control is only present if | |
6a683493 HV |
792 | the ccs_out_mode module option is set to the default value of -1 and if |
793 | the no_error_inj module option is set to 0 (the default). | |
794 | ||
cff4c8ac MCC |
795 | - Enable Output Composing: |
796 | ||
797 | enables composing support. This control is only | |
6a683493 HV |
798 | present if the ccs_out_mode module option is set to the default value of |
799 | -1 and if the no_error_inj module option is set to 0 (the default). | |
800 | ||
cff4c8ac MCC |
801 | - Enable Output Scaler: |
802 | ||
803 | enables support for a scaler (maximum 4 times upscaling | |
6a683493 HV |
804 | and downscaling). This control is only present if the ccs_out_mode |
805 | module option is set to the default value of -1 and if the no_error_inj | |
806 | module option is set to 0 (the default). | |
807 | ||
808 | ||
cff4c8ac MCC |
809 | Error Injection Controls |
810 | ^^^^^^^^^^^^^^^^^^^^^^^^ | |
6a683493 HV |
811 | |
812 | The following two controls are only valid for video and vbi capture. | |
813 | ||
cff4c8ac MCC |
814 | - Standard Signal Mode: |
815 | ||
816 | selects the behavior of VIDIOC_QUERYSTD: what should it return? | |
6a683493 HV |
817 | |
818 | Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE | |
819 | to be sent since it emulates a changed input condition (e.g. a cable | |
820 | was plugged in or out). | |
821 | ||
cff4c8ac MCC |
822 | - Standard: |
823 | ||
824 | selects the standard that VIDIOC_QUERYSTD should return if the | |
6a683493 HV |
825 | previous control is set to "Selected Standard". |
826 | ||
827 | Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE | |
828 | to be sent since it emulates a changed input standard. | |
829 | ||
830 | ||
831 | The following two controls are only valid for video capture. | |
832 | ||
cff4c8ac | 833 | - DV Timings Signal Mode: |
a28ee884 | 834 | |
cff4c8ac | 835 | selects the behavior of VIDIOC_QUERY_DV_TIMINGS: what |
6a683493 HV |
836 | should it return? |
837 | ||
838 | Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE | |
839 | to be sent since it emulates a changed input condition (e.g. a cable | |
840 | was plugged in or out). | |
841 | ||
cff4c8ac MCC |
842 | - DV Timings: |
843 | ||
844 | selects the timings the VIDIOC_QUERY_DV_TIMINGS should return | |
6a683493 HV |
845 | if the previous control is set to "Selected DV Timings". |
846 | ||
847 | Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE | |
848 | to be sent since it emulates changed input timings. | |
849 | ||
850 | ||
851 | The following controls are only present if the no_error_inj module option | |
852 | is set to 0 (the default). These controls are valid for video and vbi | |
853 | capture and output streams and for the SDR capture device except for the | |
854 | Disconnect control which is valid for all devices. | |
855 | ||
cff4c8ac MCC |
856 | - Wrap Sequence Number: |
857 | ||
858 | test what happens when you wrap the sequence number in | |
6a683493 HV |
859 | struct v4l2_buffer around. |
860 | ||
cff4c8ac MCC |
861 | - Wrap Timestamp: |
862 | ||
863 | test what happens when you wrap the timestamp in struct | |
6a683493 HV |
864 | v4l2_buffer around. |
865 | ||
cff4c8ac MCC |
866 | - Percentage of Dropped Buffers: |
867 | ||
868 | sets the percentage of buffers that | |
6a683493 HV |
869 | are never returned by the driver (i.e., they are dropped). |
870 | ||
cff4c8ac MCC |
871 | - Disconnect: |
872 | ||
873 | emulates a USB disconnect. The device will act as if it has | |
6a683493 HV |
874 | been disconnected. Only after all open filehandles to the device |
875 | node have been closed will the device become 'connected' again. | |
876 | ||
cff4c8ac MCC |
877 | - Inject V4L2_BUF_FLAG_ERROR: |
878 | ||
879 | when pressed, the next frame returned by | |
6a683493 HV |
880 | the driver will have the error flag set (i.e. the frame is marked |
881 | corrupt). | |
882 | ||
cff4c8ac MCC |
883 | - Inject VIDIOC_REQBUFS Error: |
884 | ||
885 | when pressed, the next REQBUFS or CREATE_BUFS | |
6a683493 HV |
886 | ioctl call will fail with an error. To be precise: the videobuf2 |
887 | queue_setup() op will return -EINVAL. | |
888 | ||
cff4c8ac MCC |
889 | - Inject VIDIOC_QBUF Error: |
890 | ||
891 | when pressed, the next VIDIOC_QBUF or | |
6a683493 HV |
892 | VIDIOC_PREPARE_BUFFER ioctl call will fail with an error. To be |
893 | precise: the videobuf2 buf_prepare() op will return -EINVAL. | |
894 | ||
cff4c8ac MCC |
895 | - Inject VIDIOC_STREAMON Error: |
896 | ||
897 | when pressed, the next VIDIOC_STREAMON ioctl | |
6a683493 HV |
898 | call will fail with an error. To be precise: the videobuf2 |
899 | start_streaming() op will return -EINVAL. | |
900 | ||
cff4c8ac MCC |
901 | - Inject Fatal Streaming Error: |
902 | ||
903 | when pressed, the streaming core will be | |
6a683493 HV |
904 | marked as having suffered a fatal error, the only way to recover |
905 | from that is to stop streaming. To be precise: the videobuf2 | |
906 | vb2_queue_error() function is called. | |
907 | ||
908 | ||
cff4c8ac MCC |
909 | VBI Raw Capture Controls |
910 | ^^^^^^^^^^^^^^^^^^^^^^^^ | |
911 | ||
912 | - Interlaced VBI Format: | |
6a683493 | 913 | |
cff4c8ac | 914 | if set, then the raw VBI data will be interlaced instead |
6a683493 HV |
915 | of providing it grouped by field. |
916 | ||
917 | ||
cff4c8ac MCC |
918 | Digital Video Controls |
919 | ~~~~~~~~~~~~~~~~~~~~~~ | |
6a683493 | 920 | |
cff4c8ac MCC |
921 | - Rx RGB Quantization Range: |
922 | ||
923 | sets the RGB quantization detection of the HDMI | |
6a683493 HV |
924 | input. This combines with the Vivid 'Limited RGB Range (16-235)' |
925 | control and can be used to test what happens if a source provides | |
926 | you with the wrong quantization range information. This can be tested | |
927 | by selecting an HDMI input, setting this control to Full or Limited | |
928 | range and selecting the opposite in the 'Limited RGB Range (16-235)' | |
929 | control. The effect is easy to see if the 'Gray Ramp' test pattern | |
930 | is selected. | |
931 | ||
cff4c8ac MCC |
932 | - Tx RGB Quantization Range: |
933 | ||
934 | sets the RGB quantization detection of the HDMI | |
6a683493 HV |
935 | output. It is currently not used for anything in vivid, but most HDMI |
936 | transmitters would typically have this control. | |
937 | ||
cff4c8ac MCC |
938 | - Transmit Mode: |
939 | ||
940 | sets the transmit mode of the HDMI output to HDMI or DVI-D. This | |
6a683493 HV |
941 | affects the reported colorspace since DVI_D outputs will always use |
942 | sRGB. | |
943 | ||
4196ad7c JK |
944 | - Display Present: |
945 | ||
946 | sets the presence of a "display" on the HDMI output. This affects | |
947 | the tx_edid_present, tx_hotplug and tx_rxsense controls. | |
948 | ||
6a683493 | 949 | |
cff4c8ac MCC |
950 | FM Radio Receiver Controls |
951 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
952 | ||
953 | - RDS Reception: | |
954 | ||
955 | set if the RDS receiver should be enabled. | |
956 | ||
957 | - RDS Program Type: | |
958 | ||
959 | ||
960 | - RDS PS Name: | |
961 | ||
6a683493 | 962 | |
cff4c8ac | 963 | - RDS Radio Text: |
6a683493 | 964 | |
cff4c8ac MCC |
965 | |
966 | - RDS Traffic Announcement: | |
967 | ||
968 | ||
969 | - RDS Traffic Program: | |
970 | ||
971 | ||
972 | - RDS Music: | |
973 | ||
974 | these are all read-only controls. If RDS Rx I/O Mode is set to | |
6a683493 | 975 | "Block I/O", then they are inactive as well. If RDS Rx I/O Mode is set |
cff4c8ac MCC |
976 | to "Controls", then these controls report the received RDS data. |
977 | ||
978 | .. note:: | |
979 | The vivid implementation of this is pretty basic: they are only | |
6a683493 HV |
980 | updated when you set a new frequency or when you get the tuner status |
981 | (VIDIOC_G_TUNER). | |
982 | ||
cff4c8ac MCC |
983 | - Radio HW Seek Mode: |
984 | ||
985 | can be one of "Bounded", "Wrap Around" or "Both". This | |
6a683493 HV |
986 | determines if VIDIOC_S_HW_FREQ_SEEK will be bounded by the frequency |
987 | range or wrap-around or if it is selectable by the user. | |
988 | ||
cff4c8ac MCC |
989 | - Radio Programmable HW Seek: |
990 | ||
991 | if set, then the user can provide the lower and | |
6a683493 HV |
992 | upper bound of the HW Seek. Otherwise the frequency range boundaries |
993 | will be used. | |
994 | ||
cff4c8ac MCC |
995 | - Generate RBDS Instead of RDS: |
996 | ||
997 | if set, then generate RBDS (the US variant of | |
6a683493 HV |
998 | RDS) data instead of RDS (European-style RDS). This affects only the |
999 | PICODE and PTY codes. | |
1000 | ||
cff4c8ac MCC |
1001 | - RDS Rx I/O Mode: |
1002 | ||
1003 | this can be "Block I/O" where the RDS blocks have to be read() | |
6a683493 HV |
1004 | by the application, or "Controls" where the RDS data is provided by |
1005 | the RDS controls mentioned above. | |
1006 | ||
1007 | ||
cff4c8ac MCC |
1008 | FM Radio Modulator Controls |
1009 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1010 | ||
1011 | - RDS Program ID: | |
1012 | ||
1013 | ||
1014 | - RDS Program Type: | |
1015 | ||
1016 | ||
1017 | - RDS PS Name: | |
1018 | ||
1019 | ||
1020 | - RDS Radio Text: | |
1021 | ||
1022 | ||
1023 | - RDS Stereo: | |
1024 | ||
1025 | ||
1026 | - RDS Artificial Head: | |
1027 | ||
1028 | ||
1029 | - RDS Compressed: | |
1030 | ||
1031 | ||
1032 | - RDS Dynamic PTY: | |
1033 | ||
1034 | ||
1035 | - RDS Traffic Announcement: | |
1036 | ||
1037 | ||
1038 | - RDS Traffic Program: | |
1039 | ||
1040 | ||
1041 | - RDS Music: | |
1042 | ||
1043 | these are all controls that set the RDS data that is transmitted by | |
6a683493 HV |
1044 | the FM modulator. |
1045 | ||
cff4c8ac | 1046 | - RDS Tx I/O Mode: |
6a683493 | 1047 | |
cff4c8ac MCC |
1048 | this can be "Block I/O" where the application has to use write() |
1049 | to pass the RDS blocks to the driver, or "Controls" where the RDS data | |
1050 | is Provided by the RDS controls mentioned above. | |
6a683493 | 1051 | |
cff4c8ac MCC |
1052 | |
1053 | Video, VBI and RDS Looping | |
1054 | -------------------------- | |
6a683493 HV |
1055 | |
1056 | The vivid driver supports looping of video output to video input, VBI output | |
1057 | to VBI input and RDS output to RDS input. For video/VBI looping this emulates | |
1058 | as if a cable was hooked up between the output and input connector. So video | |
1059 | and VBI looping is only supported between S-Video and HDMI inputs and outputs. | |
1060 | VBI is only valid for S-Video as it makes no sense for HDMI. | |
1061 | ||
1062 | Since radio is wireless this looping always happens if the radio receiver | |
1063 | frequency is close to the radio transmitter frequency. In that case the radio | |
1064 | transmitter will 'override' the emulated radio stations. | |
1065 | ||
1066 | Looping is currently supported only between devices created by the same | |
1067 | vivid driver instance. | |
1068 | ||
1069 | ||
cff4c8ac MCC |
1070 | Video and Sliced VBI looping |
1071 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
6a683493 HV |
1072 | |
1073 | The way to enable video/VBI looping is currently fairly crude. A 'Loop Video' | |
1074 | control is available in the "Vivid" control class of the video | |
63344b65 | 1075 | capture and VBI capture devices. When checked the video looping will be enabled. |
6a683493 HV |
1076 | Once enabled any video S-Video or HDMI input will show a static test pattern |
1077 | until the video output has started. At that time the video output will be | |
1078 | looped to the video input provided that: | |
1079 | ||
1080 | - the input type matches the output type. So the HDMI input cannot receive | |
1081 | video from the S-Video output. | |
1082 | ||
1083 | - the video resolution of the video input must match that of the video output. | |
1084 | So it is not possible to loop a 50 Hz (720x576) S-Video output to a 60 Hz | |
1085 | (720x480) S-Video input, or a 720p60 HDMI output to a 1080p30 input. | |
1086 | ||
1087 | - the pixel formats must be identical on both sides. Otherwise the driver would | |
1088 | have to do pixel format conversion as well, and that's taking things too far. | |
1089 | ||
1090 | - the field settings must be identical on both sides. Same reason as above: | |
1091 | requiring the driver to convert from one field format to another complicated | |
1092 | matters too much. This also prohibits capturing with 'Field Top' or 'Field | |
1093 | Bottom' when the output video is set to 'Field Alternate'. This combination, | |
1094 | while legal, became too complicated to support. Both sides have to be 'Field | |
1095 | Alternate' for this to work. Also note that for this specific case the | |
1096 | sequence and field counting in struct v4l2_buffer on the capture side may not | |
1097 | be 100% accurate. | |
1098 | ||
ba24b442 HV |
1099 | - field settings V4L2_FIELD_SEQ_TB/BT are not supported. While it is possible to |
1100 | implement this, it would mean a lot of work to get this right. Since these | |
1101 | field values are rarely used the decision was made not to implement this for | |
1102 | now. | |
1103 | ||
6a683493 HV |
1104 | - on the input side the "Standard Signal Mode" for the S-Video input or the |
1105 | "DV Timings Signal Mode" for the HDMI input should be configured so that a | |
1106 | valid signal is passed to the video input. | |
1107 | ||
1108 | The framerates do not have to match, although this might change in the future. | |
1109 | ||
1110 | By default you will see the OSD text superimposed on top of the looped video. | |
1111 | This can be turned off by changing the "OSD Text Mode" control of the video | |
1112 | capture device. | |
1113 | ||
1114 | For VBI looping to work all of the above must be valid and in addition the vbi | |
1115 | output must be configured for sliced VBI. The VBI capture side can be configured | |
62f28725 HV |
1116 | for either raw or sliced VBI. Note that at the moment only CC/XDS (60 Hz formats) |
1117 | and WSS (50 Hz formats) VBI data is looped. Teletext VBI data is not looped. | |
6a683493 HV |
1118 | |
1119 | ||
cff4c8ac MCC |
1120 | Radio & RDS Looping |
1121 | ~~~~~~~~~~~~~~~~~~~ | |
6a683493 HV |
1122 | |
1123 | As mentioned in section 6 the radio receiver emulates stations are regular | |
1124 | frequency intervals. Depending on the frequency of the radio receiver a | |
1125 | signal strength value is calculated (this is returned by VIDIOC_G_TUNER). | |
1126 | However, it will also look at the frequency set by the radio transmitter and | |
1127 | if that results in a higher signal strength than the settings of the radio | |
1128 | transmitter will be used as if it was a valid station. This also includes | |
1129 | the RDS data (if any) that the transmitter 'transmits'. This is received | |
1130 | faithfully on the receiver side. Note that when the driver is loaded the | |
1131 | frequencies of the radio receiver and transmitter are not identical, so | |
1132 | initially no looping takes place. | |
1133 | ||
1134 | ||
cff4c8ac MCC |
1135 | Cropping, Composing, Scaling |
1136 | ---------------------------- | |
6a683493 HV |
1137 | |
1138 | This driver supports cropping, composing and scaling in any combination. Normally | |
1139 | which features are supported can be selected through the Vivid controls, | |
1140 | but it is also possible to hardcode it when the module is loaded through the | |
1141 | ccs_cap_mode and ccs_out_mode module options. See section 1 on the details of | |
1142 | these module options. | |
1143 | ||
1144 | This allows you to test your application for all these variations. | |
1145 | ||
1146 | Note that the webcam input never supports cropping, composing or scaling. That | |
1147 | only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that | |
1148 | webcams, including this virtual implementation, normally use | |
1149 | VIDIOC_ENUM_FRAMESIZES to list a set of discrete framesizes that it supports. | |
1150 | And that does not combine with cropping, composing or scaling. This is | |
1151 | primarily a limitation of the V4L2 API which is carefully reproduced here. | |
1152 | ||
1153 | The minimum and maximum resolutions that the scaler can achieve are 16x16 and | |
1154 | (4096 * 4) x (2160 x 4), but it can only scale up or down by a factor of 4 or | |
1155 | less. So for a source resolution of 1280x720 the minimum the scaler can do is | |
1156 | 320x180 and the maximum is 5120x2880. You can play around with this using the | |
1157 | qv4l2 test tool and you will see these dependencies. | |
1158 | ||
1159 | This driver also supports larger 'bytesperline' settings, something that | |
1160 | VIDIOC_S_FMT allows but that few drivers implement. | |
1161 | ||
1162 | The scaler is a simple scaler that uses the Coarse Bresenham algorithm. It's | |
1163 | designed for speed and simplicity, not quality. | |
1164 | ||
1165 | If the combination of crop, compose and scaling allows it, then it is possible | |
1166 | to change crop and compose rectangles on the fly. | |
1167 | ||
1168 | ||
cff4c8ac MCC |
1169 | Formats |
1170 | ------- | |
6a683493 | 1171 | |
64d57022 HV |
1172 | The driver supports all the regular packed and planar 4:4:4, 4:2:2 and 4:2:0 |
1173 | YUYV formats, 8, 16, 24 and 32 RGB packed formats and various multiplanar | |
1174 | formats. | |
6a683493 HV |
1175 | |
1176 | The alpha component can be set through the 'Alpha Component' User control | |
1177 | for those formats that support it. If the 'Apply Alpha To Red Only' control | |
1178 | is set, then the alpha component is only used for the color red and set to | |
1179 | 0 otherwise. | |
1180 | ||
1181 | The driver has to be configured to support the multiplanar formats. By default | |
cba63cf8 HV |
1182 | the driver instances are single-planar. This can be changed by setting the |
1183 | multiplanar module option, see section 1 for more details on that option. | |
6a683493 HV |
1184 | |
1185 | If the driver instance is using the multiplanar formats/API, then the first | |
1186 | single planar format (YUYV) and the multiplanar NV16M and NV61M formats the | |
1187 | will have a plane that has a non-zero data_offset of 128 bytes. It is rare for | |
1188 | data_offset to be non-zero, so this is a useful feature for testing applications. | |
1189 | ||
1190 | Video output will also honor any data_offset that the application set. | |
1191 | ||
1192 | ||
cff4c8ac MCC |
1193 | Capture Overlay |
1194 | --------------- | |
6a683493 HV |
1195 | |
1196 | Note: capture overlay support is implemented primarily to test the existing | |
1197 | V4L2 capture overlay API. In practice few if any GPUs support such overlays | |
1198 | anymore, and neither are they generally needed anymore since modern hardware | |
1199 | is so much more capable. By setting flag 0x10000 in the node_types module | |
1200 | option the vivid driver will create a simple framebuffer device that can be | |
1201 | used for testing this API. Whether this API should be used for new drivers is | |
1202 | questionable. | |
1203 | ||
1204 | This driver has support for a destructive capture overlay with bitmap clipping | |
1205 | and list clipping (up to 16 rectangles) capabilities. Overlays are not | |
1206 | supported for multiplanar formats. It also honors the struct v4l2_window field | |
1207 | setting: if it is set to FIELD_TOP or FIELD_BOTTOM and the capture setting is | |
1208 | FIELD_ALTERNATE, then only the top or bottom fields will be copied to the overlay. | |
1209 | ||
1210 | The overlay only works if you are also capturing at that same time. This is a | |
1211 | vivid limitation since it copies from a buffer to the overlay instead of | |
1212 | filling the overlay directly. And if you are not capturing, then no buffers | |
1213 | are available to fill. | |
1214 | ||
1215 | In addition, the pixelformat of the capture format and that of the framebuffer | |
1216 | must be the same for the overlay to work. Otherwise VIDIOC_OVERLAY will return | |
1217 | an error. | |
1218 | ||
1219 | In order to really see what it going on you will need to create two vivid | |
1220 | instances: the first with a framebuffer enabled. You configure the capture | |
1221 | overlay of the second instance to use the framebuffer of the first, then | |
1222 | you start capturing in the second instance. For the first instance you setup | |
1223 | the output overlay for the video output, turn on video looping and capture | |
1224 | to see the blended framebuffer overlay that's being written to by the second | |
1225 | instance. This setup would require the following commands: | |
1226 | ||
cff4c8ac MCC |
1227 | .. code-block:: none |
1228 | ||
cba63cf8 | 1229 | $ sudo modprobe vivid n_devs=2 node_types=0x10101,0x1 |
6a683493 HV |
1230 | $ v4l2-ctl -d1 --find-fb |
1231 | /dev/fb1 is the framebuffer associated with base address 0x12800000 | |
1232 | $ sudo v4l2-ctl -d2 --set-fbuf fb=1 | |
1233 | $ v4l2-ctl -d1 --set-fbuf fb=1 | |
1234 | $ v4l2-ctl -d0 --set-fmt-video=pixelformat='AR15' | |
1235 | $ v4l2-ctl -d1 --set-fmt-video-out=pixelformat='AR15' | |
1236 | $ v4l2-ctl -d2 --set-fmt-video=pixelformat='AR15' | |
1237 | $ v4l2-ctl -d0 -i2 | |
1238 | $ v4l2-ctl -d2 -i2 | |
1239 | $ v4l2-ctl -d2 -c horizontal_movement=4 | |
1240 | $ v4l2-ctl -d1 --overlay=1 | |
1241 | $ v4l2-ctl -d1 -c loop_video=1 | |
1242 | $ v4l2-ctl -d2 --stream-mmap --overlay=1 | |
1243 | ||
1244 | And from another console: | |
1245 | ||
cff4c8ac MCC |
1246 | .. code-block:: none |
1247 | ||
6a683493 HV |
1248 | $ v4l2-ctl -d1 --stream-out-mmap |
1249 | ||
1250 | And yet another console: | |
1251 | ||
cff4c8ac MCC |
1252 | .. code-block:: none |
1253 | ||
6a683493 HV |
1254 | $ qv4l2 |
1255 | ||
1256 | and start streaming. | |
1257 | ||
1258 | As you can see, this is not for the faint of heart... | |
1259 | ||
1260 | ||
cff4c8ac MCC |
1261 | Output Overlay |
1262 | -------------- | |
6a683493 HV |
1263 | |
1264 | Note: output overlays are primarily implemented in order to test the existing | |
1265 | V4L2 output overlay API. Whether this API should be used for new drivers is | |
1266 | questionable. | |
1267 | ||
1268 | This driver has support for an output overlay and is capable of: | |
1269 | ||
1270 | - bitmap clipping, | |
1271 | - list clipping (up to 16 rectangles) | |
1272 | - chromakey | |
1273 | - source chromakey | |
1274 | - global alpha | |
1275 | - local alpha | |
1276 | - local inverse alpha | |
1277 | ||
1278 | Output overlays are not supported for multiplanar formats. In addition, the | |
1279 | pixelformat of the capture format and that of the framebuffer must be the | |
1280 | same for the overlay to work. Otherwise VIDIOC_OVERLAY will return an error. | |
1281 | ||
1282 | Output overlays only work if the driver has been configured to create a | |
1283 | framebuffer by setting flag 0x10000 in the node_types module option. The | |
1284 | created framebuffer has a size of 720x576 and supports ARGB 1:5:5:5 and | |
1285 | RGB 5:6:5. | |
1286 | ||
1287 | In order to see the effects of the various clipping, chromakeying or alpha | |
1288 | processing capabilities you need to turn on video looping and see the results | |
1289 | on the capture side. The use of the clipping, chromakeying or alpha processing | |
1290 | capabilities will slow down the video loop considerably as a lot of checks have | |
1291 | to be done per pixel. | |
1292 | ||
1293 | ||
cff4c8ac MCC |
1294 | CEC (Consumer Electronics Control) |
1295 | ---------------------------------- | |
6f8adea2 HV |
1296 | |
1297 | If there are HDMI inputs then a CEC adapter will be created that has | |
1298 | the same number of input ports. This is the equivalent of e.g. a TV that | |
1299 | has that number of inputs. Each HDMI output will also create a | |
1300 | CEC adapter that is hooked up to the corresponding input port, or (if there | |
1301 | are more outputs than inputs) is not hooked up at all. In other words, | |
1302 | this is the equivalent of hooking up each output device to an input port of | |
1303 | the TV. Any remaining output devices remain unconnected. | |
1304 | ||
1305 | The EDID that each output reads reports a unique CEC physical address that is | |
1306 | based on the physical address of the EDID of the input. So if the EDID of the | |
1307 | receiver has physical address A.B.0.0, then each output will see an EDID | |
1308 | containing physical address A.B.C.0 where C is 1 to the number of inputs. If | |
1309 | there are more outputs than inputs then the remaining outputs have a CEC adapter | |
1310 | that is disabled and reports an invalid physical address. | |
1311 | ||
1312 | ||
cff4c8ac MCC |
1313 | Some Future Improvements |
1314 | ------------------------ | |
6a683493 HV |
1315 | |
1316 | Just as a reminder and in no particular order: | |
1317 | ||
1318 | - Add a virtual alsa driver to test audio | |
1319 | - Add virtual sub-devices and media controller support | |
1320 | - Some support for testing compressed video | |
1321 | - Add support to loop raw VBI output to raw VBI input | |
62f28725 | 1322 | - Add support to loop teletext sliced VBI output to VBI input |
6a683493 HV |
1323 | - Fix sequence/field numbering when looping of video with alternate fields |
1324 | - Add support for V4L2_CID_BG_COLOR for video outputs | |
1325 | - Add ARGB888 overlay support: better testing of the alpha channel | |
6a683493 HV |
1326 | - Improve pixel aspect support in the tpg code by passing a real v4l2_fract |
1327 | - Use per-queue locks and/or per-device locks to improve throughput | |
1328 | - Add support to loop from a specific output to a specific input across | |
1329 | vivid instances | |
6a683493 HV |
1330 | - The SDR radio should use the same 'frequencies' for stations as the normal |
1331 | radio receiver, and give back noise if the frequency doesn't match up with | |
1332 | a station frequency | |
6a683493 HV |
1333 | - Make a thread for the RDS generation, that would help in particular for the |
1334 | "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated | |
1335 | in real-time. | |
6f8adea2 | 1336 | - Changing the EDID should cause hotplug detect emulation to happen. |