Consolidate unittests.cfg documentation in one place. Suggested-by: Andrew Jones <andrew.jones@xxxxxxxxx> Signed-off-by: Nicholas Piggin <npiggin@xxxxxxxxx> --- arm/unittests.cfg | 26 ++----------- docs/unittests.txt | 89 +++++++++++++++++++++++++++++++++++++++++++ powerpc/unittests.cfg | 25 ++---------- riscv/unittests.cfg | 26 ++----------- s390x/unittests.cfg | 18 ++------- x86/unittests.cfg | 26 ++----------- 6 files changed, 107 insertions(+), 103 deletions(-) create mode 100644 docs/unittests.txt diff --git a/arm/unittests.cfg b/arm/unittests.cfg index fe601cbb1..54cedea28 100644 --- a/arm/unittests.cfg +++ b/arm/unittests.cfg @@ -1,28 +1,10 @@ ############################################################################## # unittest configuration # -# [unittest_name] -# file = <name>.flat # Name of the flat file to be used. -# smp = <num> # Number of processors the VM will use -# # during this test. Use $MAX_SMP to use -# # the maximum the host supports. Defaults -# # to one. -# extra_params = -append <params...> # Additional parameters used. -# arch = arm|arm64 # Select one if the test case is -# # specific to only one. -# groups = <group_name1> <group_name2> ... # Used to identify test cases -# # with run_tests -g ... -# # Specify group_name=nodefault -# # to have test not run by -# # default -# accel = kvm|tcg # Optionally specify if test must run with -# # kvm or tcg. If not specified, then kvm will -# # be used when available. -# timeout = <duration> # Optionally specify a timeout. -# check = <path>=<value> # check a file for a particular value before running -# # a test. The check line can contain multiple files -# # to check separated by a space but each check -# # parameter needs to be of the form <path>=<value> +# arm specifics: +# +# file = <name>.flat # arm uses .flat files +# arch = arm|arm64 ############################################################################## # diff --git a/docs/unittests.txt b/docs/unittests.txt new file mode 100644 index 000000000..53e02077c --- /dev/null +++ b/docs/unittests.txt @@ -0,0 +1,89 @@ +unittests +********* + +run_tests.sh is driven by the <arch>/unittests.cfg file. That file defines +test cases by specifying an executable (target image) under the <arch>/ +directory, and how to run it. This way, for example, a single file can +provide multiple test cases by being run with different host configurations +and/or different parameters passed to it. + +Detailed output from run_tests.sh unit tests are stored in files under +the logs/ directory. + +unittests.cfg format +==================== + +# is the comment symbol, all following contents of the line is ignored. + +Each unit test is defined as with a [unit-test-name] line, followed by +a set of parameters that control how the test case is run. The name is +arbitrary and appears in the status reporting output. + +Parameters appear on their own lines under the test name, and have a +param = value format. + +Available parameters +==================== +Note! Some parameters like smp and extra_params modify how a test is run, +while others like arch and accel restrict the configurations in which the +test is run. + +file +---- +file = <filename> + +This parameter is mandatory and specifies which binary under the <arch>/ +directory to run. Typically this is <name>.flat or <name>.elf, depending +on the arch. The directory name is not included, only the file name. + +arch +---- +For <arch>/ directories that support multiple architectures, this restricts +the test to the specified arch. By default, the test will run on any +architecture. + +smp +--- +smp = <number> + +Optional, the number of processors created in the machine to run the test. +Defaults to 1. $MAX_SMP can be used to specify the maximum supported. + +extra_params +------------ +These are extra parameters supplied to the QEMU process. -append '...' can +be used to pass arguments into the test case argv. Multiple parameters can +be added, for example: + +extra_params = -m 256 -append 'smp=2' + +groups +------ +groups = <group_name1> <group_name2> ... + +Used to group the test cases for the `run_tests.sh -g ...` run group +option. Adding a test to the nodefault group will cause it to not be +run by default. + +accel +----- +accel = kvm|tcg + +This restricts the test to the specified accelerator. By default, the +test will run on either accelerator. (Note, the accelerator can be +specified with ACCEL= environment variable, and defaults to KVM if +available). + +timeout +------- +timeout = <duration> + +Optional timeout in seconds, after which the test will be killed and fail. + +check +----- +check = <path>=<<value> + +Check a file for a particular value before running a test. The check line +can contain multiple files to check separated by a space, but each check +parameter needs to be of the form <path>=<value> diff --git a/powerpc/unittests.cfg b/powerpc/unittests.cfg index e65217c18..432c81d58 100644 --- a/powerpc/unittests.cfg +++ b/powerpc/unittests.cfg @@ -1,28 +1,9 @@ ############################################################################## # unittest configuration # -# [unittest_name] -# file = <name>.flat # Name of the flat file to be used. -# smp = <num> # Number of processors the VM will use -# # during this test. Use $MAX_SMP to use -# # the maximum the host supports. Defaults -# # to one. -# extra_params = -append <params...> # Additional parameters used. -# arch = ppc64 # Select one if the test case is -# # specific to only one. -# groups = <group_name1> <group_name2> ... # Used to identify test cases -# # with run_tests -g ... -# # Specify group_name=nodefault -# # to have test not run by -# # default -# accel = kvm|tcg # Optionally specify if test must run with -# # kvm or tcg. If not specified, then kvm will -# # be used when available. -# timeout = <duration> # Optionally specify a timeout. -# check = <path>=<value> # check a file for a particular value before running -# # a test. The check line can contain multiple files -# # to check separated by a space but each check -# # parameter needs to be of the form <path>=<value> +# powerpc specifics: +# +# file = <name>.elf # powerpc uses .elf files ############################################################################## # diff --git a/riscv/unittests.cfg b/riscv/unittests.cfg index 5a23bed9c..50c67e37f 100644 --- a/riscv/unittests.cfg +++ b/riscv/unittests.cfg @@ -1,28 +1,10 @@ ############################################################################## # unittest configuration # -# [unittest_name] -# file = <name>.flat # Name of the flat file to be used. -# smp = <num> # Number of processors the VM will use -# # during this test. Use $MAX_SMP to use -# # the maximum the host supports. Defaults -# # to one. -# extra_params = -append <params...> # Additional parameters used. -# arch = riscv32|riscv64 # Select one if the test case is -# # specific to only one. -# groups = <group_name1> <group_name2> ... # Used to identify test cases -# # with run_tests -g ... -# # Specify group_name=nodefault -# # to have test not run by -# # default -# accel = kvm|tcg # Optionally specify if test must run with -# # kvm or tcg. If not specified, then kvm will -# # be used when available. -# timeout = <duration> # Optionally specify a timeout. -# check = <path>=<value> # check a file for a particular value before running -# # a test. The check line can contain multiple files -# # to check separated by a space but each check -# # parameter needs to be of the form <path>=<value> +# riscv specifics: +# +# file = <name>.flat # riscv uses .flat files +# arch = riscv32|risc64 ############################################################################## [selftest] diff --git a/s390x/unittests.cfg b/s390x/unittests.cfg index 550eff787..d6abf72f3 100644 --- a/s390x/unittests.cfg +++ b/s390x/unittests.cfg @@ -1,21 +1,9 @@ ############################################################################## # unittest configuration # -# [unittest_name] -# file = <name>.elf # Name of the elf file to be used. -# extra_params = -append <params...> # Additional parameters used. -# groups = <group_name1> <group_name2> ... # Used to identify test cases -# # with run_tests -g ... -# # Specify group_name=nodefault -# # to have test not run by default -# accel = kvm|tcg # Optionally specify if test must run with -# # kvm or tcg. If not specified, then kvm will -# # be used when available. -# timeout = <duration> # Optionally specify a timeout. -# check = <path>=<value> # check a file for a particular value before running -# # a test. The check line can contain multiple files -# # to check separated by a space but each check -# # parameter needs to be of the form <path>=<value> +# s390x specifics: +# +# file = <name>.elf # s390x uses .elf files ############################################################################## [selftest-setup] diff --git a/x86/unittests.cfg b/x86/unittests.cfg index 124be7a1f..867a8ea2f 100644 --- a/x86/unittests.cfg +++ b/x86/unittests.cfg @@ -1,28 +1,10 @@ ############################################################################## # unittest configuration # -# [unittest_name] -# file = <name>.flat # Name of the flat file to be used. -# smp = <num> # Number of processors the VM will use -# # during this test. Use $MAX_SMP to use -# # the maximum the host supports. Defaults -# # to one. -# extra_params = -append <params...> # Additional parameters used. -# arch = i386|x86_64 # Select one if the test case is -# # specific to only one. -# groups = <group_name1> <group_name2> ... # Used to identify test cases -# # with run_tests -g ... -# # Specify group_name=nodefault -# # to have test not run by -# # default -# accel = kvm|tcg # Optionally specify if test must run with -# # kvm or tcg. If not specified, then kvm will -# # be used when available. -# timeout = <duration> # Optionally specify a timeout. -# check = <path>=<value> # check a file for a particular value before running -# # a test. The check line can contain multiple files -# # to check separated by a space but each check -# # parameter needs to be of the form <path>=<value> +# x86 specifics: +# +# file = <name>.flat # x86 uses .flat files +# arch = i386|x86_64 ############################################################################## [apic-split] -- 2.42.0
