1 .. SPDX-License-Identifier: GPL-2.0
2
3 The Virtual Video Test Driver (vivid)
4 =====================================
5
6 This driver emulates video4linux hardware of v
7 output, vbi capture and output, metadata captu
8 transmitters, touch capture and a software def
9 simple framebuffer device is available for tes
10
11 Up to 64 vivid instances can be created, each
12
13 Each input can be a webcam, TV capture device,
14 capture device. Each output can be an S-Video
15 device.
16
17 These inputs and outputs act exactly as a real
18 allows you to use this driver as a test input
19 you can test the various features without requ
20
21 This document describes the features implement
22
23 - Support for read()/write(), MMAP, USERPTR an
24 - A large list of test patterns and variations
25 - Working brightness, contrast, saturation and
26 - Support for the alpha color component
27 - Full colorspace support, including limited/f
28 - All possible control types are present
29 - Support for various pixel aspect ratios and
30 - Error injection to test what happens if erro
31 - Supports crop/compose/scale in any combinati
32 - Can emulate up to 4K resolutions
33 - All Field settings are supported for testing
34 - Supports all standard YUV and RGB formats, i
35 - Raw and Sliced VBI capture and output suppor
36 - Radio receiver and transmitter support, incl
37 - Software defined radio (SDR) support
38 - Capture and output overlay support
39 - Metadata capture and output support
40 - Touch capture support
41
42 These features will be described in more detai
43
44 Configuring the driver
45 ----------------------
46
47 By default the driver will create a single ins
48 device with webcam, TV, S-Video and HDMI input
49 S-Video and HDMI outputs, one vbi capture devi
50 radio receiver device, one radio transmitter d
51
52 The number of instances, devices, video inputs
53 all configurable using the following module op
54
55 - n_devs:
56
57 number of driver instances to create.
58 instances can be created.
59
60 - node_types:
61
62 which devices should each driver insta
63 hexadecimal values, one for each insta
64 Each value is a bitmask with the follo
65
66 - bit 0: Video Capture node
67 - bit 2-3: VBI Capture node: 0
68 - bit 4: Radio Receiver node
69 - bit 5: Software Defined Radi
70 - bit 8: Video Output node
71 - bit 10-11: VBI Output node:
72 - bit 12: Radio Transmitter no
73 - bit 16: Framebuffer for test
74 - bit 17: Metadata Capture nod
75 - bit 18: Metadata Output node
76 - bit 19: Touch Capture node
77
78 So to create four instances, the first
79 device, the second two with just one v
80 these module options to vivid:
81
82 .. code-block:: none
83
84 n_devs=4 node_types=0x1,0x1,0x
85
86 - num_inputs:
87
88 the number of inputs, one for each ins
89 are created for each video capture dev
90 and there must be at least one.
91
92 - input_types:
93
94 the input types for each instance, the
95 what the type of each input is when th
96 instance. This is a hexadecimal value
97 pair gives the type and bits 0-1 map t
98 30-31 map to input 15. Each pair of bi
99
100 - 00: this is a webcam input
101 - 01: this is a TV tuner input
102 - 10: this is an S-Video input
103 - 11: this is an HDMI input
104
105 So to create a video capture device wi
106 tuner, inputs 1-3 are S-Video inputs a
107 would use the following module options
108
109 .. code-block:: none
110
111 num_inputs=8 input_types=0xffa
112
113 - num_outputs:
114
115 the number of outputs, one for each in
116 are created for each video output devi
117 created, and there must be at least on
118
119 - output_types:
120
121 the output types for each instance, th
122 what the type of each output is when t
123 driver instance. This is a hexadecimal
124 gives the type and bit 0 maps to outpu
125 15 maps to output 15. The meaning of e
126
127 - 0: this is an S-Video output
128 - 1: this is an HDMI output
129
130 So to create a video output device wit
131 S-Video outputs and outputs 4-7 are HD
132 following module options:
133
134 .. code-block:: none
135
136 num_outputs=8 output_types=0xf
137
138 - vid_cap_nr:
139
140 give the desired videoX start number f
141 The default is -1 which will just take
142 you to map capture video nodes to spec
143
144 .. code-block:: none
145
146 n_devs=4 vid_cap_nr=2,4,6,8
147
148 This will attempt to assign /dev/video
149 the first vivid instance, video4 for t
150 instance. If it can't succeed, then it
151 number.
152
153 - vid_out_nr:
154
155 give the desired videoX start number f
156 The default is -1 which will just take
157
158 - vbi_cap_nr:
159
160 give the desired vbiX start number for
161 The default is -1 which will just take
162
163 - vbi_out_nr:
164
165 give the desired vbiX start number for
166 The default is -1 which will just take
167
168 - radio_rx_nr:
169
170 give the desired radioX start number f
171 The default is -1 which will just take
172
173 - radio_tx_nr:
174
175 give the desired radioX start number f
176 device. The default is -1 which will j
177
178 - sdr_cap_nr:
179
180 give the desired swradioX start number
181 The default is -1 which will just take
182
183 - meta_cap_nr:
184
185 give the desired videoX start number f
186 The default is -1 which will just take
187
188 - meta_out_nr:
189
190 give the desired videoX start number f
191 The default is -1 which will just take
192
193 - touch_cap_nr:
194
195 give the desired v4l-touchX start numb
196 The default is -1 which will just take
197
198 - ccs_cap_mode:
199
200 specify the allowed video capture crop
201 for each driver instance. Video captur
202 of cropping, composing and scaling cap
203 vivid driver which of those is should
204 select this through controls.
205
206 The value is either -1 (controlled by
207 each enabling (1) or disabling (0) one
208
209 - bit 0:
210
211 Enable crop support. Cropping
212 incoming picture.
213 - bit 1:
214
215 Enable compose support. Compos
216 picture into a larger buffer.
217
218 - bit 2:
219
220 Enable scaling support. Scalin
221 picture. The scaler of the viv
222 or down to four times the orig
223 very simple and low-quality. S
224 key, not quality.
225
226 Note that this value is ignored by web
227 discrete framesizes and that is incomp
228 or scaling.
229
230 - ccs_out_mode:
231
232 specify the allowed video output crop/
233 for each driver instance. Video output
234 of cropping, composing and scaling cap
235 vivid driver which of those is should
236 select this through controls.
237
238 The value is either -1 (controlled by
239 each enabling (1) or disabling (0) one
240
241 - bit 0:
242
243 Enable crop support. Cropping
244 outgoing buffer.
245
246 - bit 1:
247
248 Enable compose support. Compos
249 buffer into a larger picture f
250
251 - bit 2:
252
253 Enable scaling support. Scalin
254 buffer. The scaler of the vivi
255 or down to four times the orig
256 very simple and low-quality. S
257 key, not quality.
258
259 - multiplanar:
260
261 select whether each device instance su
262 and thus the V4L2 multi-planar API. By
263 single-planar.
264
265 This module option can override that f
266
267 - 1: this is a single-planar i
268 - 2: this is a multi-planar in
269
270 - vivid_debug:
271
272 enable driver debugging info
273
274 - no_error_inj:
275
276 if set disable the error injecting con
277 needed in order to run a tool like v4l
278 exercise all controls including a cont
279 emulates a USB disconnect, making the
280 all tests that v4l2-compliance is doin
281
282 There may be other situations as well
283 error injection support of vivid. When
284 controls that select crop, compose and
285 removed. Unless overridden by ccs_cap_
286 will default to enabling crop, compose
287
288 - allocators:
289
290 memory allocator selection, default is
291 will be allocated.
292
293 - 0: vmalloc
294 - 1: dma-contig
295
296 - cache_hints:
297
298 specifies if the device should set que
299 consistency hint capability (V4L2_BUF_
300 The hints are valid only when using MM
301
302 - 0: forbid hints
303 - 1: allow hints
304
305 - supports_requests:
306
307 specifies if the device should support
308 three possible values, default is 1:
309
310 - 0: no request
311 - 1: supports requests
312 - 2: requires requests
313
314 Taken together, all these module options allow
315 the driver behavior and test your application
316 It is also very suitable to emulate hardware t
317 when developing software for a new upcoming de
318
319
320 Video Capture
321 -------------
322
323 This is probably the most frequently used feat
324 can be configured by using the module options
325 ccs_cap_mode (see "Configuring the driver" for
326 but by default four inputs are configured: a w
327 and an HDMI input, one input for each input ty
328 detail below.
329
330 Special attention has been given to the rate a
331 available. The jitter will be around 1 jiffy (
332 configuration of your kernel, so usually 1/100
333 but the long-term behavior is exactly followin
334 framerate of 59.94 Hz is really different from
335 exceeds your kernel's HZ value, then you will
336 frame/field sequence counting will keep track
337 count will skip whenever frames are dropped.
338
339
340 Webcam Input
341 ~~~~~~~~~~~~
342
343 The webcam input supports three framesizes: 32
344 supports frames per second settings of 10, 15,
345 are available depends on the chosen framesize:
346 lower the maximum frames per second.
347
348 The initially selected colorspace when you swi
349 sRGB.
350
351
352 TV and S-Video Inputs
353 ~~~~~~~~~~~~~~~~~~~~~
354
355 The only difference between the TV and S-Video
356 tuner. Otherwise they behave identically.
357
358 These inputs support audio inputs as well: one
359 both support all TV standards. If the standard
360 controls 'Standard Signal Mode' and 'Standard'
361 the result will be.
362
363 These inputs support all combinations of the f
364 been taken to faithfully reproduce how fields
365 TV standards. This is particularly noticeable
366 moving image so the temporal effect of using i
367 visible. For 50 Hz standards the top field is
368 is the newest in time. For 60 Hz standards tha
369 is the oldest and the top field is the newest
370
371 When you start capturing in V4L2_FIELD_ALTERNA
372 contain the top field for 50 Hz standards and
373 standards. This is what capture hardware does
374
375 Finally, for PAL/SECAM standards the first hal
376 This simulates the Wide Screen Signal that is
377
378 The initially selected colorspace when you swi
379 will be SMPTE-170M.
380
381 The pixel aspect ratio will depend on the TV s
382 can be selected through the 'Standard Aspect R
383 Choices are '4x3', '16x9' which will give lett
384 '16x9 Anamorphic' which will give full screen
385 video that will need to be scaled accordingly.
386
387 The TV 'tuner' supports a frequency range of 4
388 every 6 MHz, starting from 49.25 MHz. For each
389 will be in color for the +/- 0.25 MHz around i
390 +/- 1 MHz around the channel. Beyond that it i
391 ioctl will return 100% signal strength for +/-
392 It will also return correct afc values to show
393 low or too high.
394
395 The audio subchannels that are returned are MO
396 a valid channel frequency. When the frequency
397 channel it will return either MONO, STEREO, ei
398 LANG1 | LANG2 (for others), or STEREO | SAP.
399
400 Which one is returned depends on the chosen ch
401 will cycle through the possible audio subchann
402 you to test the various combinations by just s
403
404 Finally, for these inputs the v4l2_timecode st
405 dequeued v4l2_buffer struct.
406
407
408 HDMI Input
409 ~~~~~~~~~~
410
411 The HDMI inputs supports all CEA-861 and DMT t
412 interlaced, for pixelclock frequencies between
413 mode for interlaced formats is always V4L2_FIE
414 field order is always top field first, and whe
415 interlaced format you will receive the top fie
416
417 The initially selected colorspace when you swi
418 select an HDMI timing is based on the format r
419 less than or equal to 720x576 the colorspace i
420 others it is set to REC-709 (CEA-861 timings)
421
422 The pixel aspect ratio will depend on the HDMI
423 set as for the NTSC TV standard, for 720x576 i
424 standard, and for all others a 1:1 pixel aspec
425
426 The video aspect ratio can be selected through
427 Vivid control. Choices are 'Source Width x Hei
428 same ratio as the chosen format), '4x3' or '16
429 result in pillarboxed or letterboxed video.
430
431 For HDMI inputs it is possible to set the EDID
432 is provided. You can only set the EDID for HDM
433 the EDID is shared between all HDMI inputs.
434
435 No interpretation is done of the EDID data wit
436 physical address. See the CEC section for more
437
438 There is a maximum of 15 HDMI inputs (if there
439 reduced to 15) since that's the limitation of
440
441
442 Video Output
443 ------------
444
445 The video output device can be configured by u
446 num_outputs, output_types and ccs_out_mode (se
447 for more detailed information), but by default
448 an S-Video and an HDMI input, one output for e
449 described in more detail below.
450
451 Like with video capture the framerate is also
452
453
454 S-Video Output
455 ~~~~~~~~~~~~~~
456
457 This output supports audio outputs as well: "L
458 The S-Video output supports all TV standards.
459
460 This output supports all combinations of the f
461
462 The initially selected colorspace when you swi
463 will be SMPTE-170M.
464
465
466 HDMI Output
467 ~~~~~~~~~~~
468
469 The HDMI output supports all CEA-861 and DMT t
470 interlaced, for pixelclock frequencies between
471 mode for interlaced formats is always V4L2_FIE
472
473 The initially selected colorspace when you swi
474 select an HDMI timing is based on the format r
475 less than or equal to 720x576 the colorspace i
476 others it is set to REC-709 (CEA-861 timings)
477
478 The pixel aspect ratio will depend on the HDMI
479 set as for the NTSC TV standard, for 720x576 i
480 standard, and for all others a 1:1 pixel aspec
481
482 An HDMI output has a valid EDID which can be o
483
484 There is a maximum of 15 HDMI outputs (if ther
485 reduced to 15) since that's the limitation of
486 also the CEC section for more details.
487
488 VBI Capture
489 -----------
490
491 There are three types of VBI capture devices:
492 (undecoded) VBI, those that only support slice
493 support both. This is determined by the node_t
494 cases the driver will generate valid VBI data:
495 generate Closed Caption and XDS data. The clos
496 alternate between "Hello world!" and "Closed c
497 The XDS stream will give the current time once
498 it will generate the Wide Screen Signal which
499 Aspect Ratio control setting and teletext page
500
501 The VBI device will only work for the S-Video
502 back an error if the current input is a webcam
503
504
505 VBI Output
506 ----------
507
508 There are three types of VBI output devices: t
509 (undecoded) VBI, those that only support slice
510 support both. This is determined by the node_t
511
512 The sliced VBI output supports the Wide Screen
513 for 50 Hz standards and Closed Captioning + XD
514
515 The VBI device will only work for the S-Video
516 back an error if the current output is HDMI.
517
518
519 Radio Receiver
520 --------------
521
522 The radio receiver emulates an FM/AM/SW receiv
523 The frequency ranges are:
524
525 - FM: 64 MHz - 108 MHz
526 - AM: 520 kHz - 1710 kHz
527 - SW: 2300 kHz - 26.1 MHz
528
529 Valid channels are emulated every 1 MHz for FM
530 The signal strength decreases the further the
531 frequency until it becomes 0% at +/- 50 kHz (F
532 ideal frequency. The initial frequency when th
533 95 MHz.
534
535 The FM receiver supports RDS as well, both usi
536 modes. In the 'Controls' mode the RDS informat
537 controls. These controls are updated every tim
538 or when the tuner status is requested. The Blo
539 interface to pass the RDS blocks on to the app
540
541 The RDS signal is 'detected' for +/- 12.5 kHz
542 and the further the frequency is away from the
543 errors are randomly introduced into the block
544 blocks if you are +/- 12.5 kHz from the channe
545 can occur in equal proportions: blocks marked
546 'ERROR', blocks marked 'INVALID' and dropped b
547
548 The generated RDS stream contains all the stan
549 0B group, and also radio text and the current
550
551 The receiver supports HW frequency seek, eithe
552 mode or both, which is configurable with the "
553
554
555 Radio Transmitter
556 -----------------
557
558 The radio transmitter emulates an FM/AM/SW tra
559 The frequency ranges are:
560
561 - FM: 64 MHz - 108 MHz
562 - AM: 520 kHz - 1710 kHz
563 - SW: 2300 kHz - 26.1 MHz
564
565 The initial frequency when the driver is loade
566
567 The FM transmitter supports RDS as well, both
568 modes. In the 'Controls' mode the transmitted
569 using controls, and in 'Block I/O' mode the bl
570 using write().
571
572
573 Software Defined Radio Receiver
574 -------------------------------
575
576 The SDR receiver has three frequency bands for
577
578 - 300 kHz
579 - 900 kHz - 2800 kHz
580 - 3200 kHz
581
582 The RF tuner supports 50 MHz - 2000 MHz.
583
584 The generated data contains the In-phase and Q
585 1 kHz tone that has an amplitude of sqrt(2).
586
587
588 Metadata Capture
589 ----------------
590
591 The Metadata capture generates UVC format meta
592 transmitted based on the values set in vivid c
593
594 The Metadata device will only work for the Web
595 back an error for all other inputs.
596
597
598 Metadata Output
599 ---------------
600
601 The Metadata output can be used to set brightn
602
603 The Metadata device will only work for the Web
604 back an error for all other outputs.
605
606
607 Touch Capture
608 -------------
609
610 The Touch capture generates touch patterns sim
611 triple tap, move from left to right, zoom in,
612 a large area being pressed on a touchpad), and
613 touch points.
614
615 Controls
616 --------
617
618 Different devices support different controls.
619 each control and which devices support them.
620
621
622 User Controls - Test Controls
623 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
624
625 The Button, Boolean, Integer 32 Bits, Integer
626 Integer Menu are controls that represent all p
627 control and the Integer Menu control both have
628 meaning that one or more menu items return EIN
629 Both menu controls also have a non-zero minimu
630 allow you to check if your application can han
631 These controls are supported for every device
632
633
634 User Controls - Video Capture
635 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
636
637 The following controls are specific to video c
638
639 The Brightness, Contrast, Saturation and Hue c
640 standard. There is one special feature with th
641 video input has its own brightness value, so c
642 the brightness for that input. In addition, ea
643 brightness range (minimum and maximum control
644 cause a control event to be sent with the V4L2
645 This allows you to test controls that can chan
646
647 The 'Gain, Automatic' and Gain controls can be
648 if 'Gain, Automatic' is set, then the Gain con
649 constantly. If 'Gain, Automatic' is cleared, t
650 control.
651
652 The 'Horizontal Flip' and 'Vertical Flip' cont
653 image. These combine with the 'Sensor Flipped
654 controls.
655
656 The 'Alpha Component' control can be used to s
657 formats containing an alpha channel.
658
659
660 User Controls - Audio
661 ~~~~~~~~~~~~~~~~~~~~~
662
663 The following controls are specific to video c
664 receivers and transmitters.
665
666 The 'Volume' and 'Mute' audio controls are typ
667 control the volume and mute the audio. They do
668 the vivid driver.
669
670
671 Vivid Controls
672 ~~~~~~~~~~~~~~
673
674 These vivid custom controls control the image
675
676
677 Test Pattern Controls
678 ^^^^^^^^^^^^^^^^^^^^^
679
680 The Test Pattern Controls are all specific to
681
682 - Test Pattern:
683
684 selects which test pattern to use. Use
685 testing colorspace conversions: the co
686 map to valid colors in all colorspaces
687 is disabled for the other test pattern
688
689 - OSD Text Mode:
690
691 selects whether the text superimposed
692 test pattern should be shown, and if s
693 be displayed or the full text.
694
695 - Horizontal Movement:
696
697 selects whether the test pattern shoul
698 move to the left or right and at what
699
700 - Vertical Movement:
701
702 does the same for the vertical directi
703
704 - Show Border:
705
706 show a two-pixel wide border at the ed
707 excluding letter or pillarboxing.
708
709 - Show Square:
710
711 show a square in the middle of the ima
712 displayed with the correct pixel and i
713 then the width and height of the squar
714 the same.
715
716 - Insert SAV Code in Image:
717
718 adds a SAV (Start of Active Video) cod
719 This can be used to check if such code
720 interpreted instead of being ignored.
721
722 - Insert EAV Code in Image:
723
724 does the same for the EAV (End of Acti
725
726 - Insert Video Guard Band
727
728 adds 4 columns of pixels with the HDMI
729 left hand side of the image. This only
730 formats. The RGB pixel value 0xab/0x55
731 to the HDMI Video Guard Band code that
732 (see section 5.2.2.1 in the HDMI 1.3 S
733 receiver has correct HDMI Video Guard
734 control and then move the image to the
735 That will result in video lines that s
736 have the same value as the Video Guard
737 Receivers that will just keep skipping
738 now fail and either loose sync or thes
739
740
741 Capture Feature Selection Controls
742 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
743
744 These controls are all specific to video captu
745
746 - Sensor Flipped Horizontally:
747
748 the image is flipped horizontally and
749 V4L2_IN_ST_HFLIP input status flag is
750 a sensor is for example mounted upside
751
752 - Sensor Flipped Vertically:
753
754 the image is flipped vertically and th
755 V4L2_IN_ST_VFLIP input status flag is
756 a sensor is for example mounted upside
757
758 - Standard Aspect Ratio:
759
760 selects if the image aspect ratio as u
761 S-Video input should be 4x3, 16x9 or a
762 introduce letterboxing.
763
764 - DV Timings Aspect Ratio:
765
766 selects if the image aspect ratio as u
767 input should be the same as the source
768 it should be 4x3 or 16x9. This may int
769
770 - Timestamp Source:
771
772 selects when the timestamp for each bu
773
774 - Colorspace:
775
776 selects which colorspace should be use
777 This only applies if the CSC Colorbar
778 otherwise the test pattern will go thr
779 This behavior is also what you want, s
780 should really have 75% signal intensit
781 by colorspace conversions.
782
783 Changing the colorspace will result in
784 to be sent since it emulates a detecte
785
786 - Transfer Function:
787
788 selects which colorspace transfer func
789 generating an image. This only applies
790 selected, otherwise the test pattern w
791 This behavior is also what you want, s
792 should really have 75% signal intensit
793 by colorspace conversions.
794
795 Changing the transfer function will re
796 to be sent since it emulates a detecte
797
798 - Y'CbCr Encoding:
799
800 selects which Y'CbCr encoding should b
801 a Y'CbCr image. This only applies if t
802 as opposed to an RGB format.
803
804 Changing the Y'CbCr encoding will resu
805 to be sent since it emulates a detecte
806
807 - Quantization:
808
809 selects which quantization should be u
810 encoding when generating the test patt
811
812 Changing the quantization will result
813 to be sent since it emulates a detecte
814
815 - Limited RGB Range (16-235):
816
817 selects if the RGB range of the HDMI s
818 be limited or full range. This combine
819 Quantization Range' control and can be
820 a source provides you with the wrong q
821 See the description of that control fo
822
823 - Apply Alpha To Red Only:
824
825 apply the alpha channel as set by the
826 user control to the red color of the t
827
828 - Enable Capture Cropping:
829
830 enables crop support. This control is
831 the ccs_cap_mode module option is set
832 the no_error_inj module option is set
833
834 - Enable Capture Composing:
835
836 enables composing support. This contro
837 present if the ccs_cap_mode module opt
838 -1 and if the no_error_inj module opti
839
840 - Enable Capture Scaler:
841
842 enables support for a scaler (maximum
843 and downscaling). This control is only
844 module option is set to the default va
845 module option is set to 0 (the default
846
847 - Maximum EDID Blocks:
848
849 determines how many EDID blocks the dr
850 Note that the vivid driver does not ac
851 data, it just stores it. It allows for
852 which is the maximum supported by the
853
854 - Fill Percentage of Frame:
855
856 can be used to draw only the top X per
857 of the image. Since each frame has to
858 demands a lot of the CPU. For large re
859 problematic. By drawing only part of t
860 be reduced.
861
862
863 Output Feature Selection Controls
864 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
865
866 These controls are all specific to video outpu
867
868 - Enable Output Cropping:
869
870 enables crop support. This control is
871 the ccs_out_mode module option is set
872 the no_error_inj module option is set
873
874 - Enable Output Composing:
875
876 enables composing support. This contro
877 present if the ccs_out_mode module opt
878 -1 and if the no_error_inj module opti
879
880 - Enable Output Scaler:
881
882 enables support for a scaler (maximum
883 and downscaling). This control is only
884 module option is set to the default va
885 module option is set to 0 (the default
886
887
888 Error Injection Controls
889 ^^^^^^^^^^^^^^^^^^^^^^^^
890
891 The following two controls are only valid for
892
893 - Standard Signal Mode:
894
895 selects the behavior of VIDIOC_QUERYST
896
897 Changing this control will result in t
898 to be sent since it emulates a changed
899 was plugged in or out).
900
901 - Standard:
902
903 selects the standard that VIDIOC_QUERY
904 previous control is set to "Selected S
905
906 Changing this control will result in t
907 to be sent since it emulates a changed
908
909
910 The following two controls are only valid for
911
912 - DV Timings Signal Mode:
913
914 selects the behavior of VIDIOC_QUERY_D
915 should it return?
916
917 Changing this control will result in t
918 to be sent since it emulates a changed
919 was plugged in or out).
920
921 - DV Timings:
922
923 selects the timings the VIDIOC_QUERY_D
924 if the previous control is set to "Sel
925
926 Changing this control will result in t
927 to be sent since it emulates changed i
928
929
930 The following controls are only present if the
931 is set to 0 (the default). These controls are
932 capture and output streams and for the SDR cap
933 Disconnect control which is valid for all devi
934
935 - Wrap Sequence Number:
936
937 test what happens when you wrap the se
938 struct v4l2_buffer around.
939
940 - Wrap Timestamp:
941
942 test what happens when you wrap the ti
943 v4l2_buffer around.
944
945 - Percentage of Dropped Buffers:
946
947 sets the percentage of buffers that
948 are never returned by the driver (i.e.
949
950 - Disconnect:
951
952 emulates a USB disconnect. The device
953 been disconnected. Only after all open
954 node have been closed will the device
955
956 - Inject V4L2_BUF_FLAG_ERROR:
957
958 when pressed, the next frame returned
959 the driver will have the error flag se
960 corrupt).
961
962 - Inject VIDIOC_REQBUFS Error:
963
964 when pressed, the next REQBUFS or CREA
965 ioctl call will fail with an error. To
966 queue_setup() op will return -EINVAL.
967
968 - Inject VIDIOC_QBUF Error:
969
970 when pressed, the next VIDIOC_QBUF or
971 VIDIOC_PREPARE_BUFFER ioctl call will
972 precise: the videobuf2 buf_prepare() o
973
974 - Inject VIDIOC_STREAMON Error:
975
976 when pressed, the next VIDIOC_STREAMON
977 call will fail with an error. To be pr
978 start_streaming() op will return -EINV
979
980 - Inject Fatal Streaming Error:
981
982 when pressed, the streaming core will
983 marked as having suffered a fatal erro
984 from that is to stop streaming. To be
985 vb2_queue_error() function is called.
986
987
988 VBI Raw Capture Controls
989 ^^^^^^^^^^^^^^^^^^^^^^^^
990
991 - Interlaced VBI Format:
992
993 if set, then the raw VBI data will be
994 of providing it grouped by field.
995
996
997 Digital Video Controls
998 ~~~~~~~~~~~~~~~~~~~~~~
999
1000 - Rx RGB Quantization Range:
1001
1002 sets the RGB quantization detection o
1003 input. This combines with the Vivid '
1004 control and can be used to test what
1005 you with the wrong quantization range
1006 by selecting an HDMI input, setting t
1007 range and selecting the opposite in t
1008 control. The effect is easy to see if
1009 is selected.
1010
1011 - Tx RGB Quantization Range:
1012
1013 sets the RGB quantization detection o
1014 output. It is currently not used for
1015 transmitters would typically have thi
1016
1017 - Transmit Mode:
1018
1019 sets the transmit mode of the HDMI ou
1020 affects the reported colorspace since
1021 sRGB.
1022
1023
1024 FM Radio Receiver Controls
1025 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1026
1027 - RDS Reception:
1028
1029 set if the RDS receiver should be ena
1030
1031 - RDS Program Type:
1032
1033
1034 - RDS PS Name:
1035
1036
1037 - RDS Radio Text:
1038
1039
1040 - RDS Traffic Announcement:
1041
1042
1043 - RDS Traffic Program:
1044
1045
1046 - RDS Music:
1047
1048 these are all read-only controls. If
1049 "Block I/O", then they are inactive a
1050 to "Controls", then these controls re
1051
1052 .. note::
1053 The vivid implementation of this is p
1054 updated when you set a new frequency
1055 (VIDIOC_G_TUNER).
1056
1057 - Radio HW Seek Mode:
1058
1059 can be one of "Bounded", "Wrap Around
1060 determines if VIDIOC_S_HW_FREQ_SEEK w
1061 range or wrap-around or if it is sele
1062
1063 - Radio Programmable HW Seek:
1064
1065 if set, then the user can provide the
1066 upper bound of the HW Seek. Otherwise
1067 will be used.
1068
1069 - Generate RBDS Instead of RDS:
1070
1071 if set, then generate RBDS (the US va
1072 RDS) data instead of RDS (European-st
1073 PICODE and PTY codes.
1074
1075 - RDS Rx I/O Mode:
1076
1077 this can be "Block I/O" where the RDS
1078 by the application, or "Controls" whe
1079 the RDS controls mentioned above.
1080
1081
1082 FM Radio Modulator Controls
1083 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1084
1085 - RDS Program ID:
1086
1087
1088 - RDS Program Type:
1089
1090
1091 - RDS PS Name:
1092
1093
1094 - RDS Radio Text:
1095
1096
1097 - RDS Stereo:
1098
1099
1100 - RDS Artificial Head:
1101
1102
1103 - RDS Compressed:
1104
1105
1106 - RDS Dynamic PTY:
1107
1108
1109 - RDS Traffic Announcement:
1110
1111
1112 - RDS Traffic Program:
1113
1114
1115 - RDS Music:
1116
1117 these are all controls that set the R
1118 the FM modulator.
1119
1120 - RDS Tx I/O Mode:
1121
1122 this can be "Block I/O" where the app
1123 to pass the RDS blocks to the driver,
1124 is Provided by the RDS controls menti
1125
1126 Metadata Capture Controls
1127 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1128
1129 - Generate PTS
1130
1131 if set, then the generated metadata s
1132
1133 - Generate SCR
1134
1135 if set, then the generated metadata s
1136
1137
1138 Video, Sliced VBI and HDMI CEC Looping
1139 --------------------------------------
1140
1141 Video Looping functionality is supported for
1142 vivid driver instance, as well as across mult
1143 The vivid driver supports looping of video an
1144 and an S-Video input. It also supports loopin
1145 HDMI output and an HDMI input.
1146
1147 To enable looping, set the 'HDMI/S-Video XXX-
1148 whether an input uses the Test Pattern Genera
1149 to an output. An input can be connected to an
1150 The inputs and outputs are numbered XXX-N whe
1151 (see module option n_devs). If there is only
1152 XXX will be 000. And N is the Nth S-Video/HDM
1153 If vivid is loaded without module options, th
1154 to the S-Video 000-0 output, or the HDMI 000-
1155 This is the equivalent of connecting or disco
1156 output in a physical device.
1157
1158 If an 'HDMI/S-Video XXX-N Is Connected To' co
1159 output will be looped to the video input prov
1160
1161 - the currently selected input matches the in
1162
1163 - in the vivid instance of the output connect
1164 the output indicated by the control's value
1165
1166 - the video resolution of the video input mus
1167 So it is not possible to loop a 50 Hz (720x
1168 (720x480) S-Video input, or a 720p60 HDMI o
1169
1170 - the pixel formats must be identical on both
1171 have to do pixel format conversion as well,
1172
1173 - the field settings must be identical on bot
1174 requiring the driver to convert from one fi
1175 matters too much. This also prohibits captu
1176 Bottom' when the output video is set to 'Fi
1177 while legal, became too complicated to supp
1178 Alternate' for this to work. Also note that
1179 sequence and field counting in struct v4l2_
1180 be 100% accurate.
1181
1182 - field settings V4L2_FIELD_SEQ_TB/BT are not
1183 implement this, it would mean a lot of work
1184 field values are rarely used the decision w
1185 now.
1186
1187 - on the input side the "Standard Signal Mode
1188 "DV Timings Signal Mode" for the HDMI input
1189 valid signal is passed to the video input.
1190
1191 If any condition is not valid, then the 'Nois
1192
1193 The framerates do not have to match, although
1194
1195 By default you will see the OSD text superimp
1196 This can be turned off by changing the "OSD T
1197 capture device.
1198
1199 For VBI looping to work all of the above must
1200 output must be configured for sliced VBI. The
1201 for either raw or sliced VBI. Note that at th
1202 and WSS (50 Hz formats) VBI data is looped. T
1203
1204
1205 Radio & RDS Looping
1206 -------------------
1207
1208 The vivid driver supports looping of RDS outp
1209
1210 Since radio is wireless this looping always h
1211 frequency is close to the radio transmitter f
1212 transmitter will 'override' the emulated radi
1213
1214 RDS looping is currently supported only betwe
1215 vivid driver instance.
1216
1217 As mentioned in the "Radio Receiver" section,
1218 stations at regular frequency intervals. Depe
1219 radio receiver a signal strength value is cal
1220 VIDIOC_G_TUNER). However, it will also look a
1221 transmitter and if that results in a higher s
1222 of the radio transmitter will be used as if i
1223 includes the RDS data (if any) that the trans
1224 received faithfully on the receiver side. Not
1225 the frequencies of the radio receiver and tra
1226 initially no looping takes place.
1227
1228
1229 Cropping, Composing, Scaling
1230 ----------------------------
1231
1232 This driver supports cropping, composing and
1233 which features are supported can be selected
1234 but it is also possible to hardcode it when t
1235 ccs_cap_mode and ccs_out_mode module options.
1236 the details of these module options.
1237
1238 This allows you to test your application for
1239
1240 Note that the webcam input never supports cro
1241 only applies to the TV/S-Video/HDMI inputs an
1242 webcams, including this virtual implementatio
1243 VIDIOC_ENUM_FRAMESIZES to list a set of discr
1244 And that does not combine with cropping, comp
1245 primarily a limitation of the V4L2 API which
1246
1247 The minimum and maximum resolutions that the
1248 (4096 * 4) x (2160 x 4), but it can only scal
1249 less. So for a source resolution of 1280x720
1250 320x180 and the maximum is 5120x2880. You can
1251 qv4l2 test tool and you will see these depend
1252
1253 This driver also supports larger 'bytesperlin
1254 VIDIOC_S_FMT allows but that few drivers impl
1255
1256 The scaler is a simple scaler that uses the C
1257 designed for speed and simplicity, not qualit
1258
1259 If the combination of crop, compose and scali
1260 to change crop and compose rectangles on the
1261
1262
1263 Formats
1264 -------
1265
1266 The driver supports all the regular packed an
1267 YUYV formats, 8, 16, 24 and 32 RGB packed for
1268 formats.
1269
1270 The alpha component can be set through the 'A
1271 for those formats that support it. If the 'Ap
1272 is set, then the alpha component is only used
1273 0 otherwise.
1274
1275 The driver has to be configured to support th
1276 the driver instances are single-planar. This
1277 multiplanar module option, see "Configuring t
1278 option.
1279
1280 If the driver instance is using the multiplan
1281 single planar format (YUYV) and the multiplan
1282 will have a plane that has a non-zero data_of
1283 data_offset to be non-zero, so this is a usef
1284
1285 Video output will also honor any data_offset
1286
1287
1288 Output Overlay
1289 --------------
1290
1291 Note: output overlays are primarily implement
1292 V4L2 output overlay API. Whether this API sho
1293 questionable.
1294
1295 This driver has support for an output overlay
1296
1297 - bitmap clipping,
1298 - list clipping (up to 16 rectangles)
1299 - chromakey
1300 - source chromakey
1301 - global alpha
1302 - local alpha
1303 - local inverse alpha
1304
1305 Output overlays are not supported for multipl
1306 pixelformat of the capture format and that of
1307 same for the overlay to work. Otherwise VIDIO
1308
1309 Output overlays only work if the driver has b
1310 framebuffer by setting flag 0x10000 in the no
1311 created framebuffer has a size of 720x576 and
1312 RGB 5:6:5.
1313
1314 In order to see the effects of the various cl
1315 processing capabilities you need to turn on v
1316 on the capture side. The use of the clipping,
1317 capabilities will slow down the video loop co
1318 to be done per pixel.
1319
1320
1321 CEC (Consumer Electronics Control)
1322 ----------------------------------
1323
1324 If there are HDMI inputs then a CEC adapter w
1325 the same number of input ports. This is the e
1326 has that number of inputs. Each HDMI output w
1327 CEC adapter that is hooked up to the correspo
1328 are more outputs than inputs) is not hooked u
1329 this is the equivalent of hooking up each out
1330 the TV. Any remaining output devices remain u
1331
1332 The EDID that each output reads reports a uni
1333 based on the physical address of the EDID of
1334 receiver has physical address A.B.0.0, then e
1335 containing physical address A.B.C.0 where C i
1336 there are more outputs than inputs then the r
1337 that is disabled and reports an invalid physi
1338
1339
1340 Some Future Improvements
1341 ------------------------
1342
1343 Just as a reminder and in no particular order
1344
1345 - Add a virtual alsa driver to test audio
1346 - Add virtual sub-devices
1347 - Some support for testing compressed video
1348 - Add support to loop raw VBI output to raw V
1349 - Add support to loop teletext sliced VBI out
1350 - Fix sequence/field numbering when looping o
1351 - Add support for V4L2_CID_BG_COLOR for video
1352 - Add ARGB888 overlay support: better testing
1353 - Improve pixel aspect support in the tpg cod
1354 - Use per-queue locks and/or per-device locks
1355 - The SDR radio should use the same 'frequenc
1356 radio receiver, and give back noise if the
1357 a station frequency
1358 - Make a thread for the RDS generation, that
1359 "Controls" RDS Rx I/O Mode as the read-only
1360 in real-time.
1361 - Changing the EDID doesn't wait 100 ms befor
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.