README
1vbit-test
2
3The program tests the effect of an undefined input bit to an IROp on the
4definedness of the result of that operation. It also checks that only those
5bits in the result are undefined that we expect to be undefined. That way
6we can detect false positives (there are bits in the result that are
7undefined but shouldn't) and false negatives (there are defined bits in
8the result that should be undefined).
9
10By design, the tester will always be in-synch with the list of IROps
11in libvex_ir.h. Addition / removel of IROps will cause a compile or
12runtime error of the tester and thusly will not go unnoticed.
13
14
15How it works
16------------
17The underlying idea is to
18(1) use VALGRIND_SET_VBITS to set the V-bits of the operands of an IROp
19(2) execute that IROp
20(3) use VALGRIND_GET_VBITS to obtain the V-bits of the result
21(4) compare the result against our expectation
22Do that for all IROps and for all input bits of their operands.
23For all this to work, the tester must run under the auspices of memcheck.
24
25The key step here is #2. To "execute an IROp" we need to inject some
26IR into the the superblock. This is accomplished by adding a new "special
27instruction" that is supported by all frontends. During the decoding step
28that instruction will be recognised and a suitable piece of IR will be
29inserted (function vex_inject_ir does just that). What is "suitable" depends
30on the IROp at hand and its operands. We need to know the addresses of
31those operands, their types and, trivially, which IROp we want to execute.
32This information is collected in the IR Injection Control Block (IRICB).
33To get the IRICB to VEX we use the new client request
34VG_USERREQ__VEX_INIT_FOR_IRI.
35
36
37Invocation
38----------
39Use vbit-test --help to obtain list of supported command line flags.
40
41
42Source code overview
43--------------------
44main.c
45Contains the main loop that iterates over all IROps in libvex_ir.h.
46Depending on the number of operands one of the functions test_unary,
47test_binary, etc. will be invoked to run all tests for that opreator.
48
49irops.c
50List of IROps. For each operator it defines how undefined input bits
51influence the output (result) and whether the operator is supported on a
52given architecture.
53
54util.c
55Miscellaneous convenience functions. It also includes sizeof_irtype and
56typeof_primop which were imported from VEX/priv/ir_defs.c.
57
58unary.c
59The function test_unary_op is the work horse. It iterates over all input
60bits of the single operand. For each such bit, the corresponding V-bit will
61be set to undefined, the IROps is executed and the resulting V-bits will
62be compared against the expected result.
63The function check_result_for_unary will check the V-bits for correctness.
64
65binary.c, ternary.c, qernary.c
66Like unary.c...
67
68valgrind.c
69The main function there is valgrind_execute_test. It will
70(1) set the V-bits of the operands using the VALGRIND_SET_VBITS mechanism,
71(2) inject IR into the current IRSB to exacute a single IROp, and
72(3) obtain the V-bits of the result using the VALGRIND_GET_VBITS mechanism.
73The addresses of the operands and the result, as well as they V-bit vectors
74are stored in the test_data_t structure.
75
76<valgrind>/VEX/priv/ir_inject.c
77The file provides the function vex_inject_ir which will inject a piece of
78IR into the current IRSB based on the information provided in the IRICB.
79That code snippet will perform a single IR operation
80
81<valgrind>/include/valgrind.h
82Defines the macro VALGRIND_VEX_INJECT_IR for all architectures.
83Also defines a new client request VG_USERREQ__VEX_INIT_FOR_IRI.
84
85
86Adding a new IROp
87-----------------
88The following steps are needed
89(1) Add the operator to irops.c
90(2) If the operator propagates undefinedness from input to output in a new
91 way:
92 (a) Add a new enumerator to undef_t and document it there.
93 (b) Add a new case in function check_result_for_XYZ depending on the
94 arity of the operator. The code snippet there is supposed to check
95 that the result matches what we expect.
96
97
98Status
99------
100vbit-test has been tested on x86-64, ppc64, s390x, and mips32.
101There is support for other architectures in valgrind.h and guest_ARCH_toIR.c
102but it has not been tested.
103