Re: [PATCH v2 1/3] docs: sound: add 'pcmtest' driver documentation

[Ivan Orlov <ivan.orlov0322@gmail.com>]

On 5/22/23 17:01, Bagas Sanjaya wrote:
> On Sun, May 21, 2023 at 10:32:16PM +0400, Ivan Orlov wrote:
>> diff --git a/Documentation/sound/cards/pcmtest.rst b/Documentation/sound/cards/pcmtest.rst
>> new file mode 100644
>> index 000000000000..ea8070eaa44e
>> --- /dev/null
>> +++ b/Documentation/sound/cards/pcmtest.rst
>> @@ -0,0 +1,119 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +The Virtual PCM Test Driver
>> +===========================
>> +
>> +The Virtual PCM Test Driver emulates a generic PCM device, and can be used for
>> +testing/fuzzing of the userspace ALSA applications, as well as for testing/fuzzing of
>> +the PCM middle layer. Additionally, it can be used for simulating hard to reproduce
>> +problems with PCM devices.
>> +
>> +What can this driver do?
>> +~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +At this moment the driver can do the following things:
>> +	* Simulate both capture and playback processes
>> +	* Generate random or pattern-based capturing data
>> +	* Inject delays into the playback and capturing processes
>> +	* Inject errors during the PCM callbacks
>> +
>> +It supports up to 8 substreams and 4 channels. Also it supports both interleaved and
>> +non-interleaved access modes.
>> +
>> +Also, this driver can check the playback stream for containing the predefined pattern,
>> +which is used in the corresponding selftest (alsa/test-pcmtest-driver.c). To check the
>> +PCM middle layer data transferring functionality. Additionally, this driver redefines
> "... corresponding selftest ... to check the ..."
>> +the default RESET ioctl, and the selftest covers this PCM API functionality as well.
>> +
>> +Configuration
>> +-------------
>> +
>> +The driver has several parameters besides the common ALSA module parameters:
>> +
>> +	* fill_mode (bool) - Buffer fill mode (see below)
>> +	* inject_delay (int)
>> +	* inject_hwpars_err (bool)
>> +	* inject_prepare_err (bool)
>> +	* inject_trigger_err (bool)
>> +
>> +
>> +Capture Data Generation
>> +-----------------------
>> +
>> +The driver has two modes of data generation: the first (0 in the fill_mode parameter)
>> +means random data generation, the second (1 in the fill_mode) - pattern-based
>> +data generation. Let's look at the second mode.
>> +
>> +First of all, you may want to specify the pattern for data generation. You can do it
>> +by writing the pattern to the debugfs file (/sys/kernel/debug/pcmtest/fill_pattern).
>> +Like that:
> "For example::"
>> +
>> +.. code-block:: bash
>> +
>> +	echo -n mycoolpattern > /sys/kernel/debug/pcmtest/fill_pattern
>> +
>> +After this, every capture action performed on the 'pcmtest' device will return
>> +'mycoolpatternmycoolpatternmycoolpatternmy...' for every channel buffer.
>> +
>> +In case of interleaved access, the capture buffer will contain the repeated pattern
>> +for every channel. Otherwise, every channel buffer will contain the repeated pattern.
>> +
>> +The pattern itself can be up to 4096 bytes long.
>> +
>> +Delay injection
>> +---------------
>> +
>> +The driver has 'inject_delay' parameter, which has very self-descriptive name and
>> +can be used for time delay/speedup simulations. The parameter has integer type, and
>> +it means the delay added between module's internal timer ticks.
>> +
>> +If the 'inject_delay' value is positive, the buffer will be filled slower, if it is
>> +negative - faster. You can try it yourself by starting a recording in any
>> +audio recording application (like Audacity) and selecting the 'pcmtest' device as a
>> +source.
>> +
>> +This parameter can be also used for generating a huge amount of sound data in a very
>> +short period of time (with the negative 'inject_delay' value).
>> +
>> +Errors injection
>> +----------------
>> +
>> +This module can be used for injecting errors into the PCM communication process. This
>> +action can help you to figure out how the userspace ALSA program behaves under unusual
>> +circumstances.
>> +
>> +For example, you can make all 'hw_params' PCM callback calls return EBUSY error by
>> +writing '1' to the 'inject_hwpars_err' module parameter:
>> +
>> +.. code-block:: bash
>> +
>> +	echo 1 > /sys/module/snd_pcmtest/parameters/inject_hwpars_err
>> +
>> +Errors can be injected into the following PCM callbacks:
>> +
>> +	* hw_params (EBUSY)
>> +	* prepare (EINVAL)
>> +	* trigger (EINVAL)
>> +
>> +
>> +Playback test
>> +-------------
>> +
>> +This driver can be also used for the playback functionality testing - every time you
>> +write the playback data to the 'pcmtest' PCM device and close it, the driver checks the
>> +buffer of each channel for containing the looped pattern (which is specified in the
>> +fill_pattern debugfs file). If the playback buffer content represents the looped pattern,
>> +'pc_test' debugfs entry is set into '1'. Otherwise, the driver sets it to '0'.
>> +
>> +ioctl redefinition test
>> +-----------------------
>> +
>> +The driver redefines the 'reset' ioctl, which is default for all PCM devices. To test
>> +this functionality, we can trigger the reset ioctl and check the 'ioctl_test' debugfs
>> +entry:
>> +
>> +.. code-block:: bash
>> +
>> +	cat /sys/kernel/debug/pcmtest/ioctl_test
>> +
>> +If the ioctl is triggered successfully, this file will contain '1', and '0' otherwise.
> 
> The rest is LGTM, thanks!
> 

Hi Bagas!

Thank you for the review! I'll fix this in the next version of the patch 
set after getting response from the sound maintainers - probably it 
isn't the only part which needs to be fixed :)

Kind regards,
Ivan Orlov.