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

This is a superset of the 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

This API can be used to accumulate latencies stored in multiple different 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

This API can be used to ensure that the library version used in the compiled benchmark code is the same as the version of the shared object file of the library runtime present on target.
/* 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());