vivid.rst

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