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));

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));