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.
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.
- Return
True if the channel is enabled, false if it is disabled.
- Parameters
channel
: A pointer to the channel to check.
-
std::vector<TraceChannel*>
listTraceChannel
(void)¶ Get a list of all traceChannels in the session.
- Return
A vector of pointers to the traceChannels in the session.
-
std::string
getCurrentTraceFilename
(void)¶ Get the current trace session filename.
- Return
The current trace session filename.
-
void
closeTrace
()¶ Close the current trace session.
No Tracepoint events should be invoked following this function call.
-
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
¶
-
class
Metadata
¶ - #include <pvti.hpp>
Base class for creating metadata.
It allows attaching extra information to Trace events. The class is not intended to be subclassed but instead created directly, maybe 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.
-
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)¶
-
-
struct
metadata_hash_fn
¶ - #include <pvti.hpp>
global metadata hash function for use in the std::unordered_map
- Parameters
md
: The metadata to hash
-
class
Series
¶
-
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
name
: The channel name.enabled
: Set this to true to enable the channel when it is declared. enableTraceChannel() and disableTraceChannel() can be used to enable or disable channels at runtime.
-
-
class
Tracepoint
¶ - #include <pvti.hpp>
Class for managing tracing of events.
Public Functions
-
Tracepoint
(TraceChannel *traceChannel, const 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 fortraceLabel
: 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 thetraceLabel
(-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
-
void
begin
(TraceChannel *traceChannel, const 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.
-
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 thetraceLabel
(-1 indicates all).metadata
: A metadata object associated with the event.
-
void
end
(TraceChannel *traceChannel, const 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.
-
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 thetraceLabel
(-1 indicates all).metadata
: A metadata object associated with the event.
-
void
event
(TraceChannel *traceChannel, const 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.
-
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 thetraceLabel
(-1 indicates all).metadata
: A metadata object associated with the event.
-
-
TraceChannel