2. PopVision trace instrumentation library C++ API

namespace pvti

TraceChannels

PVTI library predefined trace categories.

These predefined channels can be enabled or disabled at runtime. Tracepoints can be created using these channels, or custom channels can be added.

TraceChannel traceDrivers
TraceChannel tracePoplar

Typedefs

typedef struct pvti::TraceChannel TraceChannel

PVTI trace categories type definition.

Use for defining custom channels.

typedef struct pvti::ThreadName ThreadName

Functions

void enableTraceChannel(TraceChannel *channel)

Enable tracing channel for the session.

PVTI_OPTIONS environment variable must be set, and trace enabled. See “Configuring trace options” for more information.

Parameters

channel – A pointer to the channel to be enabled.

void disableTraceChannel(TraceChannel *channel)

Disable tracing channel for the session.

Parameters

channel – A pointer to the channel to be disabled.

bool checkTraceChannel(TraceChannel *channel)

Check if tracing channel is enabled.

Parameters

channel – A pointer to the channel to check.

Returns

True if the channel is enabled, false if it is disabled.

std::vector<TraceChannel*> listTraceChannel(void)

Get a list of all traceChannels in the session.

Returns

A vector of pointers to the traceChannels in the session.

std::string getCurrentTraceFilename(void)

Get the current trace session filename.

Returns

The current trace session filename.

void closeTrace()

Close the current trace session.

No Tracepoint events should be invoked following this function call.

std::vector<std::uint32_t> decodeHeatmapData(const std::vector<std::uint8_t> &data)

Decode heatmap data from an encoded vector.

When using PVTI Heatmaps, some of the information is encoded before being written to the PVTI file - specifically, field bin_quantities in table HEATMAP_DATA. This function accepts the encoded value and returns the decoded value.

Parameters

data – Encoded blob of HEATMAP_DATA::bin_quantities.

Returns

Decoded values as a std::vector<std::uint32_t>.

Metadata createJsonMetadata(const std::string &json)

Helper function to create a metadata object from a json string.

Parameters

json – A json string

class Client
#include <pvti.hpp>

PVTI Client class should be added to any singleton which contains PVTI clients like Tracepoint, Graph and Series.

This is to ensure that PVTI Session singleton is created early on and it does not go out of scope before any of its clients.

Public Functions

Client()
class Graph

Public Functions

Graph(const std::string &name, const std::string &unit = "", const bool enable = true)
pvti::Series addSeries(const std::string &name, const bool enable = true)
void enable(void)
void disable(void)
bool check(void) const
int32_t getId(void) const
std::string getName(void) const
template<class T>
class Heatmap
#include <pvti.hpp>

Class to add heatmaps.

Note that only the following template types are supported: double, std::uint64_t, std::int64_t. Note that all bins are half-open, and overflow bins will be added at each end. I.e. if your bin edges are: [10, 15, 20, 25] then:

  • the first bin counts all values < 10,

  • the second bin is [10, 15) - including 10 but excluding 15,

  • the third bin is [15, 20),

  • the fourth bin is [20, 25),

  • finally, the last bin counts all values >= 25.

Public Functions

Heatmap(const std::string &name, std::vector<T> edgeFunctionInputs, const std::string &edgeFunction = "", const std::size_t numParts = 0)

Create a heatmap.

Parameters

  • name – Name of heatmap.

  • edgeFunctionInputs – Unordered values to be applied to edgeFunction to produce the bin edge values (including first and last edge).

  • edgeFunction – Mathematical function (if any) to produce bin edge values from edgeFunctionInputs. Supported formats: “n^x” (for any integer value n).

  • numParts – If you wish to provide the unbinned data points for each reading (timestamp) in multiple parts, this allows you to specify how many parts - i.e. how many times you will call add() for each reading. Note that a value of 0 means there is 1 part, but parameter readingId for function add will be ignored, so timestamps will not be synchronised with other Heatmap objects.

void add(const std::vector<T> &rawValues, const std::size_t readingId = 0)

Provide raw (unbinned) values to be binned into the heatmap.

Parameters

  • rawValues – These values will have dataFunction (from the constructor) applied to them before they are binned according to the bin edges specified in the constructor.

  • readingId – Used to identify which parts belong to the same reading (if numParts in the constructor is greater than 1). Used across all Heatmap objects to ensure data for the same reading of each tensor has the same timestamp.

class Metadata
#include <pvti.hpp>

Base class for creating metadata.

This allows you to attach extra information to Trace events. The class is not intended to be subclassed; it should be instantiated directly or with the use of helper functions like createJsonMetadata.

Public Functions

Metadata(const std::string &type)

Metadata constructor.

Parameters

type – Type information which describes the format of the data parameter (for example, “json”). The type must be recognised by the System Analyser in order for data to be displayed correctly.

Metadata(const Metadata&) = default

Default copy constructor.

Metadata(Metadata&&) = default

Default move constructor.

Metadata &operator=(const Metadata&) = default

Default assignment operator.

bool operator==(const Metadata &other) const

Equality operator operator== is required to compare keys in case of a hash collision.

void writeU8(uint8_t value)

Write methods to put data in to the meta data buffer.

void writeU16(uint16_t value)
void writeU32(uint32_t value)
void writeBuffer(const uint8_t *const value, unsigned len)
std::size_t hash() const noexcept

Metadata hash method Calculate the hash for this meta data.

Public Members

std::vector<uint8_t> data
std::string type
class Series

Public Functions

Series(const std::string &name, const Graph &graph, const bool enable = true)
void add(const double value)
inline void add(const int value)
void enable(void)
void disable(void)
bool check(void) const
struct ThreadName

Public Functions

ThreadName(const char *tname)

Construct a ThreadName object for calling thread, and add it to the current session.

Parameters

tname – thread name to be set

struct TraceChannel
#include <pvti.hpp>

PVTI trace categories type definition.

Use for defining custom channels.

Public Functions

TraceChannel(const char *name, bool enabled = true)

Construct a TraceChannel object, and add it to the current session.

Parameters

Public Members

const char *name
bool enabled
class Tracepoint
#include <pvti.hpp>

Class for managing tracing of events.

Public Functions

Tracepoint(TraceChannel *traceChannel, std::string traceLabel, const Metadata *metadata = nullptr)

Profile a function or a scope by creating a named stack object of Tracepoint type.

Parameters

  • traceChannel – The channel to create the tracepoint for

  • traceLabel – A unique user-friendly string for this scope’s trace.

  • metadata – A metadata object associated with the event.

Tracepoint(TraceChannel *traceChannel, const char *traceLabel, const int32_t traceLabelLen = -1, const Metadata *metadata = nullptr)

Profile a function or a scope by creating a named stack object of Tracepoint type.

Parameters

  • traceChannel – The channel to create the tracepoint for.

  • traceLabel – A unique user-friendly string for this scope’s trace.

  • traceLabelLen – The number of characters to use from the traceLabel (-1 indicates all).

  • metadata – A metadata object associated with the event.

~Tracepoint()

Invoked on Tracepoint function exit.

Tracepoint(const Tracepoint&) = delete
Tracepoint &operator=(const Tracepoint&) = delete

Public Static Functions

static void begin(TraceChannel *traceChannel, std::string traceLabel, const Metadata *metadata = nullptr)

Start profiling a region using this function.

Should be complemented with an end() to profile between the two.

Parameters

  • traceChannel – The channel to create tracepoints for.

  • traceLabel – A unique user-friendly string for this region’s trace.

  • metadata – A metadata object associated with the event.

static void begin(TraceChannel *traceChannel, const char *traceLabel, const int32_t traceLabelLen = -1, const Metadata *metadata = nullptr)

Start profiling a region using this function.

Should be complemented with with an end() to profile between the two.

Parameters

  • traceChannel – The channel to create tracepoints for.

  • traceLabel – A unique user-friendly string for this region’s trace.

  • traceLabelLen – The number of characters to use from the traceLabel (-1 indicates all).

  • metadata – A metadata object associated with the event.

static void end(TraceChannel *traceChannel, std::string traceLabel, const Metadata *metadata = nullptr)

End profiling a region using this function.

Should be the complement to a begin() to profile between the two.

Parameters

  • traceChannel – The channel to create tracepoints for.

  • traceLabel – A unique user-friendly string for this region’s trace.

  • metadata – A metadata object associated with the event.

static void end(TraceChannel *traceChannel, const char *traceLabel, const int32_t traceLabelLen = -1, const Metadata *metadata = nullptr)

End profiling a region using this function.

Should be the complement to a begin() to profile between the two.

Parameters

  • traceChannel – The channel to create tracepoints for.

  • traceLabel – A unique user-friendly string for this region’s trace.

  • traceLabelLen – The number of characters to use from the traceLabel (-1 indicates all).

  • metadata – A metadata object associated with the event.

static void event(TraceChannel *traceChannel, std::string traceLabel, const Metadata *metadata = nullptr)

Mark an occurrence to be instrumented.

Can be used to compute duration between two events of the same or different type.

Parameters

  • traceChannel – The channel to create tracepoints for.

  • traceLabel – A unique user-friendly string for this event.

  • metadata – A metadata object associated with the event.

static void event(TraceChannel *traceChannel, const char *traceLabel, const int32_t len = -1, const Metadata *metadata = nullptr)

Mark an occurrence to be instrumented.

Can be used to compute duration between two events of same or different type.

Parameters

  • traceChannel – The channel to create tracepoints for.

  • traceLabel – A unique user-friendly string for this event.

  • traceLabelLen – The number of characters to use from the traceLabel (-1 indicates all).

  • metadata – A metadata object associated with the event.