Functions
This section describes benchmarking library functions.
NvpGetTimeMark
This API returns an opaque timestamp in a safe and efficient manner under out-of-order execution in the target platform. The given timestamp is to be understood by NvPlayfair library only.
/* Inputs
* None
*
* Output
* uint64_t Opaque timestamp value
*/
static inline uint64_t
NvpGetTimeMark(void);
/* Example Usage */
uint64_t timeMark;
timeMark = NvpGetTimeMark();
NvpConvertTimeMarkToNsec
This API converts the opaque time-mark value to nsec timestamp. Note that, in ARM architecture, the function assumes that 1-cycle = 32-nsec which is true for the Tegra counters running at the frequency of 31.25-MHz.
/* Inputs
* timeMark 64-bit variable containing the opaque time-mark value
*
* Output
* uint64_t Flat timestamp value in nsec
*/
static inline uint64_t
NvpConvertTimeMarkToNsec(uint64_t timeMark);
/* Example Usage */
uint64_t timestamp_ns;
timestamp_ns = NvpConvertTimeMarkToNsec(NvpGetTimeMark());
NvpConstructPerfData
This is the primary function for populating a given NvpPerfData_t* object. It allocates necessary memory for internal buffers based on the given num. of samples and stores the given information for internal book-keeping.
/* Inputs
* perfData An NvpPerfData_t* object
* numOfSamples An integer specifying the total number of samples
* that can be stored in the NvpPerfData_t* object
* filename A character string specifying the name of a file
* which can be used to save the performance data
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NO_SAMPLES Call failed because the numOfSamples was zero
* NVP_FAIL_NULLPTR Call failed because one of the input pointers was NULL
* NVP_FAIL_ALLOC Call failed because the library could not allocate memory
*/
NvpStatus_t
NvpConstructPerfData(NvpPerfData_t *perfData,
uint32_t numOfSamples,
char const *filename);
/* Example Usage */
NvpPerfData_t perfData;
uint32_t numOfSamples = 1000U;
char const *filename = "myLatencyData.csv";
NVP_CHECKERR_EXIT(NvpConstructPerfData(&perfData, numOfSamples, filename);
NvpDestroyPerfData
This is a complementary function to NvpConstructPerfData; it can be used to free up all resources associated with the given NvpPerfData_t* object. It should be called once the user is done with the object.
/* Inputs
* perfData An NvpPerfData_t* object
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because the input pointer was NULL
*/
NvpStatus_t
NvpDestroyPerfData(NvpPerfData_t *perfData);
/* Example Usage */
NVP_CHECKERR_EXIT(NvpDestroyPerfData(&perfData));
NvpRecordSample
This is a complementary function to NvpConstructPerfData; it can be used to free up all resources associated with the given NvpPerfData_t* object. It should be called once the user is done with the object.
/* Inputs
* perfData An NvpPerfData_t* object
* sampleStartTimeMark 64-bit time-mark value (as returned by NvpGetTimeMark() API);
* specifying the start time of the latency sample
* sampleEndTimeMark 64-bit time-mark value (as returned by NvpGetTimeMark() API);
* specifying the end time of the latency sample
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because one of the input pointers was NULL
* NVP_FAIL_LOGGING_STOPPED Call failed because data logging has been stopped in the library
* NVP_FAIL_NO_INIT Call failed because the given perfData object had not been initialized
*/
NvpStatus_t
NvpRecordSample(NvpPerfData_t *perfData,
uint64_t sampleStartTimeMark,
uint64_t sampleEndTimeMark);
/* Example Usage */
uint64_t startTimeMark, endTimeMark;
startTimeMark = NvpGetTimeMark();
/* <Instrumented-Code> */
endTimeMark = NvpGetTimeMark();
/* Assuming that perfData object has been properly initialized */
NVP_CHECKERR_EXIT(NvpRecordSample(&perfData, startTimeMark, endTimeMark));
NvpDumpData
This API can be used to record the data gathered (up-till the moment when this call is made) in NvpPerfData_t* object into a file in the file-system. The name of the file is taken from the object itself; as provided at the time of object initialization via NvpConstructPerfData API.
/* Inputs
* perfData An NvpPerfData_t* object
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because the input pointer was NULL
* NVP_FAIL_NO_INIT Call failed because the given perfData object had not been initialized
*/
NvpStatus_t
NvpDumpData(NvpPerfData_t *perfData);
/* Example Usage */
NVP_CHECKERR_EXIT(NvpDumpData(&perfData));
NvpCalcStats
This API can be used to record the data gathered (up-till the moment when this call is made) in NvpPerfData_t* object into a file in the file-system. The name of the file is taken from the object itself; as provided at the time of object initialization via NvpConstructPerfData API.
/* Inputs
* perfData An NvpPerfData_t* object
* stats An NvpPerfStats_t object in which the stats calculated for
* perfData will be recorded and reported
* unit An NvpTimeUnit_t variable indicating the time-unit in which
* the stats should be reported
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because the input pointer was NULL
* NVP_FAIL_NO_SAMPLES Call failed because the given perfData object did not contain
* any latency samples
* NVP_FAIL_INVALID_UNIT Call failed because the specified time-unit is not understood
* by the library
*/
NvpStatus_t
NvpCalcStats(NvpPerfData_t *perfData,
NvpPerfStats_t *stats,
NvpTimeUnits_t unit);
/* Example Usage */
NvpPerfStats_t stats;
NvpTimeUnits_t unit = USEC;
NVP_CHECKERR_EXIT(NvpCalcStats(&perfData, &stats, unit));
NvpPrintStats
This API can be used to print a report on the console / system logger about the statistics calculated for the given perf. data object. It can be very handy to get quick insight into the data w/o resorting to detailed offline analysis.
/* Inputs
* perfData An NvpPerfData_t* object
* stats An NvpPerfStats_t object containing the stats already calculated
* for the given perf. data object. If this argument is NULL, the API
* will first calculate stats for the perf. data by invoking
* NvpCalcStats() internally
* unit An NvpTimeUnit_t variable indicating the time-unit in which
* the stats should be reported
* msg A character string which should be printed alongside the perf. report
* csv A boolean flag. If true, it forces the API to print the report in CSV
* (comma separated values) format
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because the input pointer was NULL
* NVP_FAIL_NO_SAMPLES Call failed because the given perfData object did not contain
* any latency samples
* NVP_FAIL_INVALID_UNIT Call failed because the specified time-unit is not understood
* by the library
*/
NvpStatus_t
NvpPrintStats(NvpPerfData_t *perfData,
NvpPerfStats_t *stats,
NvpTimeUnits_t unit,
char const *msg,
bool csv);
/* Example Usage */
NvpTimeUnits_t unit = USEC;
NVP_CHECKERR_EXIT(NvpPrintStats(&perfData, NULL, unit, "Execution Latencies", false));
NvpPrintStatsExt
NvpPrintStats
API and provides additional
arguments to specify the receiver of statical report, as well as an option to save
the report to a file in target./* Inputs
* perfData An NvpPerfData_t* object
* stats An NvpPerfStats_t object containing the stats already calculated
* for the given perf. data object. If this argument is NULL, the API
* will first calculate stats for the perf. data by invoking
* NvpCalcStats() internally
* unit An NvpTimeUnit_t variable indicating the time-unit in which
* the stats should be reported
* msg A character string which should be printed alongside the perf. report
* csv A boolean flag. If true, it forces the API to print the report in CSV
* (comma separated values) format
* logBackend An enum of type NvpLogBackend_t; specifying the receiver of report
* reportFilename A character string; specifying the name of the file in which the report
* should be saved. Can be NULL; to skip saving the report to file
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because the input pointer was NULL
* NVP_FAIL_NO_SAMPLES Call failed because the given perfData object did not contain
* any latency samples
* NVP_FAIL_INVALID_UNIT Call failed because the specified time-unit is not understood
* by the library
* NVP_FAIL_INVALID_LOG_BACKEND
* The specified backend to receive the report is not recognized
* by the library
*/
NvpStatus_t
NvpPrintStats(NvpPerfData_t *perfData,
NvpPerfStats_t *stats,
NvpTimeUnits_t unit,
char const *msg,
bool csv,
NvpLogBackend_t logBackend,
char const *reportFilename);
/* Example Usage */
NvpTimeUnits_t unit = USEC;
NvpLogBackend_t backend = CONSOLE;
NVP_CHECKERR_EXIT(NvpPrintStatsExt(&perfData, NULL, unit, "Execution Latencies", false, backend, "perfSummary.txt"));
NvpAggregatePerfData
NvpPerfData_t
objects, provided as input to the API in an array
and into a single NvpPerfData_t
object that is populated by the API
as output. The timestamp of each sample in the aggregated data structure is taken
from the timestamp of the respective sample in the first data structure in the input
perf-data array (that is, inputPerfDataArray[0]
in the arguments
below). The input perf. data structures must contain the same number of
samples./* Inputs
* netPerfData An NvpPerfData_t* object; appropriately initialized. The API will
* populate this data-structure with accumulated latencies for each
* sample in the input data-structures
* inputPerfDataArray An array of NvpPerfData_t* pointers; containing references to the
* input perf data-structures which need to be aggregated
* numOfPerfDataObjs Integer specifying the num. of elements in the inputPerfDataArray
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because one of the input pointers was NULL
* NVP_FAIL_NOINIT Call failed because the output "netPerfData" structure is not initialized
* NVP_FAIL_SAMPLE_COUNT_MISMATCH
* Call failed because the input perf. data objects do not contain equal
* number of samples
*/
NvpStatus_t
NvpAggregatePerfData(NvpPerfData_t *netPerfData,
NvpPerfStats_t **inputPerfDataArray,
uint32_t numOfPerfDataObjs);
/* Example Usage */
#define NUM_OF_PERF_DATA_OBJS (2U)
NvpPerfData_t netPerfData, perfData1, perfData2;
NvpPerfData_t* inputPerfDataArray[NUM_OF_PERF_DATA_OBJS];
NVP_CHECKERR_EXIT(NvpConstructPerfData(&netPerfData, ...));
/* Code to initialize and gather latencies into perfData1, perfData2 */
...
inputPerfDataArray[0] = &perfData1;
inputPerfDataArray[1] = &perfData2;
NVP_CHECKERR_EXIT(NvpAggregatePerfData(&netPerfData, inputPerfDataArray, NUM_OF_PERF_DATA_OBJS));
NvpRateLimitInit
This API can be used to initialize an NvpRateLimitInfo_t* object with the information required to enforce a desired periodicity to the target benchmark.
/* Inputs
* rtInfo An NvpRateLimitInfo_t* object
* fps 32-bi variable specifying the rate-limit for the benchmark in
* frames-per-sec. A value of 0 is acceptable for this argument;
* which is taken to mean that benchmark should not be rate-limited
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because the input pointer was NULL
*/
NvpStatus_t
NvpRateLimitInit(NvpRateLimitInfo_t *rtInfo,
uint32_t fps);
/* Example Usage */
uint32_t fps = 30;
NvpRateLimitInfo_t rtInfo;
NVP_CHECKERR_EXIT(NvpRateLimitInit(&rtInfo, fps));
NvpMarkPeriodicExecStart
This is a complementary API that must be invoked just before the benchmark is about to enter periodic execution phase. When this API is invoked, the library will internally calculate a timestamp in usec and store it as the start time of the first period of the calling benchmark inside the given rtInfo object. This start time value is then used to calculate the boundaries for all the subsequent periods of the benchmark.
/* Inputs
* rtInfo An NvpRateLimitInfo_t* object
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because the input pointer was NULL
*/
NvpStatus_t
NvpMarkPeriodicExecStart(NvpRateLimitInfo_t *rtInfo);
/* Example Usage */
NVP_CHECKERR_EXIT(NvpMarkPeriodicExecStart(&rtInfo));
NvpRateLimitWait
This API can be used to wait till the start of next period during the steady-state execution of the benchmark. Internally, when this API is called, it makes the library capture a timestamp in usec and use it to calculate the time remaining till the beginning of the next period of the benchmark. If the remaining time is non-negative, then a sleep is invoked for the respective duration.
/* Inputs
* rtInfo An NvpRateLimitInfo_t* object
*
* Output (NvpStatus_t)
* NVP_PASS The API call completed successfully
* NVP_FAIL_NULLPTR Call failed because the input pointer was NULL
*/
NvpStatus_t
NvpRateLimitWait(NvpRateLimitInfo_t *rtInfo);
/* Example Usage */
NVP_CHECKERR_EXIT(NvpRateLimitWait(&rtInfo));
NvpCheckLibVersion
/* Inputs
* None
*
* Output (NvpStatus_t)
* NVP_PASS Version match was successful
* NVP_FAIL_VERSION_MISMATCH Library version does not match between benchmark
* code and library runtime
*/
NvpStatus_t
NvpCheckLibVersion(void);
/* Example Usage */
NVP_CHECKERR_EXIT(NvpCheckLibVersion());