event_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/event/event_example.c Source File
event_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 event/event_example.c
46  * @section event_example_description Description
47  *
48  * This source file is an example of how to use the @ref EventStream
49  * "Event stream" interface in NTAPI.
50  *
51  * The following NTAPI functions are used:
52  * - @ref NT_Init()
53  * - @ref NT_EventOpen()
54  * - @ref NT_EventRead()
55  * - @ref NT_EventClose()
56  * - @ref NT_Done()
57  * - @ref NT_ExplainError()
58  *
59  * <hr>
60  * @section event_example_prerequisites Prerequisites
61  * A working system is needed with an Napatech accelerator as adapter 0.
62  *
63  * @section event_example_flow Program flow
64  * @{
65  * The following is required to use the @ref EventStream "Event stream"
66  * interface in NTAPI:
67  * - \#include/nt.h - Applications/Tools only need to include @ref
68  * nt.h to obtain prototypes, macros etc. from NTAPI.
69  * - @ref NT_Init(@ref NTAPI_VERSION) - Initialize the NTAPI
70  * library. @ref NTAPI_VERSION is a define that describes the version
71  * of the API described in the header files included by @ref
72  * nt.h. NT_Init() will ask the NTAPI library to convert return data
73  * to the @ref NTAPI_VERSION if possible. This will ensure that
74  * applications can run on NTAPI libraries of newer versions.
75  * - @ref NT_EventOpen() - Open an event stream.
76  * - ForceAnEvent() - Trigger an event.
77  * - @ref NT_EventRead() - Read the event information.
78  * - @ref NT_EventClose() - 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 /*
90  * This function will set the timestamp of adapter 0 which will trigger
91  * a configuration change done event.
92  */
93 static int ForceAnEvent(void)
94 {
95  NtConfigStream_t hConfigStream; // Config stream handle
96  NtConfig_t hConfig; // Config handle
97  char errorBuffer[NT_ERRBUF_SIZE]; // Error buffer
98  int status; // Status variable
99 
100  // Open a config stream. This will be used to change the timestamp
101  // of the adapter causing it to generate an event.
102  if ((status = NT_ConfigOpen(&hConfigStream, "CfgStream")) != NT_SUCCESS) {
103  // Get the status code as text
104  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
105  fprintf(stderr, "NT_ConfigOpen() failed: %s\n", errorBuffer);
106  return -1;
107  }
108 
109  printf("<<< Force an event. >>>\n");
110 
112  hConfig.u.timestampWrite.adapter=0; // On adapter 0
113  hConfig.u.timestampWrite.data.ts = 0; // set time to 0
114  hConfig.u.timestampWrite.data.bCurrent=0;// and don't use current OS time
115  // Write timestamp=0 to adapter 0
116  if ((status = NT_ConfigWrite(hConfigStream, &hConfig)) != NT_SUCCESS) {
117  // Get the status code as text
118  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
119  fprintf(stderr, "NT_ConfigWrite() failed: %s\n", errorBuffer);
120  return -1;
121  }
122 
123  // Close the config stream again
124  if ((status = NT_ConfigClose(hConfigStream)) != NT_SUCCESS) {
125  // Get the status code as text
126  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
127  fprintf(stderr, "NT_ConfigClose() failed: %s\n", errorBuffer);
128  return -1;
129  }
130 
131  return status;
132 }
133 
134 int main(void)
135 {
136  NtEventStream_t hEventStream; // Event stream handle
137  NtEvent_t hEvent; // Event handle
138  char errorBuffer[NT_ERRBUF_SIZE]; // Error buffer
139  int status; // Status variable
140  bool found = false;
141 
142  // Initialize the NTAPI library and thereby check if NTAPI_VERSION can be used together with this library
143  if ((status = NT_Init(NTAPI_VERSION)) != NT_SUCCESS) {
144  // Get the status code as text
145  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
146  fprintf(stderr, "NT_Init() failed: %s\n", errorBuffer);
147  return -1;
148  }
149 
150  printf("Generate an event and wait for the event before reading it.\n");
151 
152  // Open the event stream
153  if ((status = NT_EventOpen(&hEventStream, "ExampleEvent", NT_EVENT_SOURCE_CONFIG | NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE)) != NT_SUCCESS) {
154  // Get the status code as text
155  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
156  fprintf(stderr, "NT_EventOpen() failed: %s\n", errorBuffer);
157  return -1;
158  }
159 
160  if (ForceAnEvent() != NT_SUCCESS) {
161  return -1;
162  }
163 
164  while (1) {
165  // Wait for the events to occur.
166  if ((status = NT_EventRead(hEventStream, &hEvent, 10000)) != NT_SUCCESS) {
167  if (found) {
168  printf("No more events received within 10 seconds\n");
169  break;
170  }
171  else {
172  // Get the status code as text
173  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
174  fprintf(stderr, "NT_EventRead() failed: %s\n", errorBuffer);
175  return -1;
176  }
177  }
178 
179  // Print event info.
180  // As we have opened the event stream with the mask NT_EVENT_SOURCE_CONFIG | NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE
181  // only these to event will be received.
182  switch (hEvent.type) {
184  found = true;
185  // Some adapters will return this event when changing the adapter time
187  printf("Event received: Timestamp clock set: New time: %lld\n", (unsigned long long)hEvent.u.timeSyncStateMachineEvent.timeStampClock);
188  }
189  break;
191  found = true;
192  // Some adapters will return this event when changing the adapter time,
193  // then the command needs to be checked in order to see which command, that
194  // caused the event to be sent.
196  printf("Event received: Timestamp config change: New time: %lld\n", (unsigned long long)hEvent.u.configEvent.u.timestampWrite.data.ts);
197  }
198  else {
199  fprintf(stderr, ">>> Unexpected config change received %d.\n", hEvent.u.configEvent.parm);
200  }
201  break;
202  default:
203  fprintf(stderr, ">>> Unexpected event received %d.\n", hEvent.type);
204  break;
205  }
206  }
207 
208  // Close the event stream
209  if ((status = NT_EventClose(hEventStream)) != NT_SUCCESS) {
210  // Get the status code as text
211  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
212  fprintf(stderr, "NT_EventClose() failed: %s\n", errorBuffer);
213  return -1;
214  }
215 
216  // Close down the NTAPI library
217  NT_Done();
218 
219  printf("Done.\n");
220  return 0;
221 }