nRF Profiler

The nRF Profiler library allows for performance measurements of an embedded device. The library provides an interface for lightweight logging of nRF Profiler events together with associated timestamp and data. This allows you to deliver information about the system state with minimal negative impact on performance. You can use the module to profile Application Event Manager events or custom events.

The nRF Profiler supports one backend that provides output to the host computer using RTT. You can use a dedicated set of host tools available in the nRF Connect SDK to visualize and analyze the collected nRF Profiler events. See the nRF Profiler host tools page for details.

See the nRF Profiler sample for an example of how to use the nRF Profiler.

Configuration

Since Application Event Manager events are converted to nRF Profiler events by the Application Event Manager profiler tracer, you can configure the nRF Profiler to profile custom events or Application Event Manager events, or both.

Note

Starting from nRF Connect SDK v3.4.0, the nRF Profiler library introduces a modified string layout for the Info RTT channel to support the nRF54L Series SoCs. The library now provides also system configuration data, such as CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC, within specific markers to allow the host tools to perform accurate time unit conversions for nRF54L Series SoCs. This modification breaks the backward compatibility with older host scripts. To ensure proper behavior, use both the library and host tools from the same nRF Connect SDK release.

Configuring for use with custom events

To use the nRF Profiler for custom events, complete the following steps:

  1. Enable the CONFIG_NRF_PROFILER Kconfig option. This option adds the nRF Profiler source code to the application.

  2. Call nrf_profiler_init() during the application start to initialize the nRF Profiler.

  3. Profile custom events, as described in the following section.

Profiling custom events

To profile custom events, complete the following steps:

  1. Register the custom events using nrf_profiler_register_event_type(). The following code example shows how to register event types:

    static const char * const data_names[] = {"value1", "value2", "value3", "value4", "string"};
static const enum nrf_profiler_arg data_types[] = {NRF_PROFILER_ARG_U32, NRF_PROFILER_ARG_S32,
            NRF_PROFILER_ARG_S16, NRF_PROFILER_ARG_U8,
            NRF_PROFILER_ARG_STRING};

no_data_event_id = nrf_profiler_register_event_type("no_data_event", NULL,
            NULL, 0);
data_event_id = nrf_profiler_register_event_type("data_event", data_names,
            data_types, 5);

  2. Add a structure for sending information about event occurrences:

    1. Add the following mandatory functions to the structure:

    2. Add one or more of the following optional functions in-between the mandatory functions, depending on the data format:

  3. Wrap the calls in one function that you then call to profile event occurrences. The following code example shows a function for profiling an event with data:

    static void profile_data_event(uint32_t val1, int32_t val2, int16_t val3,
            uint8_t val4, const char *string)
{
  struct log_event_buf buf;

  nrf_profiler_log_start(&buf);
  /* Profiling data connected with an event */
  nrf_profiler_log_encode_uint32(&buf, val1);
  nrf_profiler_log_encode_int32(&buf, val2);
  nrf_profiler_log_encode_int16(&buf, val3);
  nrf_profiler_log_encode_uint8(&buf, val4);
  nrf_profiler_log_encode_string(&buf, string);
  nrf_profiler_log_send(&buf, data_event_id);
}

Note

The data_event_id and the data that is profiled with the event must be consistent with the registered event type. The data for every data field must be provided in the correct order.

Configuration for use with Application Event Manager

To use the nRF Profiler for Application Event Manager events, refer to the Application Event Manager profiler tracer documentation. The Application Event Manager profiler tracer automatically initializes the nRF Profiler and then acts as a linking layer between Application Event Manager and the nRF Profiler.

Shell integration

The nRF Profiler is integrated with Zephyr’s Shell module. You can use the CONFIG_NRF_PROFILER_SHELL option to add an additional subcommand set (nrf_profiler) to the shell. The option is enabled by default.

This subcommand set contains the following commands:

list

Show a list of profiled event types. The letters “E” or “D” indicate if profiling is currently enabled or disabled for a given event type.

enable or disable

Enable or disable profiling. If called without additional arguments, the command applies to all event types. To enable or disable profiling for specific event types, pass the event type indexes (as displayed by list) as arguments.

API documentation

Header file: include/nrf_profiler.h
Source files: subsys/nrf_profiler/
Profiler