A dice is a comparison between passing and failing runs of a program.
Dice are created using the ‘mdice’ tool. To use the ‘mdice’ tool, one must first generate a set of trace count files for passing runs and a set of trace count files for failing runs using the ‘mtc’ tool (Generating trace counts). Once this has been done, and the union of each set computed using ‘mtc_union’, ‘mdice’ can be used to display a table of statistics that compares the passing runs to the failing runs.
Here is an example of the output of the ‘mdice’ tool:
Procedure Path/Port File:Line Pass (3) Fail Suspicion pred s.mrg/3-0 <s2;c2;e;> s.m:74 0 (0) 1 1.00 pred s.mrg/3-0 <s2;c2;t;> s.m:67 10 (3) 4 0.29 pred s.mrg/3-0 CALL s.m:64 18 (3) 7 0.28 pred s.mrg/3-0 EXIT s.m:64 18 (3) 7 0.28
This example tells us that the ‘else’ in ‘s.m’ on line 74 was executed once in the failing test run, but never during the passing test runs, so this would be a good place to start looking for a bug.
Each row corresponds to an event in the program. The meanings of the columns are as follows:
The ‘mdice’ tool is invoked with a command of the form:
mdice [-s sortspec] [-l N] [-m module] [-n N] [-p N] [-f N] passfile failfile
‘passfile’ is a trace count file, generated either directly by a passing program run or as the union of the trace count files of passing program runs. ‘failfile’ is a trace count file, generated either directly by a failing program run or as the union of the trace count files of failing program runs.
The table can be sorted on the Pass, Fail or Suspicion columns, or a combination of these. This can be done with the ‘-s’ or ‘--sort’ option. The argument of this option is a string made up of any combination of the letters ‘pPfFsS’. The letters in the string indicate how the table should be sorted:
For example the string "SF" means sort the table by suspicion in descending order, and if any two suspicions are the same, then by number of executions in the failing run(s), also in descending order.
The default is to sort descending on the Suspicion column.
The option ‘-l’ or ‘--limit’ can be used to limit the number of lines displayed.
The ‘-m’ or ‘--module’ option limits the output to the given module and any submodules.
The ‘-n’ or ‘--max-name-column’ option’s argument gives the maximum width of the column containing predicate names. If the argument is zero, there is no maximum width.
The ‘-p’ or ‘--max-path-column’ option’s argument gives the maximum width of the column containing ports and goal paths. If the argument is zero, there is no maximum width.
The ‘-f’ or ‘--max-file-column’ option’s argument gives the maximum width of the column containing file names and line numbers. If the argument is zero, there is no maximum width.