event_example.c Source File

1 /*

2  *

3  * Copyright 2025 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 "NA-0009 Software License Agreement.pdf"

18  *

19  * 4. Redistributions of source code must retain this copyright notice,

20  * list of conditions and the following disclaimer.

21  *

22  * THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES, EXPRESS OR

23  * IMPLIED, AND NAPATECH DISCLAIMS ALL IMPLIED WARRANTIES INCLUDING ANY

24  * IMPLIED WARRANTY OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, OR OF

25  * FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT NOT PROHIBITED BY

26  * APPLICABLE LAW, IN NO EVENT SHALL NAPATECH BE LIABLE FOR PERSONAL INJURY,

27  * OR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES WHATSOEVER,

28  * INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, CORRUPTION OR

29  * LOSS OF DATA, FAILURE TO TRANSMIT OR RECEIVE ANY DATA OR INFORMATION,

30  * BUSINESS INTERRUPTION OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, ARISING

31  * OUT OF OR RELATED TO YOUR USE OR INABILITY TO USE NAPATECH SOFTWARE OR

32  * SERVICES OR ANY THIRD PARTY SOFTWARE OR APPLICATIONS IN CONJUNCTION WITH

33  * THE NAPATECH SOFTWARE OR SERVICES, HOWEVER CAUSED, REGARDLESS OF THE THEORY

34  * OF LIABILITY (CONTRACT, TORT OR OTHERWISE) AND EVEN IF NAPATECH HAS BEEN

35  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME JURISDICTIONS DO NOT ALLOW

36  * THE EXCLUSION OR LIMITATION OF LIABILITY FOR PERSONAL INJURY, OR OF

37  * INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION MAY NOT APPLY TO YOU.

38  *

39  *

40 

41  */

42 

43 /**

44  * @example event/event_example.c

45  * @section event_example_description Description

46  *

47  * This source file is an example of how to use the @ref EventStream

48  * "Event stream" interface in NTAPI.

49  *

50  * The following NTAPI functions are used:

51  * - @ref NT_Init()

52  * - @ref NT_EventOpen()

53  * - @ref NT_EventRead()

54  * - @ref NT_EventClose()

55  * - @ref NT_Done()

56  * - @ref NT_ExplainError()

57  *

58  * <hr>

59  * @section event_example_prerequisites Prerequisites

60  * A working system is needed with an Napatech accelerator as adapter 0.

61  *

62  * @section event_example_flow Program flow

63  * @{

64  * The following is required to use the @ref EventStream "Event stream"

65  * interface in NTAPI:

66  * - \#include/nt.h - Applications/Tools only need to include @ref

67  * nt.h to obtain prototypes, macros etc. from NTAPI.

68  * - @ref NT_Init(@ref NTAPI_VERSION) - Initialize the NTAPI

69  * library. @ref NTAPI_VERSION is a define that describes the version

70  * of the API described in the header files included by @ref

71  * nt.h. NT_Init() will ask the NTAPI library to convert return data

72  * to the @ref NTAPI_VERSION if possible. This will ensure that

73  * applications can run on NTAPI libraries of newer versions.

74  * - @ref NT_EventOpen() - Open an event stream.

75  * - ForceAnEvent() - Trigger an event.

76  * - @ref NT_EventRead() - Read the event information.

77  * - @ref NT_EventClose() - Close the stream when terminating.

78  * - @ref NT_Done() - Close down the NTAPI library.

79  * - @ref NT_ExplainError() - Explain an error code returned by NTAPI functions.

80  *

81  *<hr>

82  * @}

83  */

84 

85 // Include this in order to access the Napatech API

86 #include <nt.h>

87 

88 /*

89  * This function will set the timestamp of adapter 0 which will trigger

90  * a configuration change done event.

91  */

92 static int ForceAnEvent(void)

93 {

94  NtConfigStream_t hConfigStream; // Config stream handle

95  NtConfig_t hConfig; // Config handle

96  char errorBuffer[NT_ERRBUF_SIZE]; // Error buffer

97  int status; // Status variable

98 

99  // Open a config stream. This will be used to change the timestamp

100  // of the adapter causing it to generate an event.

101  if ((status = NT_ConfigOpen(&hConfigStream, "CfgStream")) != NT_SUCCESS) {

102  // Get the status code as text

103  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));

104  fprintf(stderr, "NT_ConfigOpen() failed: %s\n", errorBuffer);

105  return -1;

106  }

107 

108  printf("<<< Force an event. >>>\n");

109 

110  hConfig.parm=NT_CONFIG_PARM_ADAPTER_TIMESTAMP;

111  hConfig.u.timestampWrite.adapter=0; // On adapter 0

112  hConfig.u.timestampWrite.data.ts = 0; // set time to 0

113  hConfig.u.timestampWrite.data.bCurrent=0;// and don't use current OS time

114  // Write timestamp=0 to adapter 0

115  if ((status = NT_ConfigWrite(hConfigStream, &hConfig)) != NT_SUCCESS) {

116  // Get the status code as text

117  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));

118  fprintf(stderr, "NT_ConfigWrite() failed: %s\n", errorBuffer);

119  return -1;

120  }

121 

122  // Close the config stream again

123  if ((status = NT_ConfigClose(hConfigStream)) != NT_SUCCESS) {

124  // Get the status code as text

125  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));

126  fprintf(stderr, "NT_ConfigClose() failed: %s\n", errorBuffer);

127  return -1;

128  }

129 

130  return status;

131 }

132 

133 int main(void)

134 {

135  NtEventStream_t hEventStream; // Event stream handle

136  NtEvent_t hEvent; // Event handle

137  char errorBuffer[NT_ERRBUF_SIZE]; // Error buffer

138  int status; // Status variable

139  bool found = false;

140 

141  // Initialize the NTAPI library and thereby check if NTAPI_VERSION can be used together with this library

142  if ((status = NT_Init(NTAPI_VERSION)) != NT_SUCCESS) {

143  // Get the status code as text

144  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));

145  fprintf(stderr, "NT_Init() failed: %s\n", errorBuffer);

146  return -1;

147  }

148 

149  printf("Generate an event and wait for the event before reading it.\n");

150 

151  // Open the event stream

152  if ((status = NT_EventOpen(&hEventStream, "ExampleEvent", NT_EVENT_SOURCE_CONFIG | NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE)) != NT_SUCCESS) {

153  // Get the status code as text

154  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));

155  fprintf(stderr, "NT_EventOpen() failed: %s\n", errorBuffer);

156  return -1;

157  }

158 

159  if (ForceAnEvent() != NT_SUCCESS) {

160  return -1;

161  }

162 

163  while (1) {

164  // Wait for the events to occur.

165  if ((status = NT_EventRead(hEventStream, &hEvent, 10000)) != NT_SUCCESS) {

166  if (found) {

167  printf("No more events received within 10 seconds\n");

168  break;

169  }

170  else {

171  // Get the status code as text

172  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));

173  fprintf(stderr, "NT_EventRead() failed: %s\n", errorBuffer);

174  return -1;

175  }

176  }

177 

178  // Print event info.

179  // As we have opened the event stream with the mask NT_EVENT_SOURCE_CONFIG | NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE

180  // only these to event will be received.

181  switch (hEvent.type) {

182  case NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE:

183  found = true;

184  // Some adapters will return this event when changing the adapter time

185  if (hEvent.u.timeSyncStateMachineEvent.action == NT_EVENT_TIMESYNC_TIME_STAMP_CLOCK_SET) {

186  printf("Event received: Timestamp clock set: New time: %lld\n", (unsigned long long)hEvent.u.timeSyncStateMachineEvent.timeStampClock);

187  }

188  break;

189  case NT_EVENT_SOURCE_CONFIG:

190  found = true;

191  // Some adapters will return this event when changing the adapter time,

192  // then the command needs to be checked in order to see which command, that

193  // caused the event to be sent.

194  if (hEvent.u.configEvent.parm == NT_CONFIG_PARM_ADAPTER_TIMESTAMP) {

195  printf("Event received: Timestamp config change: New time: %lld\n", (unsigned long long)hEvent.u.configEvent.u.timestampWrite.data.ts);

196  }

197  else {

198  fprintf(stderr, ">>> Unexpected config change received %d.\n", hEvent.u.configEvent.parm);

199  }

200  break;

201  default:

202  fprintf(stderr, ">>> Unexpected event received %d.\n", hEvent.type);

203  break;

204  }

205  }

206 

207  // Close the event stream

208  if ((status = NT_EventClose(hEventStream)) != NT_SUCCESS) {

209  // Get the status code as text

210  NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));

211  fprintf(stderr, "NT_EventClose() failed: %s\n", errorBuffer);

212  return -1;

213  }

214 

215  // Close down the NTAPI library

216  NT_Done();

217 

218  printf("Done.\n");

219  return 0;

220 }