| Message ID | 20200116212054.4041-1-wainersm@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [kvm-unit-tests] README: fix markdown formatting and general improvements | expand |
On Thu, Jan 16, 2020 at 06:20:54PM -0300, Wainer dos Santos Moschetta wrote: > There are some formatting fixes on this change: > - Some blocks weren't indented correctly; > - Some statements needed escape. > > Also the text is improved in some ways: > - Variables and options are bold now; > - Files path are set to italic; I'd rather not do that. All the *'s and \'s make reading more difficult. > - Inline commands are marked; > - Added a section about the tests configuration file. Adding new content should be done as a separate patch. Thanks for the cleanups, but I think we can keep the markup minimal and still format the content neatly. drew > > Signed-off-by: Wainer dos Santos Moschetta <wainersm@redhat.com> > --- > See the results here: https://github.com/wainersm/kvm-unit-tests/tree/docs > > README.md | 100 ++++++++++++++++++++++++++++++------------------------ > 1 file changed, 55 insertions(+), 45 deletions(-) > > diff --git a/README.md b/README.md > index 1a9a4ab..07c5a82 100644 > --- a/README.md > +++ b/README.md > @@ -13,12 +13,11 @@ To create the test images do: > ./configure > make > > -in this directory. Test images are created in ./<ARCH>/*.flat > +in this directory. Test images are created in *./\<ARCH\>/\*.flat* > > ## Standalone tests > > -The tests can be built as standalone > -To create and use standalone tests do: > +The tests can be built as standalone. To create and use standalone tests do: > > ./configure > make standalone > @@ -26,8 +25,8 @@ To create and use standalone tests do: > (go to somewhere) > ./some-test > > -'make install' will install all tests in PREFIX/share/kvm-unit-tests/tests, > -each as a standalone test. > +They are created in *./tests*. Or run `make install` to install all tests in > +*PREFIX/share/kvm-unit-tests/tests*, each as a standalone test. > > > # Running the tests > @@ -42,85 +41,96 @@ or: > > to run them all. > > -To select a specific qemu binary, specify the QEMU=<path> > +By default the runner script searches for a suitable qemu binary in the system. > +To select a specific qemu binary though, specify the **QEMU=\<path\>** > environment variable: > > QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat > > To select an accelerator, for example "kvm" or "tcg", specify the > -ACCEL=<name> environment variable: > +**ACCEL=\<name\>** environment variable: > > ACCEL=kvm ./x86-run ./x86/msr.flat > > -# Unit test inputs > +# Tests suite configuration > > -Unit tests use QEMU's '-append <args...>' parameter for command line > -inputs, i.e. all args will be available as argv strings in main(). > -Additionally a file of the form > +Given that each test case may need specific runtime configurations as, for > +example, extra QEMU parameters and limited time to execute, the > +runner script reads those information from a configuration file found > +at *./\<ARCH\>/unittests.cfg*. This file also contain the group of tests which > +can be ran with the script's **-g** option. > + > +## Unit test inputs > > -KEY=VAL > -KEY2=VAL > -... > +Unit tests use QEMU's **-append \<args...\>** parameter for command line > +inputs, i.e. all args will be available as *argv* strings in *main()*. > +Additionally a file of the form > > -may be passed with '-initrd <file>' to become the unit test's environ, > -which can then be accessed in the usual ways, e.g. VAL = getenv("KEY") > -Any key=val strings can be passed, but some have reserved meanings in > -the framework. The list of reserved environment variables is below > + KEY=VAL > + KEY2=VAL > + ... > > - QEMU_ACCEL ... either kvm or tcg > - QEMU_VERSION_STRING ... string of the form `qemu -h | head -1` > - KERNEL_VERSION_STRING ... string of the form `uname -r` > +may be passed with **-initrd \<file\>** to become the unit test's environ, > +which can then be accessed in the usual ways, e.g. `VAL = getenv("KEY")`. > + Any *key=val* strings can be passed, but some have reserved meanings in > +the framework. The list of reserved environment variables is: > > -Additionally these self-explanatory variables are reserved > + QEMU_ACCEL either kvm or tcg > + QEMU_VERSION_STRING string of the form `qemu -h | head -1` > + KERNEL_VERSION_STRING string of the form `uname -r` > > - QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL, > - KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION > +Additionally these self-explanatory variables are reserved: *QEMU\_MAJOR*, *QEMU\_MINOR*, *QEMU\_MICRO*, *KERNEL\_VERSION*, *KERNEL\_PATCHLEVEL*, *KERNEL\_SUBLEVEL*, *KERNEL\_EXTRAVERSION*. > > # Guarding unsafe tests > > Some tests are not safe to run by default, as they may crash the > host. kvm-unit-tests provides two ways to handle tests like those. > > - 1) Adding 'nodefault' to the groups field for the unit test in the > - unittests.cfg file. When a unit test is in the nodefault group > + 1) Adding **nodefault** to the groups field for the unit test in the > + *unittests.cfg* file. When a unit test is in the *nodefault* group > it is only run when invoked > > - a) independently, arch-run arch/test > - b) by specifying any other non-nodefault group it is in, > - groups = nodefault,mygroup : ./run_tests.sh -g mygroup > - c) by specifying all tests should be run, ./run_tests.sh -a > + a. independently, `<ARCH>-run <ARCH>/<TEST>.flat` > + > + b. by specifying any other non-nodefault group it is in, > + *groups = nodefault,mygroup* : `./run_tests.sh -g mygroup` > + > + c. by specifying all tests should be run, `./run_tests.sh -a` > > 2) Making the test conditional on errata in the code, > + ``` > if (ERRATA(abcdef012345)) { > do_unsafe_test(); > } > - > + ``` > With the errata condition the unsafe unit test is only run > when > > - a) the ERRATA_abcdef012345 environ variable is provided and 'y' > - b) the ERRATA_FORCE environ variable is provided and 'y' > - c) by specifying all tests should be run, ./run_tests.sh -a > - (The -a switch ensures the ERRATA_FORCE is provided and set > + a) the *ERRATA\_abcdef012345* environment variable is provided and 'y' > + > + b) the **ERRATA_FORCE** environment variable is provided and 'y' > + > + c) by specifying all tests should be run, `./run_tests.sh -a` > + (The **-a** switch ensures the **ERRATA_FORCE** is provided and set > to 'y'.) > > -The errata.txt file provides a mapping of the commits needed by errata > +The *./errata.txt* file provides a mapping of the commits needed by errata > conditionals to their respective minimum kernel versions. By default, > when the user does not provide an environ, then an environ generated > -from the errata.txt file and the host's kernel version is provided to > +from the *./errata.txt* file and the host's kernel version is provided to > all unit tests. > > # Contributing > > ## Directory structure > > - .: configure script, top-level Makefile, and run_tests.sh > - ./scripts: helper scripts for building and running tests > - ./lib: general architecture neutral services for the tests > - ./lib/<ARCH>: architecture dependent services for the tests > - ./<ARCH>: the sources of the tests and the created objects/images > + .: configure script, top-level Makefile, and run_tests.sh > + ./scripts: helper scripts for building and running tests > + ./lib: general architecture neutral services for the tests > + ./lib/<ARCH>: architecture dependent services for the tests > + ./<ARCH>: the sources of the tests and the created objects/images > > -See <ARCH>/README for architecture specific documentation. > +See *./\<ARCH\>/README* for architecture specific documentation. > > ## Style > > @@ -129,7 +139,7 @@ existing files should be consistent with the existing style. For new > files: > > - C: please use standard linux-with-tabs, see Linux kernel > - doc Documentation/process/coding-style.rst > + doc *Documentation/process/coding-style.rst* > - Shell: use TABs for indentation > > Exceptions: > @@ -142,7 +152,7 @@ Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>. > > Please prefix messages with: [kvm-unit-tests PATCH] > > -You can add the following to .git/config to do this automatically for you: > +You can add the following to *.git/config* to do this automatically for you: > > [format] > subjectprefix = kvm-unit-tests PATCH > -- > 2.23.0 >
On 1/17/20 11:10 AM, Andrew Jones wrote: > On Thu, Jan 16, 2020 at 06:20:54PM -0300, Wainer dos Santos Moschetta wrote: >> There are some formatting fixes on this change: >> - Some blocks weren't indented correctly; >> - Some statements needed escape. >> >> Also the text is improved in some ways: >> - Variables and options are bold now; >> - Files path are set to italic; > I'd rather not do that. All the *'s and \'s make reading more difficult. I made those changes thinking on the developer reading the doc in a browser. Indeed, on cmd line it would not be a nice experience. > >> - Inline commands are marked; >> - Added a section about the tests configuration file. > Adding new content should be done as a separate patch. I will send as separate patch in v2. > > Thanks for the cleanups, but I think we can keep the markup minimal and > still format the content neatly. Yeah, agree. On v2 I will try to keep markup minimal. Thanks for the nice review. - Wainer > > drew > >> Signed-off-by: Wainer dos Santos Moschetta <wainersm@redhat.com> >> --- >> See the results here: https://github.com/wainersm/kvm-unit-tests/tree/docs >> >> README.md | 100 ++++++++++++++++++++++++++++++------------------------ >> 1 file changed, 55 insertions(+), 45 deletions(-) >> >> diff --git a/README.md b/README.md >> index 1a9a4ab..07c5a82 100644 >> --- a/README.md >> +++ b/README.md >> @@ -13,12 +13,11 @@ To create the test images do: >> ./configure >> make >> >> -in this directory. Test images are created in ./<ARCH>/*.flat >> +in this directory. Test images are created in *./\<ARCH\>/\*.flat* >> >> ## Standalone tests >> >> -The tests can be built as standalone >> -To create and use standalone tests do: >> +The tests can be built as standalone. To create and use standalone tests do: >> >> ./configure >> make standalone >> @@ -26,8 +25,8 @@ To create and use standalone tests do: >> (go to somewhere) >> ./some-test >> >> -'make install' will install all tests in PREFIX/share/kvm-unit-tests/tests, >> -each as a standalone test. >> +They are created in *./tests*. Or run `make install` to install all tests in >> +*PREFIX/share/kvm-unit-tests/tests*, each as a standalone test. >> >> >> # Running the tests >> @@ -42,85 +41,96 @@ or: >> >> to run them all. >> >> -To select a specific qemu binary, specify the QEMU=<path> >> +By default the runner script searches for a suitable qemu binary in the system. >> +To select a specific qemu binary though, specify the **QEMU=\<path\>** >> environment variable: >> >> QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat >> >> To select an accelerator, for example "kvm" or "tcg", specify the >> -ACCEL=<name> environment variable: >> +**ACCEL=\<name\>** environment variable: >> >> ACCEL=kvm ./x86-run ./x86/msr.flat >> >> -# Unit test inputs >> +# Tests suite configuration >> >> -Unit tests use QEMU's '-append <args...>' parameter for command line >> -inputs, i.e. all args will be available as argv strings in main(). >> -Additionally a file of the form >> +Given that each test case may need specific runtime configurations as, for >> +example, extra QEMU parameters and limited time to execute, the >> +runner script reads those information from a configuration file found >> +at *./\<ARCH\>/unittests.cfg*. This file also contain the group of tests which >> +can be ran with the script's **-g** option. >> + >> +## Unit test inputs >> >> -KEY=VAL >> -KEY2=VAL >> -... >> +Unit tests use QEMU's **-append \<args...\>** parameter for command line >> +inputs, i.e. all args will be available as *argv* strings in *main()*. >> +Additionally a file of the form >> >> -may be passed with '-initrd <file>' to become the unit test's environ, >> -which can then be accessed in the usual ways, e.g. VAL = getenv("KEY") >> -Any key=val strings can be passed, but some have reserved meanings in >> -the framework. The list of reserved environment variables is below >> + KEY=VAL >> + KEY2=VAL >> + ... >> >> - QEMU_ACCEL ... either kvm or tcg >> - QEMU_VERSION_STRING ... string of the form `qemu -h | head -1` >> - KERNEL_VERSION_STRING ... string of the form `uname -r` >> +may be passed with **-initrd \<file\>** to become the unit test's environ, >> +which can then be accessed in the usual ways, e.g. `VAL = getenv("KEY")`. >> + Any *key=val* strings can be passed, but some have reserved meanings in >> +the framework. The list of reserved environment variables is: >> >> -Additionally these self-explanatory variables are reserved >> + QEMU_ACCEL either kvm or tcg >> + QEMU_VERSION_STRING string of the form `qemu -h | head -1` >> + KERNEL_VERSION_STRING string of the form `uname -r` >> >> - QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL, >> - KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION >> +Additionally these self-explanatory variables are reserved: *QEMU\_MAJOR*, *QEMU\_MINOR*, *QEMU\_MICRO*, *KERNEL\_VERSION*, *KERNEL\_PATCHLEVEL*, *KERNEL\_SUBLEVEL*, *KERNEL\_EXTRAVERSION*. >> >> # Guarding unsafe tests >> >> Some tests are not safe to run by default, as they may crash the >> host. kvm-unit-tests provides two ways to handle tests like those. >> >> - 1) Adding 'nodefault' to the groups field for the unit test in the >> - unittests.cfg file. When a unit test is in the nodefault group >> + 1) Adding **nodefault** to the groups field for the unit test in the >> + *unittests.cfg* file. When a unit test is in the *nodefault* group >> it is only run when invoked >> >> - a) independently, arch-run arch/test >> - b) by specifying any other non-nodefault group it is in, >> - groups = nodefault,mygroup : ./run_tests.sh -g mygroup >> - c) by specifying all tests should be run, ./run_tests.sh -a >> + a. independently, `<ARCH>-run <ARCH>/<TEST>.flat` >> + >> + b. by specifying any other non-nodefault group it is in, >> + *groups = nodefault,mygroup* : `./run_tests.sh -g mygroup` >> + >> + c. by specifying all tests should be run, `./run_tests.sh -a` >> >> 2) Making the test conditional on errata in the code, >> + ``` >> if (ERRATA(abcdef012345)) { >> do_unsafe_test(); >> } >> - >> + ``` >> With the errata condition the unsafe unit test is only run >> when >> >> - a) the ERRATA_abcdef012345 environ variable is provided and 'y' >> - b) the ERRATA_FORCE environ variable is provided and 'y' >> - c) by specifying all tests should be run, ./run_tests.sh -a >> - (The -a switch ensures the ERRATA_FORCE is provided and set >> + a) the *ERRATA\_abcdef012345* environment variable is provided and 'y' >> + >> + b) the **ERRATA_FORCE** environment variable is provided and 'y' >> + >> + c) by specifying all tests should be run, `./run_tests.sh -a` >> + (The **-a** switch ensures the **ERRATA_FORCE** is provided and set >> to 'y'.) >> >> -The errata.txt file provides a mapping of the commits needed by errata >> +The *./errata.txt* file provides a mapping of the commits needed by errata >> conditionals to their respective minimum kernel versions. By default, >> when the user does not provide an environ, then an environ generated >> -from the errata.txt file and the host's kernel version is provided to >> +from the *./errata.txt* file and the host's kernel version is provided to >> all unit tests. >> >> # Contributing >> >> ## Directory structure >> >> - .: configure script, top-level Makefile, and run_tests.sh >> - ./scripts: helper scripts for building and running tests >> - ./lib: general architecture neutral services for the tests >> - ./lib/<ARCH>: architecture dependent services for the tests >> - ./<ARCH>: the sources of the tests and the created objects/images >> + .: configure script, top-level Makefile, and run_tests.sh >> + ./scripts: helper scripts for building and running tests >> + ./lib: general architecture neutral services for the tests >> + ./lib/<ARCH>: architecture dependent services for the tests >> + ./<ARCH>: the sources of the tests and the created objects/images >> >> -See <ARCH>/README for architecture specific documentation. >> +See *./\<ARCH\>/README* for architecture specific documentation. >> >> ## Style >> >> @@ -129,7 +139,7 @@ existing files should be consistent with the existing style. For new >> files: >> >> - C: please use standard linux-with-tabs, see Linux kernel >> - doc Documentation/process/coding-style.rst >> + doc *Documentation/process/coding-style.rst* >> - Shell: use TABs for indentation >> >> Exceptions: >> @@ -142,7 +152,7 @@ Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>. >> >> Please prefix messages with: [kvm-unit-tests PATCH] >> >> -You can add the following to .git/config to do this automatically for you: >> +You can add the following to *.git/config* to do this automatically for you: >> >> [format] >> subjectprefix = kvm-unit-tests PATCH >> -- >> 2.23.0 >>
diff --git a/README.md b/README.md index 1a9a4ab..07c5a82 100644 --- a/README.md +++ b/README.md @@ -13,12 +13,11 @@ To create the test images do: ./configure make -in this directory. Test images are created in ./<ARCH>/*.flat +in this directory. Test images are created in *./\<ARCH\>/\*.flat* ## Standalone tests -The tests can be built as standalone -To create and use standalone tests do: +The tests can be built as standalone. To create and use standalone tests do: ./configure make standalone @@ -26,8 +25,8 @@ To create and use standalone tests do: (go to somewhere) ./some-test -'make install' will install all tests in PREFIX/share/kvm-unit-tests/tests, -each as a standalone test. +They are created in *./tests*. Or run `make install` to install all tests in +*PREFIX/share/kvm-unit-tests/tests*, each as a standalone test. # Running the tests @@ -42,85 +41,96 @@ or: to run them all. -To select a specific qemu binary, specify the QEMU=<path> +By default the runner script searches for a suitable qemu binary in the system. +To select a specific qemu binary though, specify the **QEMU=\<path\>** environment variable: QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat To select an accelerator, for example "kvm" or "tcg", specify the -ACCEL=<name> environment variable: +**ACCEL=\<name\>** environment variable: ACCEL=kvm ./x86-run ./x86/msr.flat -# Unit test inputs +# Tests suite configuration -Unit tests use QEMU's '-append <args...>' parameter for command line -inputs, i.e. all args will be available as argv strings in main(). -Additionally a file of the form +Given that each test case may need specific runtime configurations as, for +example, extra QEMU parameters and limited time to execute, the +runner script reads those information from a configuration file found +at *./\<ARCH\>/unittests.cfg*. This file also contain the group of tests which +can be ran with the script's **-g** option. + +## Unit test inputs -KEY=VAL -KEY2=VAL -... +Unit tests use QEMU's **-append \<args...\>** parameter for command line +inputs, i.e. all args will be available as *argv* strings in *main()*. +Additionally a file of the form -may be passed with '-initrd <file>' to become the unit test's environ, -which can then be accessed in the usual ways, e.g. VAL = getenv("KEY") -Any key=val strings can be passed, but some have reserved meanings in -the framework. The list of reserved environment variables is below + KEY=VAL + KEY2=VAL + ... - QEMU_ACCEL ... either kvm or tcg - QEMU_VERSION_STRING ... string of the form `qemu -h | head -1` - KERNEL_VERSION_STRING ... string of the form `uname -r` +may be passed with **-initrd \<file\>** to become the unit test's environ, +which can then be accessed in the usual ways, e.g. `VAL = getenv("KEY")`. + Any *key=val* strings can be passed, but some have reserved meanings in +the framework. The list of reserved environment variables is: -Additionally these self-explanatory variables are reserved + QEMU_ACCEL either kvm or tcg + QEMU_VERSION_STRING string of the form `qemu -h | head -1` + KERNEL_VERSION_STRING string of the form `uname -r` - QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL, - KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION +Additionally these self-explanatory variables are reserved: *QEMU\_MAJOR*, *QEMU\_MINOR*, *QEMU\_MICRO*, *KERNEL\_VERSION*, *KERNEL\_PATCHLEVEL*, *KERNEL\_SUBLEVEL*, *KERNEL\_EXTRAVERSION*. # Guarding unsafe tests Some tests are not safe to run by default, as they may crash the host. kvm-unit-tests provides two ways to handle tests like those. - 1) Adding 'nodefault' to the groups field for the unit test in the - unittests.cfg file. When a unit test is in the nodefault group + 1) Adding **nodefault** to the groups field for the unit test in the + *unittests.cfg* file. When a unit test is in the *nodefault* group it is only run when invoked - a) independently, arch-run arch/test - b) by specifying any other non-nodefault group it is in, - groups = nodefault,mygroup : ./run_tests.sh -g mygroup - c) by specifying all tests should be run, ./run_tests.sh -a + a. independently, `<ARCH>-run <ARCH>/<TEST>.flat` + + b. by specifying any other non-nodefault group it is in, + *groups = nodefault,mygroup* : `./run_tests.sh -g mygroup` + + c. by specifying all tests should be run, `./run_tests.sh -a` 2) Making the test conditional on errata in the code, + ``` if (ERRATA(abcdef012345)) { do_unsafe_test(); } - + ``` With the errata condition the unsafe unit test is only run when - a) the ERRATA_abcdef012345 environ variable is provided and 'y' - b) the ERRATA_FORCE environ variable is provided and 'y' - c) by specifying all tests should be run, ./run_tests.sh -a - (The -a switch ensures the ERRATA_FORCE is provided and set + a) the *ERRATA\_abcdef012345* environment variable is provided and 'y' + + b) the **ERRATA_FORCE** environment variable is provided and 'y' + + c) by specifying all tests should be run, `./run_tests.sh -a` + (The **-a** switch ensures the **ERRATA_FORCE** is provided and set to 'y'.) -The errata.txt file provides a mapping of the commits needed by errata +The *./errata.txt* file provides a mapping of the commits needed by errata conditionals to their respective minimum kernel versions. By default, when the user does not provide an environ, then an environ generated -from the errata.txt file and the host's kernel version is provided to +from the *./errata.txt* file and the host's kernel version is provided to all unit tests. # Contributing ## Directory structure - .: configure script, top-level Makefile, and run_tests.sh - ./scripts: helper scripts for building and running tests - ./lib: general architecture neutral services for the tests - ./lib/<ARCH>: architecture dependent services for the tests - ./<ARCH>: the sources of the tests and the created objects/images + .: configure script, top-level Makefile, and run_tests.sh + ./scripts: helper scripts for building and running tests + ./lib: general architecture neutral services for the tests + ./lib/<ARCH>: architecture dependent services for the tests + ./<ARCH>: the sources of the tests and the created objects/images -See <ARCH>/README for architecture specific documentation. +See *./\<ARCH\>/README* for architecture specific documentation. ## Style @@ -129,7 +139,7 @@ existing files should be consistent with the existing style. For new files: - C: please use standard linux-with-tabs, see Linux kernel - doc Documentation/process/coding-style.rst + doc *Documentation/process/coding-style.rst* - Shell: use TABs for indentation Exceptions: @@ -142,7 +152,7 @@ Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>. Please prefix messages with: [kvm-unit-tests PATCH] -You can add the following to .git/config to do this automatically for you: +You can add the following to *.git/config* to do this automatically for you: [format] subjectprefix = kvm-unit-tests PATCH
There are some formatting fixes on this change: - Some blocks weren't indented correctly; - Some statements needed escape. Also the text is improved in some ways: - Variables and options are bold now; - Files path are set to italic; - Inline commands are marked; - Added a section about the tests configuration file. Signed-off-by: Wainer dos Santos Moschetta <wainersm@redhat.com> --- See the results here: https://github.com/wainersm/kvm-unit-tests/tree/docs README.md | 100 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 55 insertions(+), 45 deletions(-)