API

Byfl API

Byfl is normally told what to instrument via compile-time options, not via a run-time API. That said, Byfl does provide a few functions that programs can call explicitly for more run-time control of instrumentation. These functions can be declared in a C or C++ program with

#include <byfl/byfl.h>

Tagging memory regions

Byfl's -bf-data-structs option instruments loads and stores on a per-data-structure basis. Applications can declare and invoke the following function to associate an arbitrary textual tag with a fragment of a data structure (an individual memory allocation):

void bf_tag_data_region (void* address, const char *tag);

The above is a C function and should be declared extern "C" in a C++ program. It takes an address within an allocation, typically the address returned by malloc() or some other memory-allocation routine, and an arbitrary tag to associate with the allocation. Byfl effectively partitions data structures based on tags and logs tags in an additional column in the Data-structure accesses table.

Dynamically enabling and disabling instrumentation

Technically, all Byfl instrumentation code is inserted at compile time and cannot be completely disabled at run time. Hence, it is not normally possible to instrument, say, a single iteration of a loop or a specific invocation of a given function. The following function is intended to help with such use cases:

However, the following function instructs the Byfl run-time library not to update any of its data structures until told otherwise.

void bf_enable_counting (int enable);

When given an argument of 0, bf_enable_counting() inhibits data-structure updates for almost all Byfl counters. (The instruction-mix counters are currently unaffected by bf_enable_counting().) The instrumented application will run faster than it would otherwise but not as fast as when uninstrumented. When given an argument of 1, bf_enable_counting() reverts the Byfl run-time library to its normal operation.

Partitioning program-level counters

Byfl logs a number of whole-program counters. Applications can partition these arbitrarily by defining the following C function (using extern "C" in C++ programs) and compiling with -bf-every-bb—and typically also providing a large value for bf-merge-bb to avoid excessive logging:

const char* bf_categorize_counters (void);

The function is expected to return a tag with which to associate loads, stores, flops, etc. bf_categorize_counters() is called extremely frequently so it should perform as little computation as possible.