1*0c078e31SDaniel Almeida.. SPDX-License-Identifier: GPL-2.0 2*0c078e31SDaniel Almeida 3*0c078e31SDaniel AlmeidaThe Virtual Stateless Decoder Driver (visl) 4*0c078e31SDaniel Almeida=========================================== 5*0c078e31SDaniel Almeida 6*0c078e31SDaniel AlmeidaA virtual stateless decoder device for stateless uAPI development 7*0c078e31SDaniel Almeidapurposes. 8*0c078e31SDaniel Almeida 9*0c078e31SDaniel AlmeidaThis tool's objective is to help the development and testing of 10*0c078e31SDaniel Almeidauserspace applications that use the V4L2 stateless API to decode media. 11*0c078e31SDaniel Almeida 12*0c078e31SDaniel AlmeidaA userspace implementation can use visl to run a decoding loop even when 13*0c078e31SDaniel Almeidano hardware is available or when the kernel uAPI for the codec has not 14*0c078e31SDaniel Almeidabeen upstreamed yet. This can reveal bugs at an early stage. 15*0c078e31SDaniel Almeida 16*0c078e31SDaniel AlmeidaThis driver can also trace the contents of the V4L2 controls submitted 17*0c078e31SDaniel Almeidato it. It can also dump the contents of the vb2 buffers through a 18*0c078e31SDaniel Almeidadebugfs interface. This is in many ways similar to the tracing 19*0c078e31SDaniel Almeidainfrastructure available for other popular encode/decode APIs out there 20*0c078e31SDaniel Almeidaand can help develop a userspace application by using another (working) 21*0c078e31SDaniel Almeidaone as a reference. 22*0c078e31SDaniel Almeida 23*0c078e31SDaniel Almeida.. note:: 24*0c078e31SDaniel Almeida 25*0c078e31SDaniel Almeida No actual decoding of video frames is performed by visl. The 26*0c078e31SDaniel Almeida V4L2 test pattern generator is used to write various debug information 27*0c078e31SDaniel Almeida to the capture buffers instead. 28*0c078e31SDaniel Almeida 29*0c078e31SDaniel AlmeidaModule parameters 30*0c078e31SDaniel Almeida----------------- 31*0c078e31SDaniel Almeida 32*0c078e31SDaniel Almeida- visl_debug: Activates debug info, printing various debug messages through 33*0c078e31SDaniel Almeida dprintk. Also controls whether per-frame debug info is shown. Defaults to off. 34*0c078e31SDaniel Almeida Note that enabling this feature can result in slow performance through serial. 35*0c078e31SDaniel Almeida 36*0c078e31SDaniel Almeida- visl_transtime_ms: Simulated process time in milliseconds. Slowing down the 37*0c078e31SDaniel Almeida decoding speed can be useful for debugging. 38*0c078e31SDaniel Almeida 39*0c078e31SDaniel Almeida- visl_dprintk_frame_start, visl_dprintk_frame_nframes: Dictates a range of 40*0c078e31SDaniel Almeida frames where dprintk is activated. This only controls the dprintk tracing on a 41*0c078e31SDaniel Almeida per-frame basis. Note that printing a lot of data can be slow through serial. 42*0c078e31SDaniel Almeida 43*0c078e31SDaniel Almeida- keep_bitstream_buffers: Controls whether bitstream (i.e. OUTPUT) buffers are 44*0c078e31SDaniel Almeida kept after a decoding session. Defaults to false so as to reduce the amount of 45*0c078e31SDaniel Almeida clutter. keep_bitstream_buffers == false works well when live debugging the 46*0c078e31SDaniel Almeida client program with GDB. 47*0c078e31SDaniel Almeida 48*0c078e31SDaniel Almeida- bitstream_trace_frame_start, bitstream_trace_nframes: Similar to 49*0c078e31SDaniel Almeida visl_dprintk_frame_start, visl_dprintk_nframes, but controls the dumping of 50*0c078e31SDaniel Almeida buffer data through debugfs instead. 51*0c078e31SDaniel Almeida 52*0c078e31SDaniel AlmeidaWhat is the default use case for this driver? 53*0c078e31SDaniel Almeida--------------------------------------------- 54*0c078e31SDaniel Almeida 55*0c078e31SDaniel AlmeidaThis driver can be used as a way to compare different userspace implementations. 56*0c078e31SDaniel AlmeidaThis assumes that a working client is run against visl and that the ftrace and 57*0c078e31SDaniel AlmeidaOUTPUT buffer data is subsequently used to debug a work-in-progress 58*0c078e31SDaniel Almeidaimplementation. 59*0c078e31SDaniel Almeida 60*0c078e31SDaniel AlmeidaInformation on reference frames, their timestamps, the status of the OUTPUT and 61*0c078e31SDaniel AlmeidaCAPTURE queues and more can be read directly from the CAPTURE buffers. 62*0c078e31SDaniel Almeida 63*0c078e31SDaniel AlmeidaSupported codecs 64*0c078e31SDaniel Almeida---------------- 65*0c078e31SDaniel Almeida 66*0c078e31SDaniel AlmeidaThe following codecs are supported: 67*0c078e31SDaniel Almeida 68*0c078e31SDaniel Almeida- FWHT 69*0c078e31SDaniel Almeida- MPEG2 70*0c078e31SDaniel Almeida- VP8 71*0c078e31SDaniel Almeida- VP9 72*0c078e31SDaniel Almeida- H.264 73*0c078e31SDaniel Almeida- HEVC 74*0c078e31SDaniel Almeida 75*0c078e31SDaniel Almeidavisl trace events 76*0c078e31SDaniel Almeida----------------- 77*0c078e31SDaniel AlmeidaThe trace events are defined on a per-codec basis, e.g.: 78*0c078e31SDaniel Almeida 79*0c078e31SDaniel Almeida.. code-block:: bash 80*0c078e31SDaniel Almeida 81*0c078e31SDaniel Almeida $ ls /sys/kernel/debug/tracing/events/ | grep visl 82*0c078e31SDaniel Almeida visl_fwht_controls 83*0c078e31SDaniel Almeida visl_h264_controls 84*0c078e31SDaniel Almeida visl_hevc_controls 85*0c078e31SDaniel Almeida visl_mpeg2_controls 86*0c078e31SDaniel Almeida visl_vp8_controls 87*0c078e31SDaniel Almeida visl_vp9_controls 88*0c078e31SDaniel Almeida 89*0c078e31SDaniel AlmeidaFor example, in order to dump HEVC SPS data: 90*0c078e31SDaniel Almeida 91*0c078e31SDaniel Almeida.. code-block:: bash 92*0c078e31SDaniel Almeida 93*0c078e31SDaniel Almeida $ echo 1 > /sys/kernel/debug/tracing/events/visl_hevc_controls/v4l2_ctrl_hevc_sps/enable 94*0c078e31SDaniel Almeida 95*0c078e31SDaniel AlmeidaThe SPS data will be dumped to the trace buffer, i.e.: 96*0c078e31SDaniel Almeida 97*0c078e31SDaniel Almeida.. code-block:: bash 98*0c078e31SDaniel Almeida 99*0c078e31SDaniel Almeida $ cat /sys/kernel/debug/tracing/trace 100*0c078e31SDaniel Almeida video_parameter_set_id 0 101*0c078e31SDaniel Almeida seq_parameter_set_id 0 102*0c078e31SDaniel Almeida pic_width_in_luma_samples 1920 103*0c078e31SDaniel Almeida pic_height_in_luma_samples 1080 104*0c078e31SDaniel Almeida bit_depth_luma_minus8 0 105*0c078e31SDaniel Almeida bit_depth_chroma_minus8 0 106*0c078e31SDaniel Almeida log2_max_pic_order_cnt_lsb_minus4 4 107*0c078e31SDaniel Almeida sps_max_dec_pic_buffering_minus1 6 108*0c078e31SDaniel Almeida sps_max_num_reorder_pics 2 109*0c078e31SDaniel Almeida sps_max_latency_increase_plus1 0 110*0c078e31SDaniel Almeida log2_min_luma_coding_block_size_minus3 0 111*0c078e31SDaniel Almeida log2_diff_max_min_luma_coding_block_size 3 112*0c078e31SDaniel Almeida log2_min_luma_transform_block_size_minus2 0 113*0c078e31SDaniel Almeida log2_diff_max_min_luma_transform_block_size 3 114*0c078e31SDaniel Almeida max_transform_hierarchy_depth_inter 2 115*0c078e31SDaniel Almeida max_transform_hierarchy_depth_intra 2 116*0c078e31SDaniel Almeida pcm_sample_bit_depth_luma_minus1 0 117*0c078e31SDaniel Almeida pcm_sample_bit_depth_chroma_minus1 0 118*0c078e31SDaniel Almeida log2_min_pcm_luma_coding_block_size_minus3 0 119*0c078e31SDaniel Almeida log2_diff_max_min_pcm_luma_coding_block_size 0 120*0c078e31SDaniel Almeida num_short_term_ref_pic_sets 0 121*0c078e31SDaniel Almeida num_long_term_ref_pics_sps 0 122*0c078e31SDaniel Almeida chroma_format_idc 1 123*0c078e31SDaniel Almeida sps_max_sub_layers_minus1 0 124*0c078e31SDaniel Almeida flags AMP_ENABLED|SAMPLE_ADAPTIVE_OFFSET|TEMPORAL_MVP_ENABLED|STRONG_INTRA_SMOOTHING_ENABLED 125*0c078e31SDaniel Almeida 126*0c078e31SDaniel Almeida 127*0c078e31SDaniel AlmeidaDumping OUTPUT buffer data through debugfs 128*0c078e31SDaniel Almeida------------------------------------------ 129*0c078e31SDaniel Almeida 130*0c078e31SDaniel AlmeidaIf the **VISL_DEBUGFS** Kconfig is enabled, visl will populate 131*0c078e31SDaniel Almeida**/sys/kernel/debug/visl/bitstream** with OUTPUT buffer data according to the 132*0c078e31SDaniel Almeidavalues of bitstream_trace_frame_start and bitstream_trace_nframes. This can 133*0c078e31SDaniel Almeidahighlight errors as broken clients may fail to fill the buffers properly. 134*0c078e31SDaniel Almeida 135*0c078e31SDaniel AlmeidaA single file is created for each processed OUTPUT buffer. Its name contains an 136*0c078e31SDaniel Almeidainteger that denotes the buffer sequence, i.e.: 137*0c078e31SDaniel Almeida 138*0c078e31SDaniel Almeida.. code-block:: c 139*0c078e31SDaniel Almeida 140*0c078e31SDaniel Almeida snprintf(name, 32, "bitstream%d", run->src->sequence); 141*0c078e31SDaniel Almeida 142*0c078e31SDaniel AlmeidaDumping the values is simply a matter of reading from the file, i.e.: 143*0c078e31SDaniel Almeida 144*0c078e31SDaniel AlmeidaFor the buffer with sequence == 0: 145*0c078e31SDaniel Almeida 146*0c078e31SDaniel Almeida.. code-block:: bash 147*0c078e31SDaniel Almeida 148*0c078e31SDaniel Almeida $ xxd /sys/kernel/debug/visl/bitstream/bitstream0 149*0c078e31SDaniel Almeida 00000000: 2601 af04 d088 bc25 a173 0e41 a4f2 3274 &......%.s.A..2t 150*0c078e31SDaniel Almeida 00000010: c668 cb28 e775 b4ac f53a ba60 f8fd 3aa1 .h.(.u...:.`..:. 151*0c078e31SDaniel Almeida 00000020: 46b4 bcfc 506c e227 2372 e5f5 d7ea 579f F...Pl.'#r....W. 152*0c078e31SDaniel Almeida 00000030: 6371 5eb5 0eb8 23b5 ca6a 5de5 983a 19e4 cq^...#..j]..:.. 153*0c078e31SDaniel Almeida 00000040: e8c3 4320 b4ba a226 cbc1 4138 3a12 32d6 ..C ...&..A8:.2. 154*0c078e31SDaniel Almeida 00000050: fef3 247b 3523 4e90 9682 ac8e eb0c a389 ..${5#N......... 155*0c078e31SDaniel Almeida 00000060: ddd0 6cfc 0187 0e20 7aae b15b 1812 3d33 ..l.... z..[..=3 156*0c078e31SDaniel Almeida 00000070: e1c5 f425 a83a 00b7 4f18 8127 3c4c aefb ...%.:..O..'<L.. 157*0c078e31SDaniel Almeida 158*0c078e31SDaniel AlmeidaFor the buffer with sequence == 1: 159*0c078e31SDaniel Almeida 160*0c078e31SDaniel Almeida.. code-block:: bash 161*0c078e31SDaniel Almeida 162*0c078e31SDaniel Almeida $ xxd /sys/kernel/debug/visl/bitstream/bitstream1 163*0c078e31SDaniel Almeida 00000000: 0201 d021 49e1 0c40 aa11 1449 14a6 01dc ...!I..@...I.... 164*0c078e31SDaniel Almeida 00000010: 7023 889a c8cd 2cd0 13b4 dab0 e8ca 21fe p#....,.......!. 165*0c078e31SDaniel Almeida 00000020: c4c8 ab4c 486e 4e2f b0df 96cc c74e 8dde ...LHnN/.....N.. 166*0c078e31SDaniel Almeida 00000030: 8ce7 ee36 d880 4095 4d64 30a0 ff4f 0c5e ...6..@.Md0..O.^ 167*0c078e31SDaniel Almeida 00000040: f16b a6a1 d806 ca2a 0ece a673 7bea 1f37 .k.....*...s{..7 168*0c078e31SDaniel Almeida 00000050: 370f 5bb9 1dc4 ba21 6434 bc53 0173 cba0 7.[....!d4.S.s.. 169*0c078e31SDaniel Almeida 00000060: dfe6 bc99 01ea b6e0 346b 92b5 c8de 9f5d ........4k.....] 170*0c078e31SDaniel Almeida 00000070: e7cc 3484 1769 fef2 a693 a945 2c8b 31da ..4..i.....E,.1. 171*0c078e31SDaniel Almeida 172*0c078e31SDaniel AlmeidaAnd so on. 173*0c078e31SDaniel Almeida 174*0c078e31SDaniel AlmeidaBy default, the files are removed during STREAMOFF. This is to reduce the amount 175*0c078e31SDaniel Almeidaof clutter. 176