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