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