statUsage_example.c Source File

Reference Documentation

Platform
Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.10
Napatech Software Suite: examples/statUsage/statUsage_example.c Source File
statUsage_example.c
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2023 Napatech A/S. All Rights Reserved.
4  *
5  * 1. Copying, modification, and distribution of this file, or executable
6  * versions of this file, is governed by the terms of the Napatech Software
7  * license agreement under which this file was made available. If you do not
8  * agree to the terms of the license do not install, copy, access or
9  * otherwise use this file.
10  *
11  * 2. Under the Napatech Software license agreement you are granted a
12  * limited, non-exclusive, non-assignable, copyright license to copy, modify
13  * and distribute this file in conjunction with Napatech SmartNIC's and
14  * similar hardware manufactured or supplied by Napatech A/S.
15  *
16  * 3. The full Napatech Software license agreement is included in this
17  * distribution, please see "NP-0405 Napatech Software license
18  * agreement.pdf"
19  *
20  * 4. Redistributions of source code must retain this copyright notice,
21  * list of conditions and the following disclaimer.
22  *
23  * THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES, EXPRESS OR
24  * IMPLIED, AND NAPATECH DISCLAIMS ALL IMPLIED WARRANTIES INCLUDING ANY
25  * IMPLIED WARRANTY OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, OR OF
26  * FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT NOT PROHIBITED BY
27  * APPLICABLE LAW, IN NO EVENT SHALL NAPATECH BE LIABLE FOR PERSONAL INJURY,
28  * OR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES WHATSOEVER,
29  * INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, CORRUPTION OR
30  * LOSS OF DATA, FAILURE TO TRANSMIT OR RECEIVE ANY DATA OR INFORMATION,
31  * BUSINESS INTERRUPTION OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, ARISING
32  * OUT OF OR RELATED TO YOUR USE OR INABILITY TO USE NAPATECH SOFTWARE OR
33  * SERVICES OR ANY THIRD PARTY SOFTWARE OR APPLICATIONS IN CONJUNCTION WITH
34  * THE NAPATECH SOFTWARE OR SERVICES, HOWEVER CAUSED, REGARDLESS OF THE THEORY
35  * OF LIABILITY (CONTRACT, TORT OR OTHERWISE) AND EVEN IF NAPATECH HAS BEEN
36  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME JURISDICTIONS DO NOT ALLOW
37  * THE EXCLUSION OR LIMITATION OF LIABILITY FOR PERSONAL INJURY, OR OF
38  * INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION MAY NOT APPLY TO YOU.
39  *
40  *
41 
42  */
43 
44 /**
45  * @example statUsage/statUsage_example.c
46  * @section statUsage_example_description Description
47  *
48  * This source file is an example of how to use the @ref StatStream
49  * "statistics stream" interface in NTAPI to read hostbuffer usage
50  * statistics.
51  *
52  * The following NTAPI functions are used:
53  * - @ref NT_Init()
54  * - @ref NT_StatOpen()
55  * - @ref NT_StatRead()
56  * - @ref NT_StatClose()
57  * - @ref NT_Done()
58  * - @ref NT_ExplainError()
59  *
60  * <hr>
61  * @section statUsage_example_prerequisites Prerequisites
62  * A working system is needed.
63  *
64  * @section statUsage_example_flow Program flow
65  * @{
66  * The following is required to use the @ref StatStream
67  * "statistics stream" interface in NTAPI:
68  * - \#include/nt.h - Applications/Tools only need to include @ref
69  * nt.h to obtain prototypes, macros etc. from NTAPI.
70  * - @ref NT_Init(@ref NTAPI_VERSION) - Initialize the NTAPI
71  * library. @ref NTAPI_VERSION is a define that describes the version
72  * of the API described in the header files included by @ref
73  * nt.h. NT_Init() will ask the NTAPI library to convert return data
74  * to the @ref NTAPI_VERSION if possible. This will ensure that
75  * applications can run on NTAPI libraries of newer versions.
76  * - @ref NT_StatOpen() - Open an statistics stream.
77  * - @ref NT_StatRead() - Read usage statistics for the chosen stream ID.
78  * - @ref NT_StatClose() - Close the stream when terminating.
79  * - @ref NT_Done() - Close down the NTAPI library.
80  * - @ref NT_ExplainError() - Explain an error code returned by NTAPI functions.
81  *
82  *<hr>
83  * @}
84  */
85 
86 // Include this in order to access the Napatech API
87 #include <nt.h>
88 
89 #if defined(__linux__) || defined(__FreeBSD__)
90  #include <unistd.h> // sleep()
91  #include <signal.h>
92 #elif defined(WIN32) || defined (WIN64)
93  #include <winsock2.h> // Sleep()
94 #endif
95 
96 #include <argparse.h>
97 
98 int appRunning=1; // The application will run as long as appRunning==1
99 
100 /**
101  * Print command line info
102  */
103 static const char *usageText[] = {
104  "Syntax:\n"
105  "statUsage_example [-h][-s <stream ID>]\n"
106  "\nCommands:\n",
107  NULL};
108 
109 static int opt_streamid = -1;
110 
111 /**
112  * Table of valid options.
113  */
115  OPT_HELP(),
116  OPT_INTEGER('s', "streamid", &opt_streamid, "Stream ID", NULL, 0, 0, "streamid"),
117  OPT_END(),
118 };
119 
120 /**
121  * The function called when user is pressing CTRL-C
122  */
123 #if defined(WIN32) || defined (WIN64)
124 static BOOL WINAPI StopApplication(int sig)
125 #else
126 static void StopApplication(int sig)
127 #endif
128 {
129 #ifdef WIN32
130  // Force the application to stop.
131  appRunning=0;
132  return TRUE;
133 #else
134  if (sig == SIGINT)
135  // Force the application to stop.
136  appRunning=0;
137 #endif
138 }
139 
140 int main(int argc, const char *argv[])
141 {
142  NtStatStream_t hStatStream; // Statistics stream handle
143  NtStatistics_t hStat; // Stat handle.
144  char errorBuffer[NT_ERRBUF_SIZE]; // Error buffer
145  int status; // Status variable
146  struct argparse argparse;
147 
148  printf("\nNapatech example: Display hostbuffer usage\n");
149  printf("--------------------------------------------------------------------------------\n\n");
150 
151  // Register ctrl+c handler so we are able to stop again
152 #if defined(WIN32) || defined (WIN64)
153  SetConsoleCtrlHandler((PHANDLER_ROUTINE)StopApplication, TRUE);
154 #else
155  struct sigaction newaction; // Ctrl+c signal handler container
156  memset(&newaction, 0, sizeof(newaction));
157  newaction.sa_handler = StopApplication;
158  if (sigaction(SIGINT, &newaction, NULL) < 0) {
159  fprintf(stderr, "Failed to register SIGINT sigaction.\n");
160  exit(-1);
161  }
162 #endif
163 
164  // Read the command line options
165  argparse_init(&argparse, arg_options, usageText, 0);
166  argparse_parse(&argparse, argc, argv);
167 
168  if (opt_streamid == -1) {
169  // If no streamid is specefied, then exit with an error
170  fprintf(stderr, "ERROR: Stream ID must be specified\n\n");
171  return 1;
172  }
173 
174  if (opt_streamid > 255) {
175  // If streamid is to large, then exit with an error
176  fprintf(stderr, "ERROR: Stream ID must be less or equal to 255\n\n");
177  return 1;
178  }
179 
180  // Initialize the NTAPI library and thereby check if NTAPI_VERSION can be used together with this library
181  if ((status = NT_Init(NTAPI_VERSION)) != NT_SUCCESS) {
182  // Get the status code as text
183  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
184  fprintf(stderr, "NT_Init() failed: %s\n", errorBuffer);
185  return -1;
186  }
187 
188  // Open the stat stream
189  if ((status = NT_StatOpen(&hStatStream, "ExampleStatUsage")) != NT_SUCCESS) {
190  // Get the status code as text
191  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
192  fprintf(stderr, "NT_StatOpen() failed: %s\n", errorBuffer);
193  return -1;
194  }
195 
196  // Read usage data
197  while (appRunning == 1) {
198  uint32_t hbCount;
199 
200  // Read usage data for the chosen stream ID
202  hStat.u.usageData_v0.streamid = (uint8_t)opt_streamid;
203  if ((status = NT_StatRead(hStatStream, &hStat)) != NT_SUCCESS) {
204  // Get the status code as text
205  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
206  fprintf(stderr, "NT_StatRead() failed: %s\n", errorBuffer);
207  return -1;
208  }
209 
210  // Print the usage data for each hostbuffer used by the chosen stream ID
211  printf("Number of hostbuffers used by stream ID %u: %u\n", opt_streamid, hStat.u.usageData_v0.data.numHostBufferUsed);
212  printf("================================================================================\n");
213  for (hbCount = 0; hbCount < hStat.u.usageData_v0.data.numHostBufferUsed; hbCount++) {
214  // The hostbuffer is used by this adapter
215  printf("Adapter number: %u\n", hStat.u.usageData_v0.data.hb[hbCount].adapterNo);
216 
217  // The percentage of the onbord sdram buffer allocated for this hostbuffer that is used
218  printf("SDRAM fill level: %3u \%%\n", (uint32_t)((100 * hStat.u.usageData_v0.data.hb[hbCount].onboardBuffering.used) /
219  hStat.u.usageData_v0.data.hb[hbCount].onboardBuffering.size));
220 
221  // The size of the onbord sdram buffer allocated for this hostbuffer
222  printf("Onbord buffer size: %6llu MByte\n", (long long unsigned int)(hStat.u.usageData_v0.data.hb[hbCount].onboardBuffering.size)/1024/1024);
223 
224  // The size of the hostbuffer
225  printf("Hostbuffer size: %6llu MByte\n", (long long unsigned int)(hStat.u.usageData_v0.data.hb[hbCount].hostBufferSize)/1024/1024);
226 
227  // The numanode that the hostbuffer is allocated from.
228  printf("Numa node: %2u\n", hStat.u.usageData_v0.data.hb[hbCount].numaNode);
229 
230  // Number of streams (apps) that are using the hostbuffer
231  printf("Number of connected streams: %3u\n", hStat.u.usageData_v0.data.hb[hbCount].numStreams);
232 
233  // The hostbuffer status
234  // deQueued: Number of bytes available or in use by the streams
235  // enQueued: Number of bytes available to the host buffer handler
236  // enQueuedAdapter: Number of bytes currently in the adapter
237  printf("\nDequeued: %6llu, Enqueued driver: %6llu, Enqueued adapter: %6llu\n", (long long unsigned int)hStat.u.usageData_v0.data.hb[hbCount].deQueued/1024,
238  (long long unsigned int)(hStat.u.usageData_v0.data.hb[hbCount].enQueued-
239  hStat.u.usageData_v0.data.hb[hbCount].enQueuedAdapter)/1024,
240  (long long unsigned int)hStat.u.usageData_v0.data.hb[hbCount].enQueuedAdapter/1024);
241 
242  // Number of received and dropped packet for this hostbuffer
243  printf("Received packets: %8llu, Dropped packets: %8llu\n", (long long unsigned int)hStat.u.usageData_v0.data.hb[hbCount].stat.rx.frames,
244  (long long unsigned int)hStat.u.usageData_v0.data.hb[hbCount].stat.drop.frames);
245 
246  printf("--------------------------------------------------------------------------------\n\n");
247  }
248 
249 
250  // Sleep 1 sec
251 #if defined(__linux__) || defined(__FreeBSD__)
252  sleep(1);
253 #elif defined(WIN32) || defined (WIN64)
254  Sleep(1000); // sleep 1000 milliseconds = 1 second
255 #endif
256  }
257 
258  // Close the stat stream
259  if ((status = NT_StatClose(hStatStream)) != NT_SUCCESS) {
260  // Get the status code as text
261  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
262  fprintf(stderr, "NT_StatClose() failed: %s\n", errorBuffer);
263  return -1;
264  }
265 
266  // Close down the NTAPI library
267  NT_Done();
268 
269  printf("Done.\n");
270  return 0;
271 }