4.5 Raw Code Coverage Format

The idea behind the raw format files is to allow any user to create code coverage reports or do some automated analysis on them, in those cases that the HTML report is not the best match.

The raw format file can contain all information required to create a coverage report, such as the HTML report. It may also contain partial data, such as information about available memory mappings and executed instructions. Which can later be extended in a way that it contains all required information.

The raw format contains Python data structures that have been marshalled using the Python pickle library. In the following description a Python-like syntax is used. Where quotation marks around a word mean that the string has that exact name. Without any quotations, that item gives a short description of what it represents and a longer description will follow further down. Items within <> notation describe the type of the element. An asterisk at the end of a list means zero or more of the previous elements, while a plus at the end means one or more of the previous elements.

      {"version"<string>: version<int>,
       "features"<string>: {feature<string>: feature_specific_field<unknown>},
       "errors"<string>: [[code<int>, message<string>]*],
       "unknown"<string>: {address<int>: count<int>},
       "unknown_branches"<string>: {address<int>: {"taken"<string>: count<int>,
                                                   "not_taken"<string>: count<int>}},
       "mappings"<string>: [
           {"map"<string>: {"symbol_file"<string>: file<string>,
                             "address"<string>: address<int>, "size"<string>: size<int>,
                             "file_offset"<string>: offset<int>,
                             "file_size"<string>: size<int>,
                             "relocation"<string>: relocation<int>,
                             "section"<string>: section<string>,
                             "md5"<string>: md5<string>},
            "covered"<string>: {address<int>: count<int>},
            "branches"<string>: {address<int>: {"taken"<string>: count<int>,
                                                 "not_taken"<string>: count<int>}}
            "file_table"<string>: {file_id<string>: source_file<string>},
            "functions"<string>: {address<int>: {"name"<string>: name<string>,
                                                 "size"<string>: size<int>},
                                                 "file_id"<string>: file_id<string>,
                                                 "line"<string>: line<int>,
                                                 "scope_id"<string>: id<string>
                                                 "artificial"<string>: artificial<bool>},
            "inlined_functions"<string>: [
                {"name"<string>: name<string>,
                 "file_id"<string>: file_id<string>,
                 "line"<string>: line<int>,
                 "scope_id"<string>: id<string>,
                 "artificial"<string>: artificial<bool>},
                 "instances"<string>: [
                     {"id"<string>: id<string>,
                      "parent_id"<string>: parent_id<int|string>,
                      "ranges"<string>: [[start_address<int>, end_address<int>]*],
                      "call_site"<string>: {"file_id"<string>: file_id<string>,
                                            "line"<string>: line<int>}}*],
            "scopes"<string>: {id<str>: {"name"<string>: name<string>,
                                         "is_class"<string>: is_class<bool>,
                                         "parent_id"<string>: id<string>},
            "data_labels"<string>: {address<int>: {"name"<string>: name<string>}},
            "info"<string>: [{"address"<string>: address<int>, "op": [op<int>+],
                              "mnemonic"<string>: mnemonic<string>,
                              "format"<string>: format<string>,
                              "executable_lines"<string>: {line<int>: True<bool>},
                              "file_id"<string>: file_id<string>}*],
            "src_info"<string>: {"file_id"<string>:
                                 {line<int>: [[start_address<int>, end_address<int>]*]}},
            "removed_data"<string>: {address<int>: {"size"<string>: size<int>}},
            "cpu_classes": [cpu_class<string>*],
            "disassembly_class": cpu_class<string>,
            "errors"<string>: [[code<int>, message<string>]*]}*],
       "cpu_classes": [cpu_class<string>*],
       "unknown_mappings"<string>: [
           {"map"<string>: {"address"<string>: address<int>,
                            "size"<string>: size<int>},
            "covered"<string>: {address<int>: count<int>}}]*}
    

• version - The version of the code coverage raw format that was used to create the raw file. This version number is only increased when there is a change to the format that is either extending the previous version or breaking it (should be very rare).

• features - A dictionary that maps a feature to its feature_specific_field information. Available features are:

  • access_count - This feature is used to count how many times an instruction has been executed. The feature_specific_field is a bool, where True indicates that the feature is enabled.
  • branch_coverage - This feature is used to collect branch coverage on instruction level. The feature_specific_field is a bool, where True indicates that the feature is enabled.

• errors - A list with zero or more entries, containing an error code and the matching error message for any errors that are not bound to a specific mapping.

• unknown - A dictionary which in turn maps executed addresses without any known mappings, at the execution time, to a count of how many times it was executed. In order for the execution counter to be valid, the access_count feature must be enabled. Otherwise, it will always be one for such executed instruction.

• unknown_branches - Same as mappings - branches, but for conditional branch instructions that have executed and do not belong to any mapping.

• mappings - This entry contains a list of each mapping that was known to the code coverage system while collecting data. The following entries are available

  • map - A key containing a unique description of the mapping. Which has the following identifiers:

    • symbol_file - Gives the location of the module backing up the mapping.
    • address - Specifies the loaded address of the mapping.
    • size - Specifies the size of the mapping.
    • file_offset - Specifies the offset into the file where this segment or section can be found.
    • file_size - Specifies the size of the entry in the file.
    • relocation - Specifies the relocation address.
    • section - Optional field, included when only one section of a symbol file is used as mapping.
    • md5 - Optional field, MD5 hex-digest of the symbol file.

  • covered - This field works just like unknown field, except that this is per module and contains all executed addresses that were mapped to this mapping while executing.

  • branches - Keeps track of all branch instructions and how many times a branch at the given address was taken or not taken. Only available if branch_coverage feature was enabled when collecting data.

  • file_table - Maps file_id to a full source file path.

  • functions - Information about functions (non-inlined), with the following data:

    • address (key) - Function start address.
    • size - Function size.
    • name - Function name.
    • file_id - Optional field, source file the function header is present in, entry in file_table.
    • line - Optional field, source line the function header is present at, used in combination with file_id.
    • scope_id - Optional, C++ scope for the function, entry in scopes.
    • artificial - Optional field, C++ artificial function.

  • inlined_functions - Optional field. Inlined functions in the following format:

    • name - Function name.
    • file_id - Source file for the function, entry in file_table.
    • line - Source line of the function header.
    • scope_id - Optional field, scope id for C++, entry in scopes.
    • artificial - Optional field, C++ artificial function.
    • instances - Instances where the function has been inlined with the following data:
      • id - Unique identifier for inlined function instance.
      • parent_id - Parent identifier, either id of an inlined function if this is a string, or address of a function in "functions" if this is an integer. This is optional after filtering. An inlined function without parent_id is considered orphaned, this can happen when filtering out the file that the parent existed in.
      • ranges - Address ranges [start_address, end_address] for the inlined instances. The end address is inclusive.
      • call_site - Source file (as file_id entry in file_table) and line where the inlined function was “called” from.

  • scopes - C++ scopes, which consists of namespace and classes. The key is id which is an identifier referred to by functions or other scopes. Contains name for the class or namespace, is_class that tells if the scope comes from a class and optionally a parent_id that points to a parent scope in this table.

  • data_labels - Non-executable symbols in executable sections, containing the symbol’s address and name.

  • info - Contains a list, with one element per disassembled address, where each entry has the following members:

    • address - The address of the disassembled instruction
    • op - A list of opcodes making up the instruction
    • mnemonic - The mnemonic of the instruction
    • format - Instruction format, currently only present for ARM. Tells if the instruction has arm, thumb or aarch64 format.
    • file_id - A reference to the source file in the file_table. Only exists if source info has been added and exists for this address
    • executable_lines - Describes which source lines the instruction belongs to. Only exists if source info has been added and exists for this address

  The raw data contains either this field or src_info, never both.

  • src_info - A dictionary with information about executable lines and addresses for source files. Each item in the dictionary is source file where the key corresponds to a file_id in file_table.

  The value of that item is another dictionary where there is an executable source line of that file and the value is a list of address ranges that correspond to that source line. Each address range in this list is a list of two elements, start_address and end_address, where the latter is inclusive.

  A source line can be considered executed if any of the addresses inside its address ranges is found in the covered entry.

  The raw data contains either this field or info, never both.

  • cpu_classes - Optional field. Keeps track of which cpu classes have been run in this specific mapping when collecting coverage.
  • disassembly_class - Optional field. Specifies which processor class has been used to disassemble this mapping. This field is only present when disassembling was done using a processor interface, not when a disassemble module was used.
  • removed_data - Address ranges in the mapping that have been removed because they were considered to be data. The dictionary has the start address as key the size of the removed region as value. The name of the removed symbol should be retrievable from data_labels using the start address.
  • errors - A per module error list, containing an error code and a message.

• cpu_classes - Optional field. Keeps track of which cpu classes have been used to collect coverage with.

• unknown_mappings - This entry contains a list of each mapping that was known to the code coverage system while collecting data, but did not have a symbol file name. The following entries are available

  • map - A key containing the location of the unknown mapping. It has the following identifiers:

    • address - Specifies the loaded address of the mapping.
    • size - Specifies the size of the mapping.

  • covered - This field works just like unknown field, except that this is per module and contains all executed addresses that were mapped to this mapping while executing.