LinkTM-Capture-Software-12.15/Reference-Documentation/statUsage_example.c-Source-File

/*
 *
 * Copyright 2025 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 "NA-0009 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(WIN32) || defined (WIN64)
  #include <winsock2.h> // Sleep()
#else
  #include <unistd.h> // sleep()
  #include <signal.h>
  #include <stdatomic.h>
#endif

#include <stdlib.h>
#include <argparse.h>

#define MAX_NUM_STREAM_IDS (1*256)

#if defined(WIN32) || defined (WIN64)
static volatile int appRunning = 1; // The application will run as long as appRunning == 1
#else
static atomic_int appRunning = 1;   // The application will run as long as appRunning == 1
#endif

/**
  * 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_HELP(),
    OPT_INTEGER('s', "streamid", &opt_streamid, "Stream ID", NULL, 0, 0, "streamid"),
    OPT_END(),
};

/**
  * The function called when user is pressing CTRL-C
  */
#if defined(WIN32) || defined (WIN64)
static BOOL WINAPI StopApplication(int sig)
{
  (void) sig;
  appRunning = 0;
  return TRUE;
}
#else
static void StopApplication(int sig)
{
  if (sig == SIGINT)
    appRunning = 0;
}
#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(EXIT_FAILURE);
  }
#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 >= MAX_NUM_STREAM_IDS) {
    // If streamid is to large, then exit with an error
    fprintf(stderr, "ERROR: Stream ID must be less or equal to %d\n\n", MAX_NUM_STREAM_IDS);
    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.cmd=NT_STATISTICS_READ_CMD_USAGE_DATA_V0;
    hStat.u.usageData_v0.streamid = (uint8_t)opt_streamid;  // HB256: TODO:
    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",
             (unsigned)(100U * hStat.u.usageData_v0.data.hb[hbCount].onboardBuffering.used / hStat.u.usageData_v0.data.hb[hbCount].onboardBuffering.size));

      // 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");
    }

#if defined(WIN32) || defined (WIN64)
    Sleep(1000); // sleep 1000 milliseconds = 1 second
#else
    sleep(1);    // sleep 1 sec
#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
  NT_Done();

  printf("Done.\n");
  return 0;
}