statUsage/statUsage_example.c

Reference Documentation

Platform
Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.10
Napatech Software Suite: statUsage/statUsage_example.c
statUsage/statUsage_example.c

Description

This source file is an example of how to use the statistics stream interface in NTAPI to read hostbuffer usage statistics.

The following NTAPI functions are used:


Prerequisites

A working system is needed.

Program flow

The following is required to use the statistics stream interface in NTAPI:

  • #include/nt.h - Applications/Tools only need to include nt.h to obtain prototypes, macros etc. from NTAPI.
  • NT_Init(NTAPI_VERSION) - Initialize the NTAPI library. NTAPI_VERSION is a define that describes the version of the API described in the header files included by nt.h. NT_Init() will ask the NTAPI library to convert return data to the NTAPI_VERSION if possible. This will ensure that applications can run on NTAPI libraries of newer versions.
  • NT_StatOpen() - Open an statistics stream.
  • NT_StatRead() - Read usage statistics for the chosen stream ID.
  • NT_StatClose() - Close the stream when terminating.
  • NT_Done() - Close down the NTAPI library.
  • NT_ExplainError() - Explain an error code returned by NTAPI functions.

/*
*
* Copyright 2023 Napatech A/S. All Rights Reserved.
*
* 1. Copying, modification, and distribution of this file, or executable
* versions of this file, is governed by the terms of the Napatech Software
* license agreement under which this file was made available. If you do not
* agree to the terms of the license do not install, copy, access or
* otherwise use this file.
*
* 2. Under the Napatech Software license agreement you are granted a
* limited, non-exclusive, non-assignable, copyright license to copy, modify
* and distribute this file in conjunction with Napatech SmartNIC's and
* similar hardware manufactured or supplied by Napatech A/S.
*
* 3. The full Napatech Software license agreement is included in this
* distribution, please see "NP-0405 Napatech Software license
* agreement.pdf"
*
* 4. Redistributions of source code must retain this copyright notice,
* list of conditions and the following disclaimer.
*
* THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES, EXPRESS OR
* IMPLIED, AND NAPATECH DISCLAIMS ALL IMPLIED WARRANTIES INCLUDING ANY
* IMPLIED WARRANTY OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, OR OF
* FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT NOT PROHIBITED BY
* APPLICABLE LAW, IN NO EVENT SHALL NAPATECH BE LIABLE FOR PERSONAL INJURY,
* OR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES WHATSOEVER,
* INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, CORRUPTION OR
* LOSS OF DATA, FAILURE TO TRANSMIT OR RECEIVE ANY DATA OR INFORMATION,
* BUSINESS INTERRUPTION OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, ARISING
* OUT OF OR RELATED TO YOUR USE OR INABILITY TO USE NAPATECH SOFTWARE OR
* SERVICES OR ANY THIRD PARTY SOFTWARE OR APPLICATIONS IN CONJUNCTION WITH
* THE NAPATECH SOFTWARE OR SERVICES, HOWEVER CAUSED, REGARDLESS OF THE THEORY
* OF LIABILITY (CONTRACT, TORT OR OTHERWISE) AND EVEN IF NAPATECH HAS BEEN
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME JURISDICTIONS DO NOT ALLOW
* THE EXCLUSION OR LIMITATION OF LIABILITY FOR PERSONAL INJURY, OR OF
* INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION MAY NOT APPLY TO YOU.
*
*
*/
/**
* @example statUsage/statUsage_example.c
* @section statUsage_example_description Description
*
* This source file is an example of how to use the @ref StatStream
* "statistics stream" interface in NTAPI to read hostbuffer usage
* statistics.
*
* The following NTAPI functions are used:
* - @ref NT_Init()
* - @ref NT_StatOpen()
* - @ref NT_StatRead()
* - @ref NT_StatClose()
* - @ref NT_Done()
* - @ref NT_ExplainError()
*
* <hr>
* @section statUsage_example_prerequisites Prerequisites
* A working system is needed.
*
* @section statUsage_example_flow Program flow
* @{
* The following is required to use the @ref StatStream
* "statistics stream" interface in NTAPI:
* - \#include/nt.h - Applications/Tools only need to include @ref
* nt.h to obtain prototypes, macros etc. from NTAPI.
* - @ref NT_Init(@ref NTAPI_VERSION) - Initialize the NTAPI
* library. @ref NTAPI_VERSION is a define that describes the version
* of the API described in the header files included by @ref
* nt.h. NT_Init() will ask the NTAPI library to convert return data
* to the @ref NTAPI_VERSION if possible. This will ensure that
* applications can run on NTAPI libraries of newer versions.
* - @ref NT_StatOpen() - Open an statistics stream.
* - @ref NT_StatRead() - Read usage statistics for the chosen stream ID.
* - @ref NT_StatClose() - Close the stream when terminating.
* - @ref NT_Done() - Close down the NTAPI library.
* - @ref NT_ExplainError() - Explain an error code returned by NTAPI functions.
*
*<hr>
* @}
*/
// Include this in order to access the Napatech API
#include <nt.h>
#if defined(__linux__) || defined(__FreeBSD__)
#include <unistd.h> // sleep()
#include <signal.h>
#elif defined(WIN32) || defined (WIN64)
#include <winsock2.h> // Sleep()
#endif
#include <argparse.h>
int appRunning=1; // The application will run as long as appRunning==1
/**
* Print command line info
*/
static const char *usageText[] = {
"Syntax:\n"
"statUsage_example [-h][-s <stream ID>]\n"
"\nCommands:\n",
NULL};
static int opt_streamid = -1;
/**
* Table of valid options.
*/
struct argparse_option arg_options[] = {
OPT_INTEGER('s', "streamid", &opt_streamid, "Stream ID", NULL, 0, 0, "streamid"),
};
/**
* The function called when user is pressing CTRL-C
*/
#if defined(WIN32) || defined (WIN64)
static BOOL WINAPI StopApplication(int sig)
#else
static void StopApplication(int sig)
#endif
{
#ifdef WIN32
// Force the application to stop.
return TRUE;
#else
if (sig == SIGINT)
// Force the application to stop.
#endif
}
int main(int argc, const char *argv[])
{
NtStatStream_t hStatStream; // Statistics stream handle
NtStatistics_t hStat; // Stat handle.
char errorBuffer[NT_ERRBUF_SIZE]; // Error buffer
int status; // Status variable
struct argparse argparse;
printf("\nNapatech example: Display hostbuffer usage\n");
printf("--------------------------------------------------------------------------------\n\n");
// Register ctrl+c handler so we are able to stop again
#if defined(WIN32) || defined (WIN64)
SetConsoleCtrlHandler((PHANDLER_ROUTINE)StopApplication, TRUE);
#else
struct sigaction newaction; // Ctrl+c signal handler container
memset(&newaction, 0, sizeof(newaction));
newaction.sa_handler = StopApplication;
if (sigaction(SIGINT, &newaction, NULL) < 0) {
fprintf(stderr, "Failed to register SIGINT sigaction.\n");
exit(-1);
}
#endif
// Read the command line options
argparse_init(&argparse, arg_options, usageText, 0);
argparse_parse(&argparse, argc, argv);
if (opt_streamid == -1) {
// If no streamid is specefied, then exit with an error
fprintf(stderr, "ERROR: Stream ID must be specified\n\n");
return 1;
}
if (opt_streamid > 255) {
// If streamid is to large, then exit with an error
fprintf(stderr, "ERROR: Stream ID must be less or equal to 255\n\n");
return 1;
}
// Initialize the NTAPI library and thereby check if NTAPI_VERSION can be used together with this library
if ((status = NT_Init(NTAPI_VERSION)) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_Init() failed: %s\n", errorBuffer);
return -1;
}
// Open the stat stream
if ((status = NT_StatOpen(&hStatStream, "ExampleStatUsage")) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_StatOpen() failed: %s\n", errorBuffer);
return -1;
}
// Read usage data
while (appRunning == 1) {
uint32_t hbCount;
// Read usage data for the chosen stream ID
hStat.u.usageData_v0.streamid = (uint8_t)opt_streamid;
if ((status = NT_StatRead(hStatStream, &hStat)) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_StatRead() failed: %s\n", errorBuffer);
return -1;
}
// Print the usage data for each hostbuffer used by the chosen stream ID
printf("Number of hostbuffers used by stream ID %u: %u\n", opt_streamid, hStat.u.usageData_v0.data.numHostBufferUsed);
printf("================================================================================\n");
for (hbCount = 0; hbCount < hStat.u.usageData_v0.data.numHostBufferUsed; hbCount++) {
// The hostbuffer is used by this adapter
printf("Adapter number: %u\n", hStat.u.usageData_v0.data.hb[hbCount].adapterNo);
// The percentage of the onbord sdram buffer allocated for this hostbuffer that is used
printf("SDRAM fill level: %3u \%%\n", (uint32_t)((100 * hStat.u.usageData_v0.data.hb[hbCount].onboardBuffering.used) /
// The size of the onbord sdram buffer allocated for this hostbuffer
printf("Onbord buffer size: %6llu MByte\n", (long long unsigned int)(hStat.u.usageData_v0.data.hb[hbCount].onboardBuffering.size)/1024/1024);
// The size of the hostbuffer
printf("Hostbuffer size: %6llu MByte\n", (long long unsigned int)(hStat.u.usageData_v0.data.hb[hbCount].hostBufferSize)/1024/1024);
// The numanode that the hostbuffer is allocated from.
printf("Numa node: %2u\n", hStat.u.usageData_v0.data.hb[hbCount].numaNode);
// Number of streams (apps) that are using the hostbuffer
printf("Number of connected streams: %3u\n", hStat.u.usageData_v0.data.hb[hbCount].numStreams);
// The hostbuffer status
// deQueued: Number of bytes available or in use by the streams
// enQueued: Number of bytes available to the host buffer handler
// enQueuedAdapter: Number of bytes currently in the adapter
printf("\nDequeued: %6llu, Enqueued driver: %6llu, Enqueued adapter: %6llu\n", (long long unsigned int)hStat.u.usageData_v0.data.hb[hbCount].deQueued/1024,
(long long unsigned int)(hStat.u.usageData_v0.data.hb[hbCount].enQueued-
hStat.u.usageData_v0.data.hb[hbCount].enQueuedAdapter)/1024,
(long long unsigned int)hStat.u.usageData_v0.data.hb[hbCount].enQueuedAdapter/1024);
// Number of received and dropped packet for this hostbuffer
printf("Received packets: %8llu, Dropped packets: %8llu\n", (long long unsigned int)hStat.u.usageData_v0.data.hb[hbCount].stat.rx.frames,
(long long unsigned int)hStat.u.usageData_v0.data.hb[hbCount].stat.drop.frames);
printf("--------------------------------------------------------------------------------\n\n");
}
// Sleep 1 sec
#if defined(__linux__) || defined(__FreeBSD__)
sleep(1);
#elif defined(WIN32) || defined (WIN64)
Sleep(1000); // sleep 1000 milliseconds = 1 second
#endif
}
// Close the stat stream
if ((status = NT_StatClose(hStatStream)) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_StatClose() failed: %s\n", errorBuffer);
return -1;
}
// Close down the NTAPI library
printf("Done.\n");
return 0;
}