1.. SPDX-License-Identifier: GPL-2.0 2 3The Virtual Video Test Driver (vivid) 4===================================== 5 6This driver emulates video4linux hardware of various types: video capture, video 7output, vbi capture and output, radio receivers and transmitters and a software 8defined radio receiver. In addition a simple framebuffer device is available for 9testing capture and output overlays. 10 11Up to 64 vivid instances can be created, each with up to 16 inputs and 16 outputs. 12 13Each input can be a webcam, TV capture device, S-Video capture device or an HDMI 14capture device. Each output can be an S-Video output device or an HDMI output 15device. 16 17These inputs and outputs act exactly as a real hardware device would behave. This 18allows you to use this driver as a test input for application development, since 19you can test the various features without requiring special hardware. 20 21This 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 40These features will be described in more detail below. 41 42Configuring the driver 43---------------------- 44 45By default the driver will create a single instance that has a video capture 46device with webcam, TV, S-Video and HDMI inputs, a video output device with 47S-Video and HDMI outputs, one vbi capture device, one vbi output device, one 48radio receiver device, one radio transmitter device and one SDR device. 49 50The number of instances, devices, video inputs and outputs and their types are 51all configurable using the following module options: 52 53- n_devs: 54 55 number of driver instances to create. By default set to 1. Up to 64 56 instances can be created. 57 58- node_types: 59 60 which devices should each driver instance create. An array of 61 hexadecimal values, one for each instance. The default is 0x1d3d. 62 Each value is a bitmask with the following meaning: 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 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 77 .. code-block:: none 78 79 n_devs=4 node_types=0x1,0x1,0x100,0x100 80 81- num_inputs: 82 83 the number of inputs, one for each instance. By default 4 inputs 84 are created for each video capture device. At most 16 inputs can be created, 85 and there must be at least one. 86 87- input_types: 88 89 the input types for each instance, the default is 0xe4. This defines 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 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 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 104 .. code-block:: none 105 106 num_inputs=8 input_types=0xffa9 107 108- num_outputs: 109 110 the number of outputs, one for each instance. By default 2 outputs 111 are created for each video output device. At most 16 outputs can be 112 created, and there must be at least one. 113 114- output_types: 115 116 the output types for each instance, the default is 0x02. This defines 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 122 - 0: this is an S-Video output 123 - 1: this is an HDMI output 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 129 .. code-block:: none 130 131 num_outputs=8 output_types=0xf0 132 133- vid_cap_nr: 134 135 give the desired videoX start number for each video capture device. 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 139 .. code-block:: none 140 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 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: 154 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. 157 158- vbi_out_nr: 159 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. 162 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 171 device. The default is -1 which will just take the first free number. 172 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: 179 180 specify the allowed video capture crop/compose/scaling combination 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 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. 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 210- ccs_out_mode: 211 212 specify the allowed video output crop/compose/scaling combination 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 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, 242 and thus the V4L2 multi-planar API. By default device instances are 243 single-planar. 244 245 This module option can override that for each instance. Values are: 246 247 - 1: this is a single-planar instance. 248 - 2: this is a multi-planar instance. 249 250- vivid_debug: 251 252 enable driver debugging info 253 254- no_error_inj: 255 256 if set disable the error injecting controls. This option is 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 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 276Taken together, all these module options allow you to precisely customize 277the driver behavior and test your application with all sorts of permutations. 278It is also very suitable to emulate hardware that is not yet available, e.g. 279when developing software for a new upcoming device. 280 281 282Video Capture 283------------- 284 285This is probably the most frequently used feature. The video capture device 286can be configured by using the module options num_inputs, input_types and 287ccs_cap_mode (see section 1 for more detailed information), but by default 288four inputs are configured: a webcam, a TV tuner, an S-Video and an HDMI 289input, one input for each input type. Those are described in more detail 290below. 291 292Special attention has been given to the rate at which new frames become 293available. The jitter will be around 1 jiffie (that depends on the HZ 294configuration of your kernel, so usually 1/100, 1/250 or 1/1000 of a second), 295but the long-term behavior is exactly following the framerate. So a 296framerate of 59.94 Hz is really different from 60 Hz. If the framerate 297exceeds your kernel's HZ value, then you will get dropped frames, but the 298frame/field sequence counting will keep track of that so the sequence 299count will skip whenever frames are dropped. 300 301 302Webcam Input 303~~~~~~~~~~~~ 304 305The webcam input supports three framesizes: 320x180, 640x360 and 1280x720. It 306supports frames per second settings of 10, 15, 25, 30, 50 and 60 fps. Which ones 307are available depends on the chosen framesize: the larger the framesize, the 308lower the maximum frames per second. 309 310The initially selected colorspace when you switch to the webcam input will be 311sRGB. 312 313 314TV and S-Video Inputs 315~~~~~~~~~~~~~~~~~~~~~ 316 317The only difference between the TV and S-Video input is that the TV has a 318tuner. Otherwise they behave identically. 319 320These inputs support audio inputs as well: one TV and one Line-In. They 321both support all TV standards. If the standard is queried, then the Vivid 322controls 'Standard Signal Mode' and 'Standard' determine what 323the result will be. 324 325These inputs support all combinations of the field setting. Special care has 326been taken to faithfully reproduce how fields are handled for the different 327TV standards. This is particularly noticeable when generating a horizontally 328moving image so the temporal effect of using interlaced formats becomes clearly 329visible. For 50 Hz standards the top field is the oldest and the bottom field 330is the newest in time. For 60 Hz standards that is reversed: the bottom field 331is the oldest and the top field is the newest in time. 332 333When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will 334contain the top field for 50 Hz standards and the bottom field for 60 Hz 335standards. This is what capture hardware does as well. 336 337Finally, for PAL/SECAM standards the first half of the top line contains noise. 338This simulates the Wide Screen Signal that is commonly placed there. 339 340The initially selected colorspace when you switch to the TV or S-Video input 341will be SMPTE-170M. 342 343The pixel aspect ratio will depend on the TV standard. The video aspect ratio 344can be selected through the 'Standard Aspect Ratio' Vivid control. 345Choices are '4x3', '16x9' which will give letterboxed widescreen video and 346'16x9 Anamorphic' which will give full screen squashed anamorphic widescreen 347video that will need to be scaled accordingly. 348 349The TV 'tuner' supports a frequency range of 44-958 MHz. Channels are available 350every 6 MHz, starting from 49.25 MHz. For each channel the generated image 351will 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 353ioctl will return 100% signal strength for +/- 0.25 MHz and 50% for +/- 1 MHz. 354It will also return correct afc values to show whether the frequency is too 355low or too high. 356 357The audio subchannels that are returned are MONO for the +/- 1 MHz range around 358a valid channel frequency. When the frequency is within +/- 0.25 MHz of the 359channel it will return either MONO, STEREO, either MONO | SAP (for NTSC) or 360LANG1 | LANG2 (for others), or STEREO | SAP. 361 362Which one is returned depends on the chosen channel, each next valid channel 363will cycle through the possible audio subchannel combinations. This allows 364you to test the various combinations by just switching channels.. 365 366Finally, for these inputs the v4l2_timecode struct is filled in in the 367dequeued v4l2_buffer struct. 368 369 370HDMI Input 371~~~~~~~~~~ 372 373The HDMI inputs supports all CEA-861 and DMT timings, both progressive and 374interlaced, for pixelclock frequencies between 25 and 600 MHz. The field 375mode for interlaced formats is always V4L2_FIELD_ALTERNATE. For HDMI the 376field order is always top field first, and when you start capturing an 377interlaced format you will receive the top field first. 378 379The initially selected colorspace when you switch to the HDMI input or 380select an HDMI timing is based on the format resolution: for resolutions 381less than or equal to 720x576 the colorspace is set to SMPTE-170M, for 382others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings). 383 384The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it 385set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV 386standard, and for all others a 1:1 pixel aspect ratio is returned. 387 388The video aspect ratio can be selected through the 'DV Timings Aspect Ratio' 389Vivid control. Choices are 'Source Width x Height' (just use the 390same ratio as the chosen format), '4x3' or '16x9', either of which can 391result in pillarboxed or letterboxed video. 392 393For HDMI inputs it is possible to set the EDID. By default a simple EDID 394is provided. You can only set the EDID for HDMI inputs. Internally, however, 395the EDID is shared between all HDMI inputs. 396 397No interpretation is done of the EDID data with the exception of the 398physical address. See the CEC section for more details. 399 400There is a maximum of 15 HDMI inputs (if there are more, then they will be 401reduced to 15) since that's the limitation of the EDID physical address. 402 403 404Video Output 405------------ 406 407The video output device can be configured by using the module options 408num_outputs, output_types and ccs_out_mode (see section 1 for more detailed 409information), but by default two outputs are configured: an S-Video and an 410HDMI input, one output for each output type. Those are described in more detail 411below. 412 413Like with video capture the framerate is also exact in the long term. 414 415 416S-Video Output 417~~~~~~~~~~~~~~ 418 419This output supports audio outputs as well: "Line-Out 1" and "Line-Out 2". 420The S-Video output supports all TV standards. 421 422This output supports all combinations of the field setting. 423 424The initially selected colorspace when you switch to the TV or S-Video input 425will be SMPTE-170M. 426 427 428HDMI Output 429~~~~~~~~~~~ 430 431The HDMI output supports all CEA-861 and DMT timings, both progressive and 432interlaced, for pixelclock frequencies between 25 and 600 MHz. The field 433mode for interlaced formats is always V4L2_FIELD_ALTERNATE. 434 435The initially selected colorspace when you switch to the HDMI output or 436select an HDMI timing is based on the format resolution: for resolutions 437less than or equal to 720x576 the colorspace is set to SMPTE-170M, for 438others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings). 439 440The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it 441set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV 442standard, and for all others a 1:1 pixel aspect ratio is returned. 443 444An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID. 445 446There is a maximum of 15 HDMI outputs (if there are more, then they will be 447reduced to 15) since that's the limitation of the EDID physical address. See 448also the CEC section for more details. 449 450VBI Capture 451----------- 452 453There 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 455support both. This is determined by the node_types module option. In all 456cases the driver will generate valid VBI data: for 60 Hz standards it will 457generate Closed Caption and XDS data. The closed caption stream will 458alternate between "Hello world!" and "Closed captions test" every second. 459The XDS stream will give the current time once a minute. For 50 Hz standards 460it will generate the Wide Screen Signal which is based on the actual Video 461Aspect Ratio control setting and teletext pages 100-159, one page per frame. 462 463The VBI device will only work for the S-Video and TV inputs, it will give 464back an error if the current input is a webcam or HDMI. 465 466 467VBI Output 468---------- 469 470There 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 472support both. This is determined by the node_types module option. 473 474The sliced VBI output supports the Wide Screen Signal and the teletext signal 475for 50 Hz standards and Closed Captioning + XDS for 60 Hz standards. 476 477The VBI device will only work for the S-Video output, it will give 478back an error if the current output is HDMI. 479 480 481Radio Receiver 482-------------- 483 484The radio receiver emulates an FM/AM/SW receiver. The FM band also supports RDS. 485The frequency ranges are: 486 487 - FM: 64 MHz - 108 MHz 488 - AM: 520 kHz - 1710 kHz 489 - SW: 2300 kHz - 26.1 MHz 490 491Valid channels are emulated every 1 MHz for FM and every 100 kHz for AM and SW. 492The signal strength decreases the further the frequency is from the valid 493frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the 494ideal frequency. The initial frequency when the driver is loaded is set to 49595 MHz. 496 497The FM receiver supports RDS as well, both using 'Block I/O' and 'Controls' 498modes. In the 'Controls' mode the RDS information is stored in read-only 499controls. These controls are updated every time the frequency is changed, 500or when the tuner status is requested. The Block I/O method uses the read() 501interface to pass the RDS blocks on to the application for decoding. 502 503The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency, 504and the further the frequency is away from the valid frequency the more RDS 505errors are randomly introduced into the block I/O stream, up to 50% of all 506blocks if you are +/- 12.5 kHz from the channel frequency. All four errors 507can occur in equal proportions: blocks marked 'CORRECTED', blocks marked 508'ERROR', blocks marked 'INVALID' and dropped blocks. 509 510The generated RDS stream contains all the standard fields contained in a 5110B group, and also radio text and the current time. 512 513The receiver supports HW frequency seek, either in Bounded mode, Wrap Around 514mode or both, which is configurable with the "Radio HW Seek Mode" control. 515 516 517Radio Transmitter 518----------------- 519 520The radio transmitter emulates an FM/AM/SW transmitter. The FM band also supports RDS. 521The frequency ranges are: 522 523 - FM: 64 MHz - 108 MHz 524 - AM: 520 kHz - 1710 kHz 525 - SW: 2300 kHz - 26.1 MHz 526 527The initial frequency when the driver is loaded is 95.5 MHz. 528 529The FM transmitter supports RDS as well, both using 'Block I/O' and 'Controls' 530modes. In the 'Controls' mode the transmitted RDS information is configured 531using controls, and in 'Block I/O' mode the blocks are passed to the driver 532using write(). 533 534 535Software Defined Radio Receiver 536------------------------------- 537 538The SDR receiver has three frequency bands for the ADC tuner: 539 540 - 300 kHz 541 - 900 kHz - 2800 kHz 542 - 3200 kHz 543 544The RF tuner supports 50 MHz - 2000 MHz. 545 546The generated data contains the In-phase and Quadrature components of a 5471 kHz tone that has an amplitude of sqrt(2). 548 549 550Controls 551-------- 552 553Different devices support different controls. The sections below will describe 554each control and which devices support them. 555 556 557User Controls - Test Controls 558~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 559 560The Button, Boolean, Integer 32 Bits, Integer 64 Bits, Menu, String, Bitmask and 561Integer Menu are controls that represent all possible control types. The Menu 562control and the Integer Menu control both have 'holes' in their menu list, 563meaning that one or more menu items return EINVAL when VIDIOC_QUERYMENU is called. 564Both menu controls also have a non-zero minimum control value. These features 565allow you to check if your application can handle such things correctly. 566These controls are supported for every device type. 567 568 569User Controls - Video Capture 570~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 571 572The following controls are specific to video capture. 573 574The Brightness, Contrast, Saturation and Hue controls actually work and are 575standard. There is one special feature with the Brightness control: each 576video input has its own brightness value, so changing input will restore 577the brightness for that input. In addition, each video input uses a different 578brightness range (minimum and maximum control values). Switching inputs will 579cause a control event to be sent with the V4L2_EVENT_CTRL_CH_RANGE flag set. 580This allows you to test controls that can change their range. 581 582The 'Gain, Automatic' and Gain controls can be used to test volatile controls: 583if 'Gain, Automatic' is set, then the Gain control is volatile and changes 584constantly. If 'Gain, Automatic' is cleared, then the Gain control is a normal 585control. 586 587The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the 588image. These combine with the 'Sensor Flipped Horizontally/Vertically' Vivid 589controls. 590 591The 'Alpha Component' control can be used to set the alpha component for 592formats containing an alpha channel. 593 594 595User Controls - Audio 596~~~~~~~~~~~~~~~~~~~~~ 597 598The following controls are specific to video capture and output and radio 599receivers and transmitters. 600 601The 'Volume' and 'Mute' audio controls are typical for such devices to 602control the volume and mute the audio. They don't actually do anything in 603the vivid driver. 604 605 606Vivid Controls 607~~~~~~~~~~~~~~ 608 609These vivid custom controls control the image generation, error injection, etc. 610 611 612Test Pattern Controls 613^^^^^^^^^^^^^^^^^^^^^ 614 615The Test Pattern Controls are all specific to video capture. 616 617- Test Pattern: 618 619 selects which test pattern to use. Use the CSC Colorbar for 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 624- OSD Text Mode: 625 626 selects whether the text superimposed on the 627 test pattern should be shown, and if so, whether only counters should 628 be displayed or the full text. 629 630- Horizontal Movement: 631 632 selects whether the test pattern should 633 move to the left or right and at what speed. 634 635- Vertical Movement: 636 637 does the same for the vertical direction. 638 639- Show Border: 640 641 show a two-pixel wide border at the edge of the actual image, 642 excluding letter or pillarboxing. 643 644- Show Square: 645 646 show a square in the middle of the image. If the image is 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 651- Insert SAV Code in Image: 652 653 adds a SAV (Start of Active Video) code to the image. 654 This can be used to check if such codes in the image are inadvertently 655 interpreted instead of being ignored. 656 657- Insert EAV Code in Image: 658 659 does the same for the EAV (End of Active Video) code. 660 661 662Capture Feature Selection Controls 663^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 664 665These controls are all specific to video capture. 666 667- Sensor Flipped Horizontally: 668 669 the image is flipped horizontally and the 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 673- Sensor Flipped Vertically: 674 675 the image is flipped vertically and the 676 V4L2_IN_ST_VFLIP input status flag is set. This emulates the case where 677 a sensor is for example mounted upside down. 678 679- Standard Aspect Ratio: 680 681 selects if the image aspect ratio as used for the TV or 682 S-Video input should be 4x3, 16x9 or anamorphic widescreen. This may 683 introduce letterboxing. 684 685- DV Timings Aspect Ratio: 686 687 selects if the image aspect ratio as used for the HDMI 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 691- Timestamp Source: 692 693 selects when the timestamp for each buffer is taken. 694 695- Colorspace: 696 697 selects which colorspace should be used when generating the image. 698 This only applies if the CSC Colorbar test pattern is selected, 699 otherwise the test pattern will go through unconverted. 700 This behavior is also what you want, since a 75% Colorbar 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 707- Transfer Function: 708 709 selects which colorspace transfer function should be used when 710 generating an image. This only applies if the CSC Colorbar test pattern is 711 selected, otherwise the test pattern will go through unconverted. 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. 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 719- Y'CbCr Encoding: 720 721 selects which Y'CbCr encoding should be used when generating 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. 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 728- Quantization: 729 730 selects which quantization should be used for the RGB or Y'CbCr 731 encoding when generating the test pattern. 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 736- Limited RGB Range (16-235): 737 738 selects if the RGB range of the HDMI source should 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 744- Apply Alpha To Red Only: 745 746 apply the alpha channel as set by the 'Alpha Component' 747 user control to the red color of the test pattern only. 748 749- Enable Capture Cropping: 750 751 enables crop support. This control is only present if 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 755- Enable Capture Composing: 756 757 enables composing support. This control is only 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 761- Enable Capture Scaler: 762 763 enables support for a scaler (maximum 4 times upscaling 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 768- Maximum EDID Blocks: 769 770 determines how many EDID blocks the driver supports. 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 775- Fill Percentage of Frame: 776 777 can be used to draw only the top X percent 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 784Output Feature Selection Controls 785^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 786 787These controls are all specific to video output. 788 789- Enable Output Cropping: 790 791 enables crop support. This control is only present if 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 795- Enable Output Composing: 796 797 enables composing support. This control is only 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 801- Enable Output Scaler: 802 803 enables support for a scaler (maximum 4 times upscaling 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 809Error Injection Controls 810^^^^^^^^^^^^^^^^^^^^^^^^ 811 812The following two controls are only valid for video and vbi capture. 813 814- Standard Signal Mode: 815 816 selects the behavior of VIDIOC_QUERYSTD: what should it return? 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 822- Standard: 823 824 selects the standard that VIDIOC_QUERYSTD should return if the 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 831The following two controls are only valid for video capture. 832 833- DV Timings Signal Mode: 834 835 selects the behavior of VIDIOC_QUERY_DV_TIMINGS: what 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 842- DV Timings: 843 844 selects the timings the VIDIOC_QUERY_DV_TIMINGS should return 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 851The following controls are only present if the no_error_inj module option 852is set to 0 (the default). These controls are valid for video and vbi 853capture and output streams and for the SDR capture device except for the 854Disconnect control which is valid for all devices. 855 856- Wrap Sequence Number: 857 858 test what happens when you wrap the sequence number in 859 struct v4l2_buffer around. 860 861- Wrap Timestamp: 862 863 test what happens when you wrap the timestamp in struct 864 v4l2_buffer around. 865 866- Percentage of Dropped Buffers: 867 868 sets the percentage of buffers that 869 are never returned by the driver (i.e., they are dropped). 870 871- Disconnect: 872 873 emulates a USB disconnect. The device will act as if it has 874 been disconnected. Only after all open filehandles to the device 875 node have been closed will the device become 'connected' again. 876 877- Inject V4L2_BUF_FLAG_ERROR: 878 879 when pressed, the next frame returned by 880 the driver will have the error flag set (i.e. the frame is marked 881 corrupt). 882 883- Inject VIDIOC_REQBUFS Error: 884 885 when pressed, the next REQBUFS or CREATE_BUFS 886 ioctl call will fail with an error. To be precise: the videobuf2 887 queue_setup() op will return -EINVAL. 888 889- Inject VIDIOC_QBUF Error: 890 891 when pressed, the next VIDIOC_QBUF or 892 VIDIOC_PREPARE_BUFFER ioctl call will fail with an error. To be 893 precise: the videobuf2 buf_prepare() op will return -EINVAL. 894 895- Inject VIDIOC_STREAMON Error: 896 897 when pressed, the next VIDIOC_STREAMON ioctl 898 call will fail with an error. To be precise: the videobuf2 899 start_streaming() op will return -EINVAL. 900 901- Inject Fatal Streaming Error: 902 903 when pressed, the streaming core will be 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 909VBI Raw Capture Controls 910^^^^^^^^^^^^^^^^^^^^^^^^ 911 912- Interlaced VBI Format: 913 914 if set, then the raw VBI data will be interlaced instead 915 of providing it grouped by field. 916 917 918Digital Video Controls 919~~~~~~~~~~~~~~~~~~~~~~ 920 921- Rx RGB Quantization Range: 922 923 sets the RGB quantization detection of the HDMI 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 932- Tx RGB Quantization Range: 933 934 sets the RGB quantization detection of the HDMI 935 output. It is currently not used for anything in vivid, but most HDMI 936 transmitters would typically have this control. 937 938- Transmit Mode: 939 940 sets the transmit mode of the HDMI output to HDMI or DVI-D. This 941 affects the reported colorspace since DVI_D outputs will always use 942 sRGB. 943 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 949 950FM 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 962 963- RDS Radio Text: 964 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 975 "Block I/O", then they are inactive as well. If RDS Rx I/O Mode is set 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 980 updated when you set a new frequency or when you get the tuner status 981 (VIDIOC_G_TUNER). 982 983- Radio HW Seek Mode: 984 985 can be one of "Bounded", "Wrap Around" or "Both". This 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 989- Radio Programmable HW Seek: 990 991 if set, then the user can provide the lower and 992 upper bound of the HW Seek. Otherwise the frequency range boundaries 993 will be used. 994 995- Generate RBDS Instead of RDS: 996 997 if set, then generate RBDS (the US variant of 998 RDS) data instead of RDS (European-style RDS). This affects only the 999 PICODE and PTY codes. 1000 1001- RDS Rx I/O Mode: 1002 1003 this can be "Block I/O" where the RDS blocks have to be read() 1004 by the application, or "Controls" where the RDS data is provided by 1005 the RDS controls mentioned above. 1006 1007 1008FM 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 1044 the FM modulator. 1045 1046- RDS Tx I/O Mode: 1047 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. 1051 1052 1053Video, VBI and RDS Looping 1054-------------------------- 1055 1056The vivid driver supports looping of video output to video input, VBI output 1057to VBI input and RDS output to RDS input. For video/VBI looping this emulates 1058as if a cable was hooked up between the output and input connector. So video 1059and VBI looping is only supported between S-Video and HDMI inputs and outputs. 1060VBI is only valid for S-Video as it makes no sense for HDMI. 1061 1062Since radio is wireless this looping always happens if the radio receiver 1063frequency is close to the radio transmitter frequency. In that case the radio 1064transmitter will 'override' the emulated radio stations. 1065 1066Looping is currently supported only between devices created by the same 1067vivid driver instance. 1068 1069 1070Video and Sliced VBI looping 1071~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1072 1073The way to enable video/VBI looping is currently fairly crude. A 'Loop Video' 1074control is available in the "Vivid" control class of the video 1075capture and VBI capture devices. When checked the video looping will be enabled. 1076Once enabled any video S-Video or HDMI input will show a static test pattern 1077until the video output has started. At that time the video output will be 1078looped 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 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 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 1108The framerates do not have to match, although this might change in the future. 1109 1110By default you will see the OSD text superimposed on top of the looped video. 1111This can be turned off by changing the "OSD Text Mode" control of the video 1112capture device. 1113 1114For VBI looping to work all of the above must be valid and in addition the vbi 1115output must be configured for sliced VBI. The VBI capture side can be configured 1116for either raw or sliced VBI. Note that at the moment only CC/XDS (60 Hz formats) 1117and WSS (50 Hz formats) VBI data is looped. Teletext VBI data is not looped. 1118 1119 1120Radio & RDS Looping 1121~~~~~~~~~~~~~~~~~~~ 1122 1123As mentioned in section 6 the radio receiver emulates stations are regular 1124frequency intervals. Depending on the frequency of the radio receiver a 1125signal strength value is calculated (this is returned by VIDIOC_G_TUNER). 1126However, it will also look at the frequency set by the radio transmitter and 1127if that results in a higher signal strength than the settings of the radio 1128transmitter will be used as if it was a valid station. This also includes 1129the RDS data (if any) that the transmitter 'transmits'. This is received 1130faithfully on the receiver side. Note that when the driver is loaded the 1131frequencies of the radio receiver and transmitter are not identical, so 1132initially no looping takes place. 1133 1134 1135Cropping, Composing, Scaling 1136---------------------------- 1137 1138This driver supports cropping, composing and scaling in any combination. Normally 1139which features are supported can be selected through the Vivid controls, 1140but it is also possible to hardcode it when the module is loaded through the 1141ccs_cap_mode and ccs_out_mode module options. See section 1 on the details of 1142these module options. 1143 1144This allows you to test your application for all these variations. 1145 1146Note that the webcam input never supports cropping, composing or scaling. That 1147only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that 1148webcams, including this virtual implementation, normally use 1149VIDIOC_ENUM_FRAMESIZES to list a set of discrete framesizes that it supports. 1150And that does not combine with cropping, composing or scaling. This is 1151primarily a limitation of the V4L2 API which is carefully reproduced here. 1152 1153The 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 1155less. So for a source resolution of 1280x720 the minimum the scaler can do is 1156320x180 and the maximum is 5120x2880. You can play around with this using the 1157qv4l2 test tool and you will see these dependencies. 1158 1159This driver also supports larger 'bytesperline' settings, something that 1160VIDIOC_S_FMT allows but that few drivers implement. 1161 1162The scaler is a simple scaler that uses the Coarse Bresenham algorithm. It's 1163designed for speed and simplicity, not quality. 1164 1165If the combination of crop, compose and scaling allows it, then it is possible 1166to change crop and compose rectangles on the fly. 1167 1168 1169Formats 1170------- 1171 1172The driver supports all the regular packed and planar 4:4:4, 4:2:2 and 4:2:0 1173YUYV formats, 8, 16, 24 and 32 RGB packed formats and various multiplanar 1174formats. 1175 1176The alpha component can be set through the 'Alpha Component' User control 1177for those formats that support it. If the 'Apply Alpha To Red Only' control 1178is set, then the alpha component is only used for the color red and set to 11790 otherwise. 1180 1181The driver has to be configured to support the multiplanar formats. By default 1182the driver instances are single-planar. This can be changed by setting the 1183multiplanar module option, see section 1 for more details on that option. 1184 1185If the driver instance is using the multiplanar formats/API, then the first 1186single planar format (YUYV) and the multiplanar NV16M and NV61M formats the 1187will have a plane that has a non-zero data_offset of 128 bytes. It is rare for 1188data_offset to be non-zero, so this is a useful feature for testing applications. 1189 1190Video output will also honor any data_offset that the application set. 1191 1192 1193Capture Overlay 1194--------------- 1195 1196Note: capture overlay support is implemented primarily to test the existing 1197V4L2 capture overlay API. In practice few if any GPUs support such overlays 1198anymore, and neither are they generally needed anymore since modern hardware 1199is so much more capable. By setting flag 0x10000 in the node_types module 1200option the vivid driver will create a simple framebuffer device that can be 1201used for testing this API. Whether this API should be used for new drivers is 1202questionable. 1203 1204This driver has support for a destructive capture overlay with bitmap clipping 1205and list clipping (up to 16 rectangles) capabilities. Overlays are not 1206supported for multiplanar formats. It also honors the struct v4l2_window field 1207setting: if it is set to FIELD_TOP or FIELD_BOTTOM and the capture setting is 1208FIELD_ALTERNATE, then only the top or bottom fields will be copied to the overlay. 1209 1210The overlay only works if you are also capturing at that same time. This is a 1211vivid limitation since it copies from a buffer to the overlay instead of 1212filling the overlay directly. And if you are not capturing, then no buffers 1213are available to fill. 1214 1215In addition, the pixelformat of the capture format and that of the framebuffer 1216must be the same for the overlay to work. Otherwise VIDIOC_OVERLAY will return 1217an error. 1218 1219In order to really see what it going on you will need to create two vivid 1220instances: the first with a framebuffer enabled. You configure the capture 1221overlay of the second instance to use the framebuffer of the first, then 1222you start capturing in the second instance. For the first instance you setup 1223the output overlay for the video output, turn on video looping and capture 1224to see the blended framebuffer overlay that's being written to by the second 1225instance. This setup would require the following commands: 1226 1227.. code-block:: none 1228 1229 $ sudo modprobe vivid n_devs=2 node_types=0x10101,0x1 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 1244And from another console: 1245 1246.. code-block:: none 1247 1248 $ v4l2-ctl -d1 --stream-out-mmap 1249 1250And yet another console: 1251 1252.. code-block:: none 1253 1254 $ qv4l2 1255 1256and start streaming. 1257 1258As you can see, this is not for the faint of heart... 1259 1260 1261Output Overlay 1262-------------- 1263 1264Note: output overlays are primarily implemented in order to test the existing 1265V4L2 output overlay API. Whether this API should be used for new drivers is 1266questionable. 1267 1268This 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 1278Output overlays are not supported for multiplanar formats. In addition, the 1279pixelformat of the capture format and that of the framebuffer must be the 1280same for the overlay to work. Otherwise VIDIOC_OVERLAY will return an error. 1281 1282Output overlays only work if the driver has been configured to create a 1283framebuffer by setting flag 0x10000 in the node_types module option. The 1284created framebuffer has a size of 720x576 and supports ARGB 1:5:5:5 and 1285RGB 5:6:5. 1286 1287In order to see the effects of the various clipping, chromakeying or alpha 1288processing capabilities you need to turn on video looping and see the results 1289on the capture side. The use of the clipping, chromakeying or alpha processing 1290capabilities will slow down the video loop considerably as a lot of checks have 1291to be done per pixel. 1292 1293 1294CEC (Consumer Electronics Control) 1295---------------------------------- 1296 1297If there are HDMI inputs then a CEC adapter will be created that has 1298the same number of input ports. This is the equivalent of e.g. a TV that 1299has that number of inputs. Each HDMI output will also create a 1300CEC adapter that is hooked up to the corresponding input port, or (if there 1301are more outputs than inputs) is not hooked up at all. In other words, 1302this is the equivalent of hooking up each output device to an input port of 1303the TV. Any remaining output devices remain unconnected. 1304 1305The EDID that each output reads reports a unique CEC physical address that is 1306based on the physical address of the EDID of the input. So if the EDID of the 1307receiver has physical address A.B.0.0, then each output will see an EDID 1308containing physical address A.B.C.0 where C is 1 to the number of inputs. If 1309there are more outputs than inputs then the remaining outputs have a CEC adapter 1310that is disabled and reports an invalid physical address. 1311 1312 1313Some Future Improvements 1314------------------------ 1315 1316Just 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 1322- Add support to loop teletext sliced VBI output to VBI input 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 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 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 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. 1336- Changing the EDID should cause hotplug detect emulation to happen. 1337