1. Attribute¶

1.1. Prof¶

This section describes the TOPSPTI prof api.

const char *TopsptiGetResultString(TopsptiResult res)¶

get the descriptive string for a TopsptiResult

Parameters: res – the result to get the string for
Returns: result string

const char *TopsptiGetProductName(int32_t dev = 0)¶

get the name of product

Returns: product name string

TopsptiResult TopsptiGetDeviceList(std::vector<int32_t> &ids)¶

get the GCU id list

Parameters: ids – [out] GCU id list
Returns: TopsptiResult

const char *SipPmcEventName(TopsptiEventKind event)¶

get the name of PMC event

Parameters: event – kind of event record to enable collecting
Returns: sip pmc event string

TopsptiResult TopsptiConfig(const TopsptiProfileConfig &config, int32_t dev = 0)¶

save configuration into config file

Parameters: config – software profiling configuration
Returns: TopsptiResult

TopsptiResult TopsptiGetVersion(uint32_t *version)¶

get the TOPSPTI API version

Parameters: version – [out] the API version
Returns: TopsptiResult

class topspti::prof::TopsProfiler¶

#include <topspti_prof_api.h>

topspti prof profiler definition

Public Functions

bool Init()¶

Init.

Returns: bool

TopsptiResult Start()¶

start profiling

Returns: TOPSPTI_SUCCESS if success, TOPSPTI_ERROR_INVALID_OPERATION if in wrong state

TopsptiResult Stop()¶

stop profiling

Returns: TOPSPTI_SUCCESS if success, TOPSPTI_ERROR_INVALID_OPERATION if in wrong state

TopsptiResult WaitOnProfile(int milliseconds)¶

wait on runtime process profiling

Returns: TopsptiResult

TopsptiResult Suspend()¶

suspend profiling

Returns: TopsptiResult

TopsptiResult Resume()¶

resume profiling

Returns: TopsptiResult

TopsptiResult Cancel()¶

cancel profiling

Returns: TopsptiResult

TopsptiResult DomainEnum(RawStrVec &domains)¶

enumerate hardware engines domains supported

Parameters: domains – [out] the domains supported
Returns: TOPSPTI_SUCCESS

TopsptiResult DeviceEnum(const char **device)¶

enumerate devices (hardware engines)

Parameters: device – [out] the hardware devices
Returns: TOPSPTI_SUCCESS

TopsptiResult DeviceEnum(TopsptiDevice *&device)¶

enumerate devices (hardware engines)

Parameters: device – [out] the hardware devices
Returns: TopsptiResult

TopsptiResult EventEnum(RawStrToStrsMap &events)¶

enumerate event kinds supported

Parameters: events – [out] the event kinds supported
Returns: TopsptiResult

TopsptiResult DomainEventEnum(const char *domain, RawStrVec &events)¶

enumerate event kinds supported on specific domain

Parameters

domain – domain type to enumerate
events – [out] the event kinds supported

Returns

TOPSPTI_SUCCESS if sucess, and TOPSPTI_ERROR_INVALID_PARAMETER if domain unrecognized

TopsptiResult ActivityEnum(RawStrToStrsMap &acts)¶

enumerate software prof activity kinds supported

Parameters: acts – [out] the activity kinds supported
Returns: TOPSPTI_SUCCESS

TopsptiResult DomainActivityEnum(const char *domain, RawStrVec &acts)¶

enumerate software prof activity kinds supported on specific domain

Parameters

domain – domain type to enumerate
acts – [out] the activity kinds supported

Returns

TopsptiResult

TopsptiResult MetricEnum(RawStrToStrsMap &metrics)¶

enumerate metrics kinds supported

Parameters: metrics – [out] the metrics kinds supported
Returns: TopsptiResult

TopsptiResult EngineGetIdFromName(TopsptiEngineKind &kind, const char *name)¶

find an engine by name

Example:

TopsptiEngineKind kind = TOPSPTI_ENGINE_UNKNOWN;
TopsptiResult ret = EngineGetIdFromName(kind, "CDMA");

Parameters

kind – [out] the ID of the engine
name – the name of engine to find

Returns

TopsptiResult

TopsptiResult ActivityGetIdFromName(TopsptiActivityKind &kind, const char *name)¶

find an activity by name

Example:

TopsptiActivityKind kind = TOPSPTI_ACTIVITY_UNKNOWN;
TopsptiResult ret = ActivityGetIdFromName(kind, "DMA Busy");

Parameters

kind – [out] the ID of the found activity or undefined if unable to find the activity
name – the name of activity to find

Returns

TopsptiResult

TopsptiResult EventGetIdFromName(TopsptiEventKind &kind, const char *name)¶

find an event by name

Example:

TopsptiEventKind kind = TOPSPTI_EVENT_UNKNOWN;
TopsptiResult ret = EventGetIdFromName(kind, "SIP Busy With Wait");

Parameters

kind – [out] the ID of the found event or undefined if unable to find the event
name – the name of event to find

Returns

TOPSPTI_SUCCESS if success, and TOPSPTI_ERROR_INVALID_PARAMETER if specified name is unrecognized

TopsptiResult ActivityEnable(TopsptiActivityKind kind)¶

enable collection of a specific kind of activity record

Example:

TopsptiResult ret = ActivityEnable(TOPSPTI_ACTIVITY_SIP_BUSY);

Parameters: kind – the kind of activity record to enable collecting
Returns: TOPSPTI_SUCCESS if success, TOPSPTI_ERROR_INVALID_METRIC if the specified activity kind is unrecognized, and TOPSPTI_ERROR_INVALID_OPERATION if the activity has been enabled already

TopsptiResult ActivityDisable(TopsptiActivityKind kind)¶

disable collection of a specific kind of activity record

Example:

TopsptiResult ret = ActivityDisable(TOPSPTI_ACTIVITY_SIP_BUSY);

Parameters: kind – the kind of activity record to disable collecting
Returns: TOPSPTI_SUCCESS if success, TOPSPTI_ERROR_INVALID_METRIC if the specified activity kind is unrecognized, and TOPSPTI_ERROR_INVALID_OPERATION if the activity has been disabled already

TopsptiResult ActivityEnable(const char *kind)¶

enable collection of a specific kind of activity record

Example:

TopsptiResult ret = ActivityEnable("SIP Busy");

Parameters: kind – the kind of activity record to enable collecting
Returns: TopsptiResult

TopsptiResult ActivityDisable(const char *kind)¶

disable collection of a specific kind of activity record

Example:

TopsptiResult ret = ActivityDisable("SIP Busy");

Parameters: kind – the kind of activity record to disable collecting
Returns: TopsptiResult

TopsptiResult traceDomainEnable(TopsptiTraceDomainKind kind)¶

enable collection of a specific domain of topstx trace record

Example:

TopsptiResult ret = traceDomainEnable(TOPSPTI_TRACE_DOMAIN_TOPSTX);

Parameters: kind – the domain of topstx trace record to enable collecting
Returns: TopsptiResult

TopsptiResult traceDomainDisable(TopsptiTraceDomainKind kind)¶

disable collection of a specific domain of topstx trace record

Example:

TopsptiResult ret = traceDomainDisable(TOPSPTI_TRACE_DOMAIN_TOPSTX);

Parameters: kind – the domain of topstx trace record to disable collecting
Returns: TopsptiResult

TopsptiResult registerGcuTraceCallback(GcuTraceFunc callback)¶

Register a callback function. When parsing raw profiling data, this function will be called when accounting topstx trace data.

Parameters: callback – the callback function
Returns: TopsptiResult

TopsptiResult getFormat(const char *path, int &format)¶

get format from rawdata file

Parameters

path – file path to get format from
format – the format of topstx trace data

Returns

TopsptiResult

TopsptiResult EngineActivityEnable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, TopsptiActivityKind kind)¶

enable collection of a specific kind of activity record on specific engine

Example:

TopsptiResult ret = EngineActivityEnable(TOPSPTI_ENGINE_CDMA,
    TopsptiGCUCoord{0, 0, 0, 0}, TOPSPTI_ACTIVITY_DMA_BUSY);

Parameters

engine – engine type to enable collecting
coord – engine coordinate to enable collecting
kind – the kind of activity record to enable collecting

Returns

TopsptiResult

TopsptiResult EngineActivityDisable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, TopsptiActivityKind kind)¶

disable collection of a specific kind of activity record on specific engine

Example:

TopsptiResult ret = EngineActivityDisable(TOPSPTI_ENGINE_CDMA,
    TopsptiGCUCoord{0, 0, 0, 0}, TOPSPTI_ACTIVITY_DMA_BUSY);

Parameters

engine – engine type to disable collecting
coord – engine coordinate to disable collecting
kind – the kind of activity record to disable collecting

Returns

TopsptiResult

TopsptiResult EngineActivityEnable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, const char *kind)¶

enable collection of a specific kind of activity record on specific engine

Example:

TopsptiResult ret = EngineActivityEnable(TOPSPTI_ENGINE_CDMA,
    TopsptiGCUCoord{0, 0, 0, 0}, "DMA Busy");

Parameters

engine – engine type to enable collecting
coord – engine coordinate to enable collecting
kind – the kind of activity record to enable collecting

Returns

TopsptiResult

TopsptiResult EngineActivityDisable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, const char *kind)¶

disable collection of a specific kind of activity record on specific engine

Example:

TopsptiResult ret = EngineActivityDisable(TOPSPTI_ENGINE_CDMA,
    TopsptiGCUCoord{0, 0, 0, 0}, "DMA Busy");

Parameters

engine – engine type to disable collecting
coord – engine coordinate to disable collecting
kind – the kind of activity record to disable collecting

Returns

TopsptiResult

TopsptiResult EventEnable(TopsptiEventKind kind)¶

enable collection of a specific kind of event record

Example:

TopsptiResult ret = EventEnable(TOPSPTI_EVENT_SIP_PMC_SIP_BUSY_WITH_WAIT);

Parameters: kind – the kind of event record to enable collecting
Returns: TOPSPTI_SUCCESS if success, TOPSPTI_ERROR_INVALID_EVENT if the specified event kind is unrecognized, and TOPSPTI_ERROR_INVALID_OPERATION if the event has been enabled already

TopsptiResult EventDisable(TopsptiEventKind kind)¶

disable collection of a specific kind of event record

Example:

TopsptiResult ret = EventDisable(TOPSPTI_EVENT_SIP_PMC_SIP_BUSY_WITH_WAIT);

Parameters: kind – the kind of event record to disable collecting
Returns: TOPSPTI_SUCCESS if success, TOPSPTI_ERROR_INVALID_EVENT if the specified event kind is unrecognized, and TOPSPTI_ERROR_INVALID_OPERATION if the event has been disabled already

TopsptiResult EventEnable(const char *kind)¶

enable collection of a specific kind of event record

Example:

TopsptiResult ret = EventEnable("SIP Busy With Wait");

Parameters: kind – the kind of event record to enable collecting
Returns: TopsptiResult

TopsptiResult EventDisable(const char *kind)¶

disable collection of a specific kind of event record

Example:

TopsptiResult ret = EventDisable("SIP Busy With Wait");

Parameters: kind – the kind of event record to disable collecting
Returns: TopsptiResult

TopsptiResult EngineEventEnable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, TopsptiEventKind kind)¶

enable collection of a specific kind of event record on specific engine

Example:

TopsptiResult ret = EngineEventEnable(TOPSPTI_ENGINE_SIP_PMC,
    TopsptiGCUCoord{0, 0, 0, 0}, TOPSPTI_EVENT_SIP_PMC_SIP_BUSY_WITH_WAIT);

Parameters

engine – engine type to enable collecting
coord – engine coordinate to enable collecting
kind – the kind of event record to enable collecting

Returns

TopsptiResult

TopsptiResult EngineEventDisable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, TopsptiEventKind kind)¶

disable collection of a specific kind of event record on specific engine

Example:

TopsptiResult ret = EngineEventDisable(TOPSPTI_ENGINE_SIP_PMC,
    TopsptiGCUCoord{0, 0, 0, 0}, TOPSPTI_EVENT_SIP_PMC_SIP_BUSY_WITH_WAIT);

Parameters

engine – engine type to disable collecting
coord – engine coordinate to disable collecting
kind – the kind of event record to disable collecting

Returns

TopsptiResult

TopsptiResult EngineEventEnable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, const char *kind)¶

enable collection of a specific kind of event record on specific engine

Example:

TopsptiResult ret = EngineEventEnable(TOPSPTI_ENGINE_SIP_PMC,
    TopsptiGCUCoord{0, 0, 0, 0}, "SIP Busy With Wait");

Parameters

engine – engine type to enable collecting
coord – engine coordinate to enable collecting
kind – the kind of event record to enable collecting

Returns

TopsptiResult

TopsptiResult EngineEventDisable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, const char *kind)¶

disable collection of a specific kind of event record on specific engine

Example:

TopsptiResult ret = EngineEventDisable(TOPSPTI_ENGINE_SIP_PMC,
    TopsptiGCUCoord{0, 0, 0, 0}, "SIP Busy With Wait");

Parameters

engine – engine type to disable collecting
coord – engine coordinate to disable collecting
kind – the kind of event record to disable collecting

Returns

TopsptiResult

TopsptiResult EngineMetricEnable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, TopsptiMetricKind kind)¶

enable collection of a specific kind of metrics record on specific engine

Example:

TopsptiResult ret = EngineMetricEnable(TOPSPTI_ENGINE_SIP,
    TopsptiGCUCoord{0, 0, 0, 0}, TOPSPTI_METRIC_SIP_BUSY_EFFICIENCY);

Parameters

engine – engine type to enable collecting
coord – engine coordinate to enable collecting
kind – the kind of metrics record to enable collecting

Returns

TopsptiResult

TopsptiResult EngineMetricDisable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, TopsptiMetricKind kind)¶

disable collection of a specific kind of metrics record on specific engine

Example:

TopsptiResult ret = EngineMetricDisable(TOPSPTI_ENGINE_SIP,
    TopsptiGCUCoord{0, 0, 0, 0}, TOPSPTI_METRIC_SIP_BUSY_EFFICIENCY);

Parameters

engine – engine type to disable collecting
coord – engine coordinate to disable collecting
kind – the kind of metrics record to disable collecting

Returns

TopsptiResult

TopsptiResult EngineMetricEnable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, const char *kind)¶

enable collection of a specific kind of metrics record on specific engine

Example:

TopsptiResult ret = EngineMetricEnable(TOPSPTI_ENGINE_SIP,
    TopsptiGCUCoord{0, 0, 0, 0}, "SIP/BUSY_EFFICIENCY");

Parameters

engine – engine type to enable collecting
coord – engine coordinate to enable collecting
kind – the kind of metrics record to enable collecting

Returns

TopsptiResult

TopsptiResult EngineMetricDisable(TopsptiEngineKind engine, const TopsptiGCUCoord &coord, const char *kind)¶

disable collection of a specific kind of metrics record on specific engine

Example:

TopsptiResult ret = EngineMetricDisable(TOPSPTI_ENGINE_SIP,
    TopsptiGCUCoord{0, 0, 0, 0}, "SIP/BUSY_EFFICIENCY");

Parameters

engine – engine type to disable collecting
coord – engine coordinate to disable collecting
kind – the kind of metrics record to disable collecting

Returns

TopsptiResult

TopsptiResult Config(const TopsptiProfileConfig &config)¶

configure profiling

Example:

TopsptiProfileConfig config;
config.output = "/tmp/test.data";
TopsptiResult ret = Config(config);

Parameters: config – software profiling configuration
Returns: TOPSPTI_SUCCESS

TopsptiResult Process(const char *path)¶

parse raw profiling data from file and compute profiling results

Parameters: path – file path to process from
Returns: TopsptiResult

TopsptiResult Query(RawStrVec *results, const char *table, const char *column)¶

get the profiling string type results depends on table and column

Parameters

results – [out] the profiling results
table – table name from vpd.
column – column name form vpd.

Returns

TopsptiResult

TopsptiResult Query(std::vector<uint64_t> *results, const char *table, const char *column)¶

get the profiling int type results depends on table and column

Parameters

results – [out] the profiling results
table – table name from vpd.
column – column name form vpd.

Returns

TopsptiResult

TopsptiResult Query(::topspti::database::DataBase *&db)¶

get the profiling results of database proto format

Parameters: db – [out] profiling results
Returns: TopsptiResult

1.2. Misc¶

This section describes the TOPSPTI misc api.

class TopsptiGCUCoord¶: #include <topspti_obj.h>

engine coordinate to be configured

class TopsptiProfileConfig¶: #include <topspti_obj.h>

profiling software configuration