Re: [PATCH v3 9/9] KVM: selftests: Provide README.rst for KVM selftests runner

[Marc Zyngier <maz@kernel.org>]

On Tue, 30 Sep 2025 17:36:35 +0100,
Vipin Sharma <vipinsh@google.com> wrote:
> 
> Add README.rst for KVM selftest runner and explain how to use the
> runner.
> 
> Signed-off-by: Vipin Sharma <vipinsh@google.com>
> ---
>  tools/testing/selftests/kvm/.gitignore        |  1 +
>  tools/testing/selftests/kvm/runner/README.rst | 54 +++++++++++++++++++
>  2 files changed, 55 insertions(+)
>  create mode 100644 tools/testing/selftests/kvm/runner/README.rst
> 
> diff --git a/tools/testing/selftests/kvm/.gitignore b/tools/testing/selftests/kvm/.gitignore
> index 548d435bde2f..83aa2fe01bac 100644
> --- a/tools/testing/selftests/kvm/.gitignore
> +++ b/tools/testing/selftests/kvm/.gitignore
> @@ -4,6 +4,7 @@
>  !*.c
>  !*.h
>  !*.py
> +!*.rst
>  !*.S
>  !*.sh
>  !*.test
> diff --git a/tools/testing/selftests/kvm/runner/README.rst b/tools/testing/selftests/kvm/runner/README.rst
> new file mode 100644
> index 000000000000..83b071c0a0e6
> --- /dev/null
> +++ b/tools/testing/selftests/kvm/runner/README.rst
> @@ -0,0 +1,54 @@
> +KVM Selftest Runner
> +===================
> +
> +KVM selftest runner is highly configurable test executor that allows to run
> +tests with different configurations (not just the default), parallely, save

s/parallely/in parallel/

> +output to disk hierarchically, control what gets printed on console, provide
> +execution status.
> +
> +To generate default tests use::
> +
> +  # make tests_install
> +
> +This will create ``testcases_default_gen`` directory which will have testcases

I don't think using the future tense is correct here. I'd rather see
something written in the present tense, possibly imperative. For
example:

"Create 'blah' directory containing 'foo' files, one per test-case.

> +in `default.test` files. Each KVM selftest will have a directory in  which
> +`default.test` file will be created with executable path relative to KVM
> +selftest root directory i.e. `/tools/testing/selftests/kvm`.

Shouldn't this honor the existing build output directives? If it
actually does, then you want to call this out.

> For example, the
> +`dirty_log_perf_test` will have::
> +
> +  # cat testcase_default_gen/dirty_log_perf_test/default.test
> +  dirty_log_perf_test
> +
> +Runner will execute `dirty_log_perf_test`. Testcases files can also provide
> +extra arguments to the test::
> +
> +  # cat tests/dirty_log_perf_test/2slot_5vcpu_10iter.test
> +  dirty_log_perf_test -x 2 -v 5 -i 10
> +
> +In this case runner will execute the `dirty_log_perf_test` with the options.
> +

The beginning of the text talks about "non-default' configurations,
but you only seem to talk about the default stuff. How does one deals
with a non-default config?

	M.

-- 
Without deviation from the norm, progress is not possible.