Documentation/admin-guide/media/visl.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/media/visl.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/media/visl.rst
Extension
.rst
Size
7203 bytes
Lines
186
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

The Virtual Stateless Decoder Driver (visl)
===========================================

A virtual stateless decoder device for stateless uAPI development
purposes.

This tool's objective is to help the development and testing of
userspace applications that use the V4L2 stateless API to decode media.

A userspace implementation can use visl to run a decoding loop even when
no hardware is available or when the kernel uAPI for the codec has not
been upstreamed yet. This can reveal bugs at an early stage.

This driver can also trace the contents of the V4L2 controls submitted
to it.  It can also dump the contents of the vb2 buffers through a
debugfs interface. This is in many ways similar to the tracing
infrastructure available for other popular encode/decode APIs out there
and can help develop a userspace application by using another (working)
one as a reference.

.. note::

        No actual decoding of video frames is performed by visl. The
        V4L2 test pattern generator is used to write various debug information
        to the capture buffers instead.

Module parameters
-----------------

- visl_debug: Activates debug info, printing various debug messages through
  dprintk. Also controls whether per-frame debug info is shown. Defaults to off.
  Note that enabling this feature can result in slow performance through serial.

- visl_transtime_ms: Simulated process time in milliseconds. Slowing down the
  decoding speed can be useful for debugging.

- visl_dprintk_frame_start, visl_dprintk_frame_nframes: Dictates a range of
  frames where dprintk is activated. This only controls the dprintk tracing on a
  per-frame basis. Note that printing a lot of data can be slow through serial.

- keep_bitstream_buffers: Controls whether bitstream (i.e. OUTPUT) buffers are
  kept after a decoding session. Defaults to false so as to reduce the amount of
  clutter. keep_bitstream_buffers == false works well when live debugging the
  client program with GDB.

- bitstream_trace_frame_start, bitstream_trace_nframes: Similar to
  visl_dprintk_frame_start, visl_dprintk_nframes, but controls the dumping of
  buffer data through debugfs instead.

- tpg_verbose: Write extra information on each output frame to ease debugging
  the API. When set to true, the output frames are not stable for a given input
  as some information like pointers or queue status will be added to them.

What is the default use case for this driver?
---------------------------------------------

This driver can be used as a way to compare different userspace implementations.
This assumes that a working client is run against visl and that the ftrace and
OUTPUT buffer data is subsequently used to debug a work-in-progress
implementation.

Even though no video decoding is actually done, the output frames can be used
against a reference for a given input, except if tpg_verbose is set to true.

Depending on the tpg_verbose parameter value, information on reference frames,
their timestamps, the status of the OUTPUT and CAPTURE queues and more can be
read directly from the CAPTURE buffers.

Annotation

Implementation Notes