Documentation/admin-guide/media/visl.rst

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