[LTP] [PATCH] doc: add kvm tests documentation

[Petr Vorel]

Hi Andrea,

> Converted KVM Tests API documentation into RST format and fixed
> grammatical errors in the text.

Thanks for doing this!
I'm ok if you ignore moving to header (it should be done, but it can be done
later).

Reviewed-by: Petr Vorel <pvorel@suse.cz>

...
> +Basic KVM Test Structure
> +------------------------
> +
> +KVM tests are simple C source files containing both the KVM controller code
> +and the guest payload code separated by ``#ifdef COMPILE_PAYLOAD`` preprocessor
> +condition. The file will be compiled twice: once to compile the payload part,
> +and once to compile the KVM controller part and embed the payload binary inside.
> +The result is a single self-contained binary that will execute the embedded
> +payload inside a KVM virtual machine and print results in the same format as
> +a normal LTP test.
> +
> +A KVM test source should start with ``#include "kvm_test.h"`` instead of the
> +usual ``tst_test.h``. The ``kvm_test.h`` header file will include the other basic
nit: I would prefer if headers could be clickable links, as it's done in
developers/test_case_tutorial.rst (i.e. consistency + allow reader to quickly
see the source). E.g.:

usual :master:`include/tst_test.h`. The :master:`include/kvm_test.h` header file
will include the other basic ...

But I can do this and the other later (no need to send v2.

> +headers appropriate for the current compilation pass. Everything else in the
> +source file should be enclosed in ``#ifdef COMPILE_PAYLOAD ... #else ... #endif``
> +condition, including any other header file includes. Note that the standard
> +LTP headers are not available in the payload compilation pass; only the KVM
> +guest library headers can be included.
> +
> +.. _example-kvm-test:
> +
> +.. rubric:: Example KVM Test
> +
> +.. code-block:: c
> +
> +    #include "kvm_test.h"
> +
> +    #ifdef COMPILE_PAYLOAD
> +
> +    /* Guest payload code */
> +
> +    void main(void)
> +    {
> +    	tst_res(TPASS, "Hello, world!");
Here you started using tabs.
Could you convert it to spaces before merge?
(Mixing tabs and spaces on places where they are used for syntax formatting will
lead sooner or later to broken output.)

> +    }
> +
> +    #else /* COMPILE_PAYLOAD */
> +
> +    /* KVM controller code */
> +
> +    static struct tst_test test = {
> +    	.test_all = tst_kvm_run,
> +    	.setup = tst_kvm_setup,
> +    	.cleanup = tst_kvm_cleanup,
And these 3 lines as well.

> +    };
> +
> +    #endif /* COMPILE_PAYLOAD */
> +
> +The KVM controller code is a normal LTP test and needs to define an instance
> +of ``struct tst_test`` with metadata and the usual setup, cleanup, and test
Please could you use ref syntax for all structs? i.e.
:ref:`struct tst_test`

This way it's clickable and consistent with other parts of the docs.
It can be done before merge.

> +functions. Basic implementation of all three functions is provided by the KVM
> +host library.
> +
> +On the other hand, the payload is essentially a tiny kernel that will run
> +on bare virtual hardware. It cannot access any files, Linux syscalls, standard
> +library functions, etc., except for the small subset provided by the KVM guest
> +library. The payload code must define a ``void main(void)`` function which will
> +be the VM entry point of the test.
> +
> +KVM Host Library
> +----------------
> +
> +The KVM host library provides helper functions for creating and running
> +a minimal KVM virtual machine.
> +
> +Data Structures
> +~~~~~~~~~~~~~~~
> +
> +.. code-block:: c
> +
> +    struct tst_kvm_instance {
Well, this should be now in testcases/kernel/kvm/include/kvm_host.h.
Would it be too much work to add kernel doc to it and include it in docs?
Doing it properly would help with struct being clickable from other places.
It applies to the rest of the document.

> +    	int vm_fd, vcpu_fd;
> +    	struct kvm_run *vcpu_info;
> +    	size_t vcpu_info_size;
> +    	struct kvm_userspace_memory_region ram[MAX_KVM_MEMSLOTS];
> +    	struct tst_kvm_result *result;
Here also tabs => spaces (in case you keep the docs here).

> +    };
> +
> +``struct tst_kvm_instance`` holds the file descriptors and memory buffers
> +of a single KVM virtual machine:
> +
> +* ``int vm_fd`` is the main VM file descriptor created by ``ioctl(KVM_CREATE_VM)``
> +* ``int vcpu_fd`` is the virtual CPU file descriptor created by
> +  ``ioctl(KVM_CREATE_VCPU)``
> +* ``struct kvm_run *vcpu_info`` is the VCPU state structure created by
> +  ``mmap(vcpu_fd)``
> +* ``size_t vcpu_info_size`` is the size of ``vcpu_info`` buffer
> +* ``struct kvm_userspace_memory_region ram[MAX_KVM_MEMSLOTS]`` is the list
> +  of memory slots defined in this VM. Unused memory slots have zero
> +  in the ``userspace_addr`` field.
> +* ``struct tst_kvm_result *result`` is a buffer for passing test result data
> +  from the VM to the controller program, mainly ``tst_res()``/``tst_brk()`` flags
> +  and messages.
This explanation should be really in the header.

> +
> +.. code-block:: c
> +
> +    struct tst_kvm_result {
> +    	int32_t result;
> +    	int32_t lineno;
> +    	uint64_t file_addr;
> +    	char message[0];
Here also tabs => spaces (in case you keep the docs here).

Kind regards,
Petr