Lines Matching +full:in +full:- +full:and +full:- +full:around
1 .. SPDX-License-Identifier: GPL-2.0
7 output, vbi capture and output, metadata capture and output, radio receivers and
8 transmitters, touch capture and a software defined radio receiver. In addition a
9 simple framebuffer device is available for testing capture and output overlays.
11 Up to 64 vivid instances can be created, each with up to 16 inputs and 16 outputs.
13 Each input can be a webcam, TV capture device, S-Video capture device or an HDMI
14 capture device. Each output can be an S-Video output device or an HDMI output
17 These inputs and outputs act exactly as a real hardware device would behave. This
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
42 These features will be described in more detail below.
45 ----------------------
48 device with webcam, TV, S-Video and HDMI inputs, a video output device with
49 S-Video and HDMI outputs, one vbi capture device, one vbi output device, one
50 radio receiver device, one radio transmitter device and one SDR device.
52 The number of instances, devices, video inputs and outputs and their types are
55 - n_devs:
60 - node_types:
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
82 .. code-block:: none
86 - num_inputs:
90 and there must be at least one.
92 - input_types:
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:
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
106 tuner, inputs 1-3 are S-Video inputs and inputs 4-7 are HDMI inputs you
109 .. code-block:: none
113 - num_outputs:
117 created, and there must be at least one.
119 - output_types:
124 gives the type and bit 0 maps to output 0, bit 1 maps to output 1, bit
127 - 0: this is an S-Video output
128 - 1: this is an HDMI output
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
134 .. code-block:: none
138 - vid_cap_nr:
141 The default is -1 which will just take the first free number. This allows
144 .. code-block:: none
153 - vid_out_nr:
156 The default is -1 which will just take the first free number.
158 - vbi_cap_nr:
161 The default is -1 which will just take the first free number.
163 - vbi_out_nr:
166 The default is -1 which will just take the first free number.
168 - radio_rx_nr:
171 The default is -1 which will just take the first free number.
173 - radio_tx_nr:
176 device. The default is -1 which will just take the first free number.
178 - sdr_cap_nr:
181 The default is -1 which will just take the first free number.
183 - meta_cap_nr:
186 The default is -1 which will just take the first free number.
188 - meta_out_nr:
191 The default is -1 which will just take the first free number.
193 - touch_cap_nr:
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.
198 - ccs_cap_mode:
202 of cropping, composing and scaling capabilities and this will tell the
206 The value is either -1 (controlled by the user) or a set of three bits,
209 - bit 0:
213 - bit 1:
218 - bit 2:
223 very simple and low-quality. Simplicity and speed were
227 discrete framesizes and that is incompatible with cropping, composing
230 - ccs_out_mode:
234 of cropping, composing and scaling capabilities and this will tell the
238 The value is either -1 (controlled by the user) or a set of three bits,
241 - bit 0:
246 - bit 1:
251 - bit 2:
256 very simple and low-quality. Simplicity and speed were
259 - multiplanar:
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.
267 - 1: this is a single-planar instance.
268 - 2: this is a multi-planar instance.
270 - vivid_debug:
274 - no_error_inj:
277 needed in order to run a tool like v4l2-compliance. Tools like that
279 emulates a USB disconnect, making the device inaccessible and so
280 all tests that v4l2-compliance is doing will fail afterwards.
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.
288 - allocators:
293 - 0: vmalloc
294 - 1: dma-contig
296 - cache_hints:
298 specifies if the device should set queues' user-space cache and memory
302 - 0: forbid hints
303 - 1: allow hints
305 - supports_requests:
310 - 0: no request
311 - 1: supports requests
312 - 2: requires requests
315 the driver behavior and test your application with all sorts of permutations.
321 -------------
324 can be configured by using the module options num_inputs, input_types and
326 but by default four inputs are configured: a webcam, a TV tuner, an S-Video
327 and an HDMI input, one input for each input type. Those are described in more
331 available. The jitter will be around 1 jiffy (that depends on the HZ
333 but the long-term behavior is exactly following the framerate. So a
343 The webcam input supports three framesizes: 320x180, 640x360 and 1280x720. It
344 supports frames per second settings of 10, 15, 25, 30, 50 and 60 fps. Which ones
352 TV and S-Video Inputs
355 The only difference between the TV and S-Video input is that the TV has a
358 These inputs support audio inputs as well: one TV and one Line-In. They
360 controls 'Standard Signal Mode' and 'Standard' determine what
367 visible. For 50 Hz standards the top field is the oldest and the bottom field
368 is the newest in time. For 60 Hz standards that is reversed: the bottom field
369 is the oldest and the top field is the newest in time.
371 When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will
372 contain the top field for 50 Hz standards and the bottom field for 60 Hz
378 The initially selected colorspace when you switch to the TV or S-Video input
379 will be SMPTE-170M.
383 Choices are '4x3', '16x9' which will give letterboxed widescreen video and
387 The TV 'tuner' supports a frequency range of 44-958 MHz. Channels are available
389 will 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
391 ioctl will return 100% signal strength for +/- 0.25 MHz and 50% for +/- 1 MHz.
395 The audio subchannels that are returned are MONO for the +/- 1 MHz range around
396 a valid channel frequency. When the frequency is within +/- 0.25 MHz of the
404 Finally, for these inputs the v4l2_timecode struct is filled in the
411 The HDMI inputs supports all CEA-861 and DMT timings, both progressive and
412 interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
414 field order is always top field first, and when you start capturing an
419 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
420 others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
424 standard, and for all others a 1:1 pixel aspect ratio is returned.
429 result in pillarboxed or letterboxed video.
443 ------------
446 num_outputs, output_types and ccs_out_mode (see "Configuring the driver"
448 an S-Video and an HDMI input, one output for each output type. Those are
449 described in more detail below.
451 Like with video capture the framerate is also exact in the long term.
454 S-Video Output
457 This output supports audio outputs as well: "Line-Out 1" and "Line-Out 2".
458 The S-Video output supports all TV standards.
462 The initially selected colorspace when you switch to the TV or S-Video input
463 will be SMPTE-170M.
469 The HDMI output supports all CEA-861 and DMT timings, both progressive and
470 interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
475 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
476 others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
480 standard, and for all others a 1:1 pixel aspect ratio is returned.
489 -----------
492 (undecoded) VBI, those that only support sliced (decoded) VBI and those that
493 support both. This is determined by the node_types module option. In all
495 generate Closed Caption and XDS data. The closed caption stream will
496 alternate between "Hello world!" and "Closed captions test" every second.
499 Aspect Ratio control setting and teletext pages 100-159, one page per frame.
501 The VBI device will only work for the S-Video and TV inputs, it will give
506 ----------
509 (undecoded) VBI, those that only support sliced (decoded) VBI and those that
512 The sliced VBI output supports the Wide Screen Signal and the teletext signal
513 for 50 Hz standards and Closed Captioning + XDS for 60 Hz standards.
515 The VBI device will only work for the S-Video output, it will give
520 --------------
525 - FM: 64 MHz - 108 MHz
526 - AM: 520 kHz - 1710 kHz
527 - SW: 2300 kHz - 26.1 MHz
529 Valid channels are emulated every 1 MHz for FM and every 100 kHz for AM and SW.
531 frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the
535 The FM receiver supports RDS as well, both using 'Block I/O' and 'Controls'
536 modes. In the 'Controls' mode the RDS information is stored in read-only
541 The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency,
542 and the further the frequency is away from the valid frequency the more RDS
544 blocks if you are +/- 12.5 kHz from the channel frequency. All four errors
545 can occur in equal proportions: blocks marked 'CORRECTED', blocks marked
546 'ERROR', blocks marked 'INVALID' and dropped blocks.
548 The generated RDS stream contains all the standard fields contained in a
549 0B group, and also radio text and the current time.
551 The receiver supports HW frequency seek, either in Bounded mode, Wrap Around
556 -----------------
561 - FM: 64 MHz - 108 MHz
562 - AM: 520 kHz - 1710 kHz
563 - SW: 2300 kHz - 26.1 MHz
567 The FM transmitter supports RDS as well, both using 'Block I/O' and 'Controls'
568 modes. In the 'Controls' mode the transmitted RDS information is configured
569 using controls, and in 'Block I/O' mode the blocks are passed to the driver
574 -------------------------------
578 - 300 kHz
579 - 900 kHz - 2800 kHz
580 - 3200 kHz
582 The RF tuner supports 50 MHz - 2000 MHz.
584 The generated data contains the In-phase and Quadrature components of a
589 ----------------
591 The Metadata capture generates UVC format metadata. The PTS and SCR are
592 transmitted based on the values set in vivid controls.
599 ---------------
601 The Metadata output can be used to set brightness, contrast, saturation and hue.
608 -------------
611 triple tap, move from left to right, zoom in, zoom out, palm press (simulating
612 a large area being pressed on a touchpad), and simulating 16 simultaneous
616 --------
619 each control and which devices support them.
622 User Controls - Test Controls
625 The Button, Boolean, Integer 32 Bits, Integer 64 Bits, Menu, String, Bitmask and
627 control and the Integer Menu control both have 'holes' in their menu list,
629 Both menu controls also have a non-zero minimum control value. These features
634 User Controls - Video Capture
639 The Brightness, Contrast, Saturation and Hue controls actually work and are
642 the brightness for that input. In addition, each video input uses a different
643 brightness range (minimum and maximum control values). Switching inputs will
647 The 'Gain, Automatic' and Gain controls can be used to test volatile controls:
648 if 'Gain, Automatic' is set, then the Gain control is volatile and changes
652 The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the
660 User Controls - Audio
663 The following controls are specific to video capture and output and radio
664 receivers and transmitters.
666 The 'Volume' and 'Mute' audio controls are typical for such devices to
667 control the volume and mute the audio. They don't actually do anything in
682 - Test Pattern:
685 testing colorspace conversions: the colors used in that test pattern
686 map to valid colors in all colorspaces. The colorspace conversion
689 - OSD Text Mode:
692 test pattern should be shown, and if so, whether only counters should
695 - Horizontal Movement:
698 move to the left or right and at what speed.
700 - Vertical Movement:
704 - Show Border:
706 show a two-pixel wide border at the edge of the actual image,
709 - Show Square:
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
716 - Insert SAV Code in Image:
719 This can be used to check if such codes in the image are inadvertently
722 - Insert EAV Code in Image:
726 - Insert Video Guard Band
732 (see section 5.2.2.1 in the HDMI 1.3 Specification). To test if a video
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
738 now fail and either loose sync or these video lines will shift.
746 - Sensor Flipped Horizontally:
748 the image is flipped horizontally and the
752 - Sensor Flipped Vertically:
754 the image is flipped vertically and the
758 - Standard Aspect Ratio:
761 S-Video input should be 4x3, 16x9 or anamorphic widescreen. This may
764 - DV Timings Aspect Ratio:
767 input should be the same as the source width and height ratio, or if
770 - Timestamp Source:
774 - Colorspace:
780 should really have 75% signal intensity and should not be affected
783 Changing the colorspace will result in the V4L2_EVENT_SOURCE_CHANGE
786 - Transfer Function:
792 should really have 75% signal intensity and should not be affected
795 Changing the transfer function will result in the V4L2_EVENT_SOURCE_CHANGE
798 - Y'CbCr Encoding:
804 Changing the Y'CbCr encoding will result in the V4L2_EVENT_SOURCE_CHANGE
807 - Quantization:
812 Changing the quantization will result in the V4L2_EVENT_SOURCE_CHANGE
815 - Limited RGB Range (16-235):
819 Quantization Range' control and can be used to test what happens if
823 - Apply Alpha To Red Only:
828 - Enable Capture Cropping:
831 the ccs_cap_mode module option is set to the default value of -1 and if
834 - Enable Capture Composing:
838 -1 and if the no_error_inj module option is set to 0 (the default).
840 - Enable Capture Scaler:
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
847 - Maximum EDID Blocks:
854 - Fill Percentage of Frame:
868 - Enable Output Cropping:
871 the ccs_out_mode module option is set to the default value of -1 and if
874 - Enable Output Composing:
878 -1 and if the no_error_inj module option is set to 0 (the default).
880 - Enable Output Scaler:
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
891 The following two controls are only valid for video and vbi capture.
893 - Standard Signal Mode:
897 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
899 was plugged in or out).
901 - Standard:
906 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
912 - DV Timings Signal Mode:
917 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
919 was plugged in or out).
921 - DV Timings:
926 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
931 is set to 0 (the default). These controls are valid for video and vbi
932 capture and output streams and for the SDR capture device except for the
935 - Wrap Sequence Number:
937 test what happens when you wrap the sequence number in
938 struct v4l2_buffer around.
940 - Wrap Timestamp:
942 test what happens when you wrap the timestamp in struct
943 v4l2_buffer around.
945 - Percentage of Dropped Buffers:
950 - Disconnect:
956 - Inject V4L2_BUF_FLAG_ERROR:
962 - Inject VIDIOC_REQBUFS Error:
966 queue_setup() op will return -EINVAL.
968 - Inject VIDIOC_QBUF Error:
972 precise: the videobuf2 buf_prepare() op will return -EINVAL.
974 - Inject VIDIOC_STREAMON Error:
978 start_streaming() op will return -EINVAL.
980 - Inject Fatal Streaming Error:
991 - Interlaced VBI Format:
1000 - Rx RGB Quantization Range:
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
1007 range and selecting the opposite in the 'Limited RGB Range (16-235)'
1011 - Tx RGB Quantization Range:
1014 output. It is currently not used for anything in vivid, but most HDMI
1017 - Transmit Mode:
1019 sets the transmit mode of the HDMI output to HDMI or DVI-D. This
1027 - RDS Reception:
1031 - RDS Program Type:
1034 - RDS PS Name:
1037 - RDS Radio Text:
1040 - RDS Traffic Announcement:
1043 - RDS Traffic Program:
1046 - RDS Music:
1048 these are all read-only controls. If RDS Rx I/O Mode is set to
1057 - Radio HW Seek Mode:
1059 can be one of "Bounded", "Wrap Around" or "Both". This
1061 range or wrap-around or if it is selectable by the user.
1063 - Radio Programmable HW Seek:
1065 if set, then the user can provide the lower and
1069 - Generate RBDS Instead of RDS:
1072 RDS) data instead of RDS (European-style RDS). This affects only the
1073 PICODE and PTY codes.
1075 - RDS Rx I/O Mode:
1085 - RDS Program ID:
1088 - RDS Program Type:
1091 - RDS PS Name:
1094 - RDS Radio Text:
1097 - RDS Stereo:
1100 - RDS Artificial Head:
1103 - RDS Compressed:
1106 - RDS Dynamic PTY:
1109 - RDS Traffic Announcement:
1112 - RDS Traffic Program:
1115 - RDS Music:
1120 - RDS Tx I/O Mode:
1129 - Generate PTS
1133 - Generate SCR
1138 Video, Sliced VBI and HDMI CEC Looping
1139 --------------------------------------
1143 The vivid driver supports looping of video and Sliced VBI data between an S-Video output
1144 and an S-Video input. It also supports looping of video and HDMI CEC data between an
1145 HDMI output and an HDMI input.
1147 To enable looping, set the 'HDMI/S-Video XXX-N Is Connected To' control(s) to select
1150 The inputs and outputs are numbered XXX-N where XXX is the vivid instance number
1152 XXX will be 000. And N is the Nth S-Video/HDMI input or output of that instance.
1153 If vivid is loaded without module options, then you can connect the S-Video 000-0 input
1154 to the S-Video 000-0 output, or the HDMI 000-0 input to the HDMI 000-0 output.
1155 This is the equivalent of connecting or disconnecting a cable between an input and an
1156 output in a physical device.
1158 If an 'HDMI/S-Video XXX-N Is Connected To' control selected an output, then the video
1161 - the currently selected input matches the input indicated by the control name.
1163 - in the vivid instance of the output connector, the currently selected output matches
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.
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.
1173 - the field settings must be identical on both sides. Same reason as above:
1179 sequence and field counting in struct v4l2_buffer on the capture side may not
1182 - field settings V4L2_FIELD_SEQ_TB/BT are not supported. While it is possible to
1187 - on the input side the "Standard Signal Mode" for the S-Video input or the
1193 The framerates do not have to match, although this might change in the future.
1199 For VBI looping to work all of the above must be valid and in addition the vbi
1202 and WSS (50 Hz formats) VBI data is looped. Teletext VBI data is not looped.
1206 -------------------
1211 frequency is close to the radio transmitter frequency. In that case the radio
1217 As mentioned in the "Radio Receiver" section, the radio receiver emulates
1221 transmitter and if that results in a higher signal strength than the settings
1225 the frequencies of the radio receiver and transmitter are not identical, so
1230 ----------------------------
1232 This driver supports cropping, composing and scaling in any combination. Normally
1235 ccs_cap_mode and ccs_out_mode module options. See "Configuring the driver" on
1241 only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that
1244 And that does not combine with cropping, composing or scaling. This is
1247 The minimum and maximum resolutions that the scaler can achieve are 16x16 and
1250 320x180 and the maximum is 5120x2880. You can play around with this using the
1251 qv4l2 test tool and you will see these dependencies.
1257 designed for speed and simplicity, not quality.
1259 If the combination of crop, compose and scaling allows it, then it is possible
1260 to change crop and compose rectangles on the fly.
1264 -------
1266 The driver supports all the regular packed and planar 4:4:4, 4:2:2 and 4:2:0
1267 YUYV formats, 8, 16, 24 and 32 RGB packed formats and various multiplanar
1272 is set, then the alpha component is only used for the color red and set to
1276 the driver instances are single-planar. This can be changed by setting the
1281 single planar format (YUYV) and the multiplanar NV16M and NV61M formats the
1282 will have a plane that has a non-zero data_offset of 128 bytes. It is rare for
1283 data_offset to be non-zero, so this is a useful feature for testing applications.
1289 --------------
1291 Note: output overlays are primarily implemented in order to test the existing
1295 This driver has support for an output overlay and is capable of:
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
1305 Output overlays are not supported for multiplanar formats. In addition, the
1306 pixelformat of the capture format and that of the framebuffer must be the
1310 framebuffer by setting flag 0x10000 in the node_types module option. The
1311 created framebuffer has a size of 720x576 and supports ARGB 1:5:5:5 and
1314 In order to see the effects of the various clipping, chromakeying or alpha
1315 processing capabilities you need to turn on video looping and see the results
1322 ----------------------------------
1328 are more outputs than inputs) is not hooked up at all. In other words,
1337 that is disabled and reports an invalid physical address.
1341 ------------------------
1343 Just as a reminder and in no particular order:
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
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.