Implemented By
branch_recorder, data-profiler

Interface for getting statistics out of profilers. The target is some kind of profiler whose data can be meaningfully viewed as counts per address.

The function num_views returns the number k of different ways you can view the data of this object. The view selection parameter view to all other functions in the interface accepts values between 0 and k − 1.

description returns a short string that explains what the data means. physical_addresses returns true if the profiler works with physical addresses, or false if it uses virtual addresses. address_bits returns the number of bits in an address.

granularity_log2 returns the base 2 logarithm of the size, in bytes, of the address intervals that the counters are associated to. For example, if the data is instruction execution count and each instruction is 4 bytes long, one would expect the granularity to be at least 4 bytes since that is the smallest interval containing a whole instruction (but it might be more, if the profiler is less fine-grained for some reason). And for a 4-byte granularity, granularity_log2 would return 2.

sum returns the sum of all counters between start and stop, inclusive. max returns the maximum value of any counter in the range.

iter returns an address profile iterator that will visit all nonzero counters in the range precisely once, in some order. In C, you can use the functions SIM_iter_next, SIM_iter_addr and SIM_iter_free to operate the iterator. In Python, it works just like any other iterator, and returns (count, address) pairs. Note that you may not continue to use the iterator after the underlying address profiler has been modified.

typedef struct address_profiler_interface {
        addr_prof_iter_t *(*iter)(conf_object_t *prof_obj, unsigned view,
                                  generic_address_t start,
                                  generic_address_t stop);
        uint64 (*sum)(conf_object_t *prof_obj, unsigned view,
                      generic_address_t start, generic_address_t end);
        uint64 (*max)(conf_object_t *prof_obj, unsigned view,
                      generic_address_t start, generic_address_t end);
        unsigned (*granularity_log2)(conf_object_t *prof_obj, unsigned view);
        int (*address_bits)(conf_object_t *prof_obj, unsigned view);
        int (*physical_addresses)(conf_object_t *prof_obj, unsigned view);
        const char *(*description)(conf_object_t *prof_obj, unsigned view);
        unsigned (*num_views)(conf_object_t *prof_obj);
} address_profiler_interface_t;

#define ADDRESS_PROFILER_INTERFACE "address_profiler"

Command List
address-profile-datalinear map of address profiling data
address-profile-infogeneral info about an address profiler
address-profile-toplistprint toplist of address profiling data

Command Descriptions

<address_profiler>.address-profile-data [view] [address] [cell-bits] [row-bits] [table-bits] [start] [stop] [lines] [-same-prefix]
Display a map of (a part of) the address space covered by the address profiler, and the counts of one of its views associated with each address. The view is specified by the view argument; default is view 0. The default behavior is to display the smallest interval that contains all counts; you can change this with either the start and stop or the address and cell-bits, row-bits or table-bits arguments.

Cells that have zero counts are marked with ".". Cells that have a non-zero count, but were rounded to zero, are marked with "o".

If one of cell-bits, row-bits or table-bits is specified, then each cell, or each table row, or the entire table is limited to that many bits of address space. By default the display starts at address 0, but if an address is specified with the address argument, the displayed interval is shifted to make that address is visible.

If start and stop are specified, the display is limited to the smallest interval containing both addresses.

The maximum number of lines in the table is limited by the lines argument (the default is 20 lines). The scale of the map is adjusted to fit this limit.

Normally, the display chooses an appropriate prefix for the count of each cell; with the -same-prefix flag, all counts will be forced to have the same prefix. This is useful if a lot of small but non-zero values makes it hard to spot the really big values.

<address_profiler>.address-profile-info [-sum] [-max]
Print general info about an object implementing the address-profiler interface, such as a list of the available views. If the -sum or -max flags are given, will also print the sum or max of each view over the entire address space.
<address_profiler>.address-profile-toplist [symtable] [samples] [start] [stop] [view] [count_interval]
Print address profiling regions sorted by count. The symtable attribute can be used to map data profiling regions in form of physical addresses to source function and file information.

The samples argument specifies the number of sampling points used to create the list containing the highest count. The sampling range is determined by start and stop. The default values are 100 samples in the interval 0x0 - 0xfffffffc. The granularity is defined by the data profiler object.

The view attribute selects the address profiler view.

The count_interval attribute defines the range in which sampled data regions will match even thought the data profiler count is not equal. Ex. Assume that the samples in the region 0x20c - 0x20c has a count of 4711 and region 0x20d - 0x20f a count of 4713. The regions will be considered on region if count_interval is 4 but not if 1.