Barman public API

Use the bare-metal agent by calling the following public API functions.

barman_initialize

The prototype of barman_initialize varies depending on the datastore chosen.

When using the linear or circular RAM buffer:

BM_NONNULL((1, 3, 4))
bm_bool barman_initialize(bm_uint8 * buffer, bm_uintptr buffer_length,

When using STM:

BM_NONNULL((2, 3, 4))
bm_bool barman_initialize_with_stm_interface(void * stm_configuration_registers, void * stm_extended_stimulus_ports,

When using ITM on Arm^® M-profile architectures:

BM_NONNULL((1, 2))
bm_bool barman_initialize_with_itm_interface(

When using ITM on Arm A- or R-profile architectures:

BM_NONNULL((1, 2, 3))
bm_bool barman_initialize_with_itm_interface(void * itm_registers,

The remaining parameters for each datastore are the same:

    const char * target_name,
    const struct bm_protocol_clock_info * clock_info,
#if BM_CONFIG_MAX_TASK_INFOS > 0
    bm_uint32 num_task_entries,
    const struct bm_protocol_task_info * task_entries,
#endif
#if BM_CONFIG_MAX_MMAP_LAYOUTS > 0
    bm_uint32 num_mmap_entries,
    const struct bm_protocol_mmap_layout * mmap_entries,
#endif
    bm_uint32 timer_sample_rate);

barman_initialize function information
Description	Initialize Barman.
Parameters	`buffer` Pointer to in memory buffer. `buffer_length` Length of the in memory buffer. `stm_configuration_registers` Base address of the STM configuration registers. This parameter can be NULL if it is initialized elsewhere, for example by the debugger. `stm_extended_stimulus_ports` Base address of the STM extended stimulus ports. `itm_registers` Base address of the ITM registers. `datastore_config` Pointer to the configuration to pass to `barman_ext_datastore_initialize`. `target_name` Name of the target device. `clock_info` Information about the monotonic clock used for timestamps. `num_task_entries` Length of the array of task entries in `task_entries`. If this value is greater than `BM_CONFIG_MAX_TASK_INFOS`, it is truncated. `task_entries` The task information descriptors. Can be NULL. `num_mmap_entries` The length of the array of mmap entries in `mmap_entries`. If this value is greater than `BM_CONFIG_MAX_MMAP_LAYOUT`, it is truncated. `mmap_entries` The mmap image layout descriptors. Can be NULL. `timer_sample_rate` Timer-based sampling rate in Hertz. Zero indicates no timer-based sampling (assumes a maximum 4GHz sample rate). This value is informative only, and is used for reporting the timer frequency in the Streamline UI.
Return value	`BM_TRUE` On success. `BM_FALSE` On failure.

Note

If BM_CONFIG_MAX_TASK_INFOS ≤ 0, num_task_entries and task_entries are not present.

If BM_CONFIG_MAX_MMAP_LAYOUTS ≤ 0, num_mmap_entries and mmap_entries are not present.

barman_enable_sampling

void barman_enable_sampling(void);

barman_enable_sampling function information
Description	Enables sampling. Call when all PMUs are enabled and the data store is configured.

barman_disable_sampling

void barman_disable_sampling(void);

barman_disable_sampling function information
Description	Disables sampling without reconfiguring the PMU. To resume sampling, call `barman_enable_sampling`.

barman_sample_counters

void barman_sample_counters(bm_bool sample_return_address);

barman_sample_counters function information
Description	Reads the configured PMU counters for the current processing element and inserts them into the data store. Can also insert a Program Counter record using the return address as the PC sample.
Parameter	`sample_return_address` `BM_TRUE` to sample the return address as PC, `BM_FALSE` to ignore.

Note

The Call Paths view displays the PC values. This view is blank if the application does not call barman_sample_counters with sample_return_address == BM_TRUE, or barman_sample_counters_with_program_counter with pc != BM_NULL.
Application code that is not doing periodic sampling typically calls this function with sample_return_address == BM_TRUE.
This function must be run on the processing element for the PMU that it intends to sample from. It must not be migrated to another processing element for the duration of the call. This is necessary as it needs to program the per processing element PMU registers.

barman_sample_counters_with_program_counter

void barman_sample_counters_with_program_counter(const void * pc);

barman_sample_counters_with_program_counter function information
Description	Reads the configured PMU counters for the current processing element and inserts them into the data store.
Parameter	`pc` The PC value to record. The PC entry is not inserted if `pc == BM_NULL`.

Note

The Call Paths view displays the PC values. This view is blank if the application does not call barman_sample_counters_with_program_counter with pc != BM_NULL, or barman_sample_counters with sample_return_address == BM_TRUE.
A periodic interrupt handler typically calls this function, with pc == <the_exception_return_address>.
This function must be run on the processing element for the PMU that it intends to sample from. It must not be migrated to another processing element for the duration of the call. This is necessary as it needs to program the per processing element PMU registers.

The following functions are available if BM_CONFIG_MAX_TASK_INFOS > 0 :

barman_add_task_record

bm_bool barman_add_task_record(bm_uint64 timestamp, const struct bm_protocol_task_info * task_entry);

barman_add_task_record function information
Description	Adds a task information record.
Parameters	`timestamp` The timestamp at which the record is inserted. `task_entry` The new task entry.
Return value	`BM_TRUE` On success. `BM_FALSE` On failure.

barman_record_task_switch

void barman_record_task_switch(enum bm_task_switch_reason reason);

barman_record_task_switch function information
Description	Records that a task switch has occurred. Call this function after the new task is made the current task, so a call to `barman_ext_get_current_task_id` returns the new task ID. For example, insert it into the scheduler of an RTOS just after the new task is selected to record the task switch.
Parameter	`reason` Reason for the task switch.

Note

Call after the task switch has occurred so that bm_ext_get_current_task returns the task_id of the switched to task.

The following function is available if BM_CONFIG_MAX_MMAP_LAYOUTS > 0:

barman_add_mmap_record

bm_bool barman_add_mmap_record(bm_uint64 timestamp, const struct bm_protocol_mmap_layout * mmap_entry);

barman_add_mmap_record function information
Description	Adds a `mmap` information record.
Parameters	`timestamp` The timestamp at which the record is inserted. `mmap_entry` The new `mmap` entry.
Return value	`BM_TRUE` On success. `BM_FALSE` On failure.

Data types associated with the public API functions:

bm_protocol_clock_info

struct bm_protocol_clock_info
{
   bm_uint64 timestamp_base;
   bm_uint64 timestamp_multiplier;
   bm_uint64 timestamp_divisor;
   bm_uint64 unix_base_ns;
};

bm_protocol_clock_info function information
Description	Defines information about the monotonic clock used in the trace. Timestamp information is stored in arbitrary units within samples. Arbitrary units reduce the overhead of making the trace by removing the need to transform the timestamp into nanoseconds at the point the sample is recorded. The host expects timestamps to be in nanoseconds. The arbitrary timestamp information is transformed to nanoseconds according to the following formula: `bm_uint64 nanoseconds = (((timestamp - timestamp_base) * timestamp_multiplier) / timestamp_divisor);` Therefore for a clock that already returns time in nanoseconds, `timestamp_multiplier` and `timestamp_divisor` should be configured as `1` and `1`. If the clock counts in microseconds then the multiplier and divisor should be set to `1000` and `1`. If the clock counts at a rate of n Hertz, then the multiplier should be set to `1000000000` and the divisor to n.
Members	`timestamp_base` The base value of the timestamp so that this value is zero in the trace. `timestamp_multiplier` The clock rate ratio multiplier. `timestamp_divisor` The clock rate ratio divisor `unix_base_ns` The Unix timestamp base value, in nanoseconds, so a `timestamp_base` maps to a `unix_base` Unix time value.

bm_protocol_task_info

struct bm_protocol_task_info
{
   bm_task_id_t task_id;
   const char * task_name;
};

bm_protocol_task_info function information
Description	A task information record. Describes information about a unique task within the system.
Members	`task_id` The task ID. `task_name` The name of the task.

bm_protocol_mmap_layout

struct bm_protocol_mmap_layout
{
#if BM_CONFIG_MAX_TASK_INFOS > 0
   bm_task_id_t task_id;
#endif
   bm_uintptr base_address;
   bm_uintptr length;
   bm_uintptr image_offset;
   const char * image_name;
};

bm_protocol_mmap_layout function information
Description	An MMAP layout record. Describes the position of an executable image (or section thereof) in memory, allowing the host to map PC values to the appropriate executable image.
Members	`task_id` The task ID to associate with the map. `base_address` The base address of the image, or image section. `length` The length of the image, or image section. `image_offset` The image section offset. `image_name` The name of the image.

bm_task_switch_reason

enum bm_task_switch_reason
{
   BM_TASK_SWITCH_REASON_PREEMPTED = 0,
   BM_TASK_SWITCH_REASON_WAIT = 1
};

bm_task_switch_reason function information
Description	Reason for a task switch.
Members	`BM_TASK_SWITCH_REASON_PREEMPTED` Thread is preempted. `BM_TASK_SWITCH_REASON_WAIT` Thread is blocked waiting, for example on I/O.

WFI and WFE event handling functions:

barman_wfi

void barman_wfi(void);

barman_wfi function information
Description	Wraps WFI instruction and sends events before and after the WFI to log the time in WFI. This function is safe to use in place of the usual WFI `asm` instruction, as it degenerates to just a WFI instruction when Barman is disabled.

barman_wfe

void barman_wfe(void);

barman_wfe function information
Description	Wraps WFE instruction and sends events before and after the WFE to log the time in WFE. This function is safe to use in place of the usual WFE `asm` instruction as it degenerates to just a WFE instruction when Barman is disabled.

barman_before_idle

void barman_before_idle(void);

barman_before_idle function information
Description	Call before a WFI or WFE, or other similar halting event, to log entry into the paused state. Can be used in situations where `barman_wfi()` or `barman_wfe()` is not suitable.

Note

You must use barman_before_idle in a pair with barman_after_idle().
Using barman_wfi() or barman_wfe() is usually preferred, as it takes care of calling the before and after functions.

barman_after_idle

void barman_after_idle(void);

barman_after_idle function information
Description	Call after a WFI or WFE, or other similar halting event, to log exit from the paused state. Can be used in situations where `barman_wfi()` or `barman_wfe()` is not suitable.

Note

You must use barman_after_idle in a pair with barman_before_idle().
Using barman_wfi() or barman_wfe() is usually preferred, as it takes care of calling the before and after functions.

Functions for recording textual annotations:

barman_annotate_channel

void barman_annotate_channel(bm_uint32 channel, bm_uint32 color, const char * string)

barman_annotate_channel function information
Description	Adds a string annotation with a display color, and assigns it to a channel.
Parameters	`channel` The channel number. `color` The annotation color from `bm_annotation_colors` . `text` The annotation text, or null to end the previous annotation.

Note

Annotation channels and groups are used to organize annotations within the threads and processes section of the Timeline view. Each annotation channel appears in its own row under the thread. Channels can also be grouped and displayed under a group name, using the barman_annotate_name_group function.

barman_annotate_name_channel

void barman_annotate_name_channel(bm_uint32 channel, bm_uint32 group, const char * name)

barman_annotate_name_channel function information
Description	Defines a channel and attaches it to an existing group.
Parameters	`channel` The channel number. `group` The group number. `name` The name of the channel.

Note

The channel number must be unique within the task.

barman_annotate_name_group

void barman_annotate_name_group(bm_uint32 group, const char * name)

barman_annotate_name_group function information
Description	Defines an annotation group.
Parameters	`group` The group number. `name` The name of the group.

Note

The group identifier, group, must be unique within the task.

barman_annotate_marker

void barman_annotate_marker(bm_uint32 color, const char * text)

barman_annotate_marker function information
Description	Adds a bookmark with a string and a color to the Timeline view and Log view. The string is displayed in the Timeline view when you hover over the bookmark, and in the Message column in the Log view.
Parameters	`color` The marker color from `bm_annotation_colors` . `text` The marker text, or null for no text.

bm_annotation_colors

bm_annotation_colors function information
Description	Color macros for annotations. See Annotation #defines .