harness: machines: define custom buildall targets for armv7/armv8 machines
[barrelfish] / tools / harness / README
1 ##########################################################################
2 Copyright (c) 2009, ETH Zurich.
3 All rights reserved.
4
5 This file is distributed under the terms in the attached LICENSE file.
6 If you do not find this file, copies can be found by writing to:
7 ETH Zurich D-INFK, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
8 ##########################################################################
9
10 Barrelfish test/benchmarking harness README
11
12 RUNNING TESTS
13
14 This set of Python modules is designed to automate the process of
15 building, booting and collecting/analysing the output of various bechmarks
16 on Barrelfish. There are currently two top-level programs:
17
18 scalebench.py -- the (poorly-named) main script to run tests and collect results
19 reprocess.py -- this is a utility using the same backend code that
20   allows the results of one or more previous runs to be re-analysed
21   without rerunning the benchmark
22
23 scalebench.py is essentially a nested loop that runs one or more tests
24 for one or more builds on one or more victim machines. The available
25 builds, machines and tests are determined by the local site and the
26 configured modules -- use scalebench.py -L to see a list.
27
28 Specifying builds
29 -----------------
30
31 Build types may be specified the -b argument (which may be passed multiple
32 times). Presently-supported builds are hake's default configuration, and a
33 "release" configuration (without assertions or debug info). For a given build
34 type, a build directory will be automatically created under the "build base"
35 path, specified with -B. This allows the reuse of results of previous builds
36 of the same type. Alternatively, rather than passing -b, the -e argument
37 may be used to specify a path to an existing (configured) build directory;
38 this allows the user to quickly run benchmarks against a specific set of
39 compiled binaries with arbitrary build options.
40
41 Specifying machines
42 -------------------
43
44 One or more victim 'machines' must be specified with the -m argument.
45 This includes, at a minimum, the machines 'qemu1' and 'qemu4' which are
46 simulated 1-way and 4-way CPUs. Depending on your site, various real
47 hosts will also be available.
48
49 Specifying tests
50 ----------------
51
52 A large number of tests are available, and at least one must be specified
53 with -t. See scalebench.py -L for a list of currently-defined tests and
54 a short description of each. Not all tests may work at one time, and some
55 tests probably won't work on all machines (in particular qemu). You'll have
56 to use common sense here or ask for help.
57
58 Note that the -b, -m and -t arguments accept shell-style glob wildcards;
59 this can be useful to run a set of similarly-named tests, or to try all
60 build types.
61
62 Results
63 -------
64
65 Each test run, successful or not, produces a set of files in a result
66 directory, which is currently created with a unique name under a global
67 results directory that you must pass as the final argument to scalebench.
68 This directory contains some metadata describing the test run
69 (description.txt), the full console output from running the test (raw.txt)
70 and any other test-specific files produced by running the test or processing
71 its results -- these are hopefully self-explanatory, but if not see the
72 python module that defines the test for information.
73
74
75 INVOCATION EXAMPLES
76
77 For a quick x86_64 smoke-test, try something like:
78
79 python scalebench.py -m qemu1 -t memtest -v SOURCEDIR /tmp/results
80
81
82 DEFINING NEW MACHINES, BUILDS, AND TESTS
83
84 This is presently undocumented :(
85 Please see the existing examples, or ask Andrew for help.
86
87
88 TODOs
89
90  * Better support for multiple architectures.
91  * Better support for processing results, plot scripts etc.
92  * Better error handling (don't blow up in a backtrace when subprograms fail)
93  * Parallel tests/builds