1 .. SPDX-License-Identifier: GPL-2.0
2
3 The Virtual Stateless Decoder Driver (visl)
4 ===========================================
5
6 A virtual stateless decoder device for statele
7 purposes.
8
9 This tool's objective is to help the developme
10 userspace applications that use the V4L2 state
11
12 A userspace implementation can use visl to run
13 no hardware is available or when the kernel uA
14 been upstreamed yet. This can reveal bugs at a
15
16 This driver can also trace the contents of the
17 to it. It can also dump the contents of the v
18 debugfs interface. This is in many ways simila
19 infrastructure available for other popular enc
20 and can help develop a userspace application b
21 one as a reference.
22
23 .. note::
24
25 No actual decoding of video frames is
26 V4L2 test pattern generator is used to
27 to the capture buffers instead.
28
29 Module parameters
30 -----------------
31
32 - visl_debug: Activates debug info, printing v
33 dprintk. Also controls whether per-frame deb
34 Note that enabling this feature can result i
35
36 - visl_transtime_ms: Simulated process time in
37 decoding speed can be useful for debugging.
38
39 - visl_dprintk_frame_start, visl_dprintk_frame
40 frames where dprintk is activated. This only
41 per-frame basis. Note that printing a lot of
42
43 - keep_bitstream_buffers: Controls whether bit
44 kept after a decoding session. Defaults to f
45 clutter. keep_bitstream_buffers == false wor
46 client program with GDB.
47
48 - bitstream_trace_frame_start, bitstream_trace
49 visl_dprintk_frame_start, visl_dprintk_nfram
50 buffer data through debugfs instead.
51
52 - tpg_verbose: Write extra information on each
53 the API. When set to true, the output frames
54 as some information like pointers or queue s
55
56 What is the default use case for this driver?
57 ---------------------------------------------
58
59 This driver can be used as a way to compare di
60 This assumes that a working client is run agai
61 OUTPUT buffer data is subsequently used to deb
62 implementation.
63
64 Even though no video decoding is actually done
65 against a reference for a given input, except
66
67 Depending on the tpg_verbose parameter value,
68 their timestamps, the status of the OUTPUT and
69 read directly from the CAPTURE buffers.
70
71 Supported codecs
72 ----------------
73
74 The following codecs are supported:
75
76 - FWHT
77 - MPEG2
78 - VP8
79 - VP9
80 - H.264
81 - HEVC
82 - AV1
83
84 visl trace events
85 -----------------
86 The trace events are defined on a per-codec ba
87
88 .. code-block:: bash
89
90 $ ls /sys/kernel/tracing/events/ | gre
91 visl_av1_controls
92 visl_fwht_controls
93 visl_h264_controls
94 visl_hevc_controls
95 visl_mpeg2_controls
96 visl_vp8_controls
97 visl_vp9_controls
98
99 For example, in order to dump HEVC SPS data:
100
101 .. code-block:: bash
102
103 $ echo 1 > /sys/kernel/tracing/events
104
105 The SPS data will be dumped to the trace buffe
106
107 .. code-block:: bash
108
109 $ cat /sys/kernel/tracing/trace
110 video_parameter_set_id 0
111 seq_parameter_set_id 0
112 pic_width_in_luma_samples 1920
113 pic_height_in_luma_samples 1080
114 bit_depth_luma_minus8 0
115 bit_depth_chroma_minus8 0
116 log2_max_pic_order_cnt_lsb_minus4 4
117 sps_max_dec_pic_buffering_minus1 6
118 sps_max_num_reorder_pics 2
119 sps_max_latency_increase_plus1 0
120 log2_min_luma_coding_block_size_minus3
121 log2_diff_max_min_luma_coding_block_si
122 log2_min_luma_transform_block_size_min
123 log2_diff_max_min_luma_transform_block
124 max_transform_hierarchy_depth_inter 2
125 max_transform_hierarchy_depth_intra 2
126 pcm_sample_bit_depth_luma_minus1 0
127 pcm_sample_bit_depth_chroma_minus1 0
128 log2_min_pcm_luma_coding_block_size_mi
129 log2_diff_max_min_pcm_luma_coding_bloc
130 num_short_term_ref_pic_sets 0
131 num_long_term_ref_pics_sps 0
132 chroma_format_idc 1
133 sps_max_sub_layers_minus1 0
134 flags AMP_ENABLED|SAMPLE_ADAPTIVE_OFFS
135
136
137 Dumping OUTPUT buffer data through debugfs
138 ------------------------------------------
139
140 If the **VISL_DEBUGFS** Kconfig is enabled, vi
141 **/sys/kernel/debug/visl/bitstream** with OUTP
142 values of bitstream_trace_frame_start and bits
143 highlight errors as broken clients may fail to
144
145 A single file is created for each processed OU
146 integer that denotes the buffer sequence, i.e.
147
148 .. code-block:: c
149
150 snprintf(name, 32, "bitstream%d", run-
151
152 Dumping the values is simply a matter of readi
153
154 For the buffer with sequence == 0:
155
156 .. code-block:: bash
157
158 $ xxd /sys/kernel/debug/visl/bitstream
159 00000000: 2601 af04 d088 bc25 a173 0e4
160 00000010: c668 cb28 e775 b4ac f53a ba6
161 00000020: 46b4 bcfc 506c e227 2372 e5f
162 00000030: 6371 5eb5 0eb8 23b5 ca6a 5de
163 00000040: e8c3 4320 b4ba a226 cbc1 413
164 00000050: fef3 247b 3523 4e90 9682 ac8
165 00000060: ddd0 6cfc 0187 0e20 7aae b15
166 00000070: e1c5 f425 a83a 00b7 4f18 812
167
168 For the buffer with sequence == 1:
169
170 .. code-block:: bash
171
172 $ xxd /sys/kernel/debug/visl/bitstream
173 00000000: 0201 d021 49e1 0c40 aa11 144
174 00000010: 7023 889a c8cd 2cd0 13b4 dab
175 00000020: c4c8 ab4c 486e 4e2f b0df 96c
176 00000030: 8ce7 ee36 d880 4095 4d64 30a
177 00000040: f16b a6a1 d806 ca2a 0ece a67
178 00000050: 370f 5bb9 1dc4 ba21 6434 bc5
179 00000060: dfe6 bc99 01ea b6e0 346b 92b
180 00000070: e7cc 3484 1769 fef2 a693 a94
181
182 And so on.
183
184 By default, the files are removed during STREA
185 of clutter.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.