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