CSI Output: Metadata

Program Coverage Details

Program Coverage metadata is stored as text in the debug sections .debug_FC, .debug_CC, and .debug_BBC (for function coverage, call coverage, and statement coverage, respectively) of the object file or executable. Note that in the case of multiple object files linked into a single executable, the executable contains the complete metadata consolidated from all object files. To extract this data, use a command similar to
Tools/extract-section --require .debug_CC myexe
This particular command will extract the metadata for call-site coverage. The extracted information will contain entries for each instrumented function in any object file linked into the executable.

For each form of program coverage, we present example metadata (taken from the unit test funcs), and the format grammar for the metadata. In format grammars, Non-terminals are distinguished from terminals by capitalization, color, and italics. All metadata grammars contain the following shared rules:

Each Function entry lists the function’s name and the name of the global coverage array. Note that the non-terminal Entry_List is defined differently for each type of metadata. The following sections describe each in detail.

Function Coverage

Function coverage metadata is stored in section .debug_FC of the instrumented object file or executable. Each entry gives information for a function in the executable. A complete example (from the unit test funcs) is:

#abc|__FC_arr_abc
#a|__FC_arr_a
#b|__FC_arr_b
#main|__FC_arr_main

The format grammar follows.

That is, function coverage metadata lists only functions and their global coverage array names. Of course, each of these “arrays” has only one entry (whether or not that function previously executed), so the variables are actually simply Booleans (see the variables page). Function coverage data has no stack-local variant, as functions in the active program stack are clearly already executing. Recall that each Function entry lists the function’s name and the name of the global coverage array. In the example above, then, function main’s global function coverage variable will be named __FC_arr_main in the executing program.

Call-site Coverage

Call-site coverage metadata is stored in section .debug_CC of the instrumented object file or executable. Each entry gives information for each call site in the function. A complete example (from the unit test funcs) is:

#a|__CC_arr_a
0|20|printf
1|14|printf
2|17|abc
3|18|abc
4|19|abc
#b|__CC_arr_b
0|26|a
#main|__CC_arr_main
0|35|a
1|35|printf
2|36|b
3|36|printf

The format grammar follows.

Each function header lists the function’s name and the name of its global coverage array (e.g., __CC_arr_main holds data for main’s global call coverage). The header is followed by N Call lines each describing one of the N call sites in the function. For each call, the metadata lists the index of the call’s boolean flag (from 0 to N-1) in both the local and global coverage arrays, the line number of the call, and the name of the Called_Function. If the called function cannot be statically determined, the function name is replaced with a ?. In the example above, then, there is a call to function abc on line 17 within function a. In a running version of this program, the boolean value at __CC_arr_a[2] (and the corresponding local variable __CC_arr[2]; see the variables page), denotes whether or not the program has previously executed and returned from this call.

Statement Coverage

Statement coverage metadata is stored in section .debug_BBC of the instrumented object file or executable. Each entry gives information for a single basic block in the function. A complete example (from the unit test funcs) is:

#abc|__BBC_arr_abc
0|3|4
1|5
2|8
3|9
#a|__BBC_arr_a
0|11|12|13
1|14
2|16
3|17|18|19|20|21
#b|__BBC_arr_b
0|24|25
1|26
2|27
3|28
#main|__BBC_arr_main
0|31|32|33|34|35|36|37

The format grammar follows.

Analogous to previous examples, function main’s global array will be named __BBC_arr_main in the executing program. The header is followed by N Block lines each describing one of the N basic blocks in the function. For each block, the metadata lists the index of the block's boolean flag (from 0 to N-1) in both the local and global coverage arrays, and an ordered list of the line numbers for statements within that basic block (Line_List). If the block contains no statements with line number information (e.g., for program flow not associated directly with source locations, or due to either incomplete debug information from compilation), the Line_List is replaced with NULL.