transmit_on_timestamp_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/net/transmit_on_timestamp/transmit_on_timestamp_example.c Source File
transmit_on_timestamp_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 net/transmit_on_timestamp/transmit_on_timestamp_example.c
46  * @section transmit_on_timestamp_example_description Description
47  *
48  * This source file is an example of how to transmit packets on timestamp
49  * using the packet interface in NTAPI. The example will transmit 100000
50  * packets with a size of 296 bytes from port 0 at a rate of approximately
51  * 5 Mb/s. The packet contains an incrementing 32bit pattern.
52  *
53  * The transmit on timestamp functionality is also available in segment mode.
54  * See the @ref net/transmit_segment/transmit_segment_example.c example code
55  * to see how to use the segment interface.
56  *
57  * The following NTAPI functions are used:
58  * - @ref NT_Init()
59  * - @ref NT_ConfigOpen()
60  * - @ref NT_ConfigRead()
61  * - @ref NT_ConfigWrite()
62  * - @ref NT_ConfigClose()
63  * - @ref NT_NetTxOpen()
64  * - @ref NT_NetTxGet()
65  * - @ref NT_NET_SET_PKT_TIMESTAMP()
66  * - @ref NT_NET_GET_PKT_L2_PTR()
67  * - @ref NT_NetTxRelease()
68  * - @ref NT_NetTxClose()
69  * - @ref NT_Done()
70  * - @ref NT_ExplainError()
71  *
72  * @section transmit_on_timestamp_example_prerequisites Prerequisites
73  * - This example is only compatible with adapters supporting 4GA transmit on
74  * timestamp.
75  * - The ntservice.ini must have at least one HostBuffersTx defined. Below is
76  * an example of a minimum ini-file. It will create a 4MB TX hostbuffer from
77  * NUMA node 0.
78  *
79  * @code
80  * [System]
81  * TimestampFormat = NATIVE
82  *
83  * [Adapter0]
84  * AdapterType = NT20E2
85  * BusId = 00:0a:00.00
86  * HostBuffersTx = [1,4,0]
87  * @endcode
88  *
89  * @section transmit_on_timestamp_example_flow Program flow
90  * @{
91  * The following is required to transmit packages:
92  * - \#include/nt.h - Applications/Tools only need to include @ref
93  * nt.h to obtain prototypes, macros etc. from NTAPI.
94  * - @ref NT_Init(@ref NTAPI_VERSION) - Initialize the NTAPI
95  * library. @ref NTAPI_VERSION is a define that describes the version
96  * of the API described in the header files included by @ref
97  * nt.h. NT_Init() will ask the NTAPI library to convert return data
98  * to the @ref NTAPI_VERSION if possible. This will ensure that
99  * applications can run on NTAPI libraries of newer versions.
100  * - @ref NT_ConfigOpen() - Open the config stream.
101  * - @ref NT_ConfigRead() - Use the config stream to read the current adapter
102  * time.
103  * - @ref NT_ConfigWrite() - Use the config stream to configure transmit on
104  * timestamp, using the retrieved adapter time.
105  * - @ref NT_NetTxOpen() - Open a hostbuffer than can transmit packets to port 0.
106  * - @ref NT_NetTxGet() - Get an empty tx buffer. This will get a 296 byte
107  * wire length packet buffer that will be sent onto port 0 when the packet
108  * buffer is released, and the timestamp has been reached on the adapter.
109  * - @ref NT_NET_GET_PKT_L2_PTR() is used to get the L2 pointer to the tx
110  * buffer, this is where the payload is placed.
111  * - @ref NT_NET_SET_PKT_TIMESTAMP() is used to set the packet timestamp.
112  * - @ref NT_NetTxRelease() - Release the tx packet buffer. Once a tx
113  * buffer is released it will be transmitted
114  * - @ref NT_ConfigRead() - Read the adapter timestamp to check if the last
115  * packet should have been transmitted. We need to do this in order to avoid
116  * disabling transmit on timestamp too early.
117  * - @ref NT_ConfigWrite() - Disable transmit on timestamp.
118  * - @ref NT_NetTxClose() - Close the TX stream.
119  * - @ref NT_Done() - Close down the NTAPI library.
120  *
121  *<hr>
122  * @section transmit_on_timestamp_example_code Code
123  * @}
124  */
125 
126 // Include this in order to access the Napatech API
127 #include <nt.h>
128 
129 #if defined(__linux__) || defined(__FreeBSD__)
130  #include <unistd.h> // sleep()
131 #elif defined(WIN32) || defined (WIN64)
132  #include <winsock2.h>
133 #endif
134 
135 // default TX packet test setup
136 #define PACKETS 100000
137 #define PACKET_SIZE 296 // Packet size to transmit (incl crc.)
138 #define PORT 0
139 #define ADAPTER 0
140 
141 // printError is a simple convenience function for printing an NTAPI error
142 // message to stderr.
143 static void printError(const char *prefix, int errorCode) {
145  NT_ExplainError(errorCode, errorBuffer, sizeof errorBuffer);
146  fprintf(stderr, "%s: %s\n", prefix, errorBuffer);
147 }
148 
149 int main(void)
150 {
151  //
152  // Initialize the API. This also checks if we are compatible with the
153  // installed library version.
154  //
155  int status;
156 
157  if ((status = NT_Init(NTAPI_VERSION)) != NT_SUCCESS) {
158  printError("NT_Init() failed", status);
159  return -1;
160  }
161 
162  //
163  // Open the config stream, in order to retrieve the adapter timestamp and
164  // to configure the transmit on timestamp functionality. We configure
165  // transmit on timestamp in such a way that a packet with timestamp 0 will
166  // transmit in approximately one second from this point.
167  //
168  NtConfigStream_t hConfig;
169  NtConfig_t config;
170 
171  if ((status = NT_ConfigOpen(&hConfig, "replay")) != NT_SUCCESS) {
172  printError("NT_ConfigOpen() failed", status);
173  return -1;
174  }
175 
177  config.u.timestampRead.adapter = ADAPTER;
178 
179  if ((status = NT_ConfigRead(hConfig, &config)) != NT_SUCCESS) {
180  printError("NT_ConfigRead() failed", status);
181  return -1;
182  }
183 
184  // Store adapter timestamp, converted from 10ns ticks to 1ns
185  uint64_t adapterTS = config.u.timestampRead.data.nativeUnixTs * 10;
186 
187  // Configure transmit on timestamp. In scenarios where a packet descriptor
188  // that does not contain a TXNOW bit is used, such as when transmitting PCAP,
189  // forceTxOnTs must be set to true. However, this example uses NT
190  // descriptors, and can thus use the TXNOW bit.
192  config.u.transmitOnTimestamp.portNo = (uint8_t)PORT;
193  config.u.transmitOnTimestamp.data.timeDelta = adapterTS + 1000000000;
195  config.u.transmitOnTimestamp.data.enable = true;
196  config.u.transmitOnTimestamp.data.forceTxOnTs = false;
197 
198  if ((status = NT_ConfigWrite(hConfig, &config)) != NT_SUCCESS) {
199  printError("NT_ConfigWrite() failed", status);
200  return -1;
201  }
202 
203  //
204  // Open a TX stream
205  //
206  NtNetStreamTx_t hNetTx;
207 
208  status = NT_NetTxOpen(&hNetTx, "transmit_on_timestamp_example_txstream",
209  1ULL << PORT, NT_NETTX_NUMA_ANY_HB, 0);
210  if (status != NT_SUCCESS) {
211  printError("NT_NetTxOpen() failed", status);
212  return -1;
213  }
214 
215  //
216  // Retrieve a packet buffer, fill it, and repeat until we have transmitted
217  // the requested amount of packets. The timestamp will be set so that the
218  // adapter will transmit at approximately 5 Mb/s.
219  //
220  printf("Commencing transmission\n");
221 
222  NtNetBuf_t hNetBufTx;
223  uint64_t timestamp = 0;
224  int numPackets = 0;
225 
226  for (numPackets = 0; numPackets < PACKETS; numPackets++) {
227 
228  // Get a packet TX buffer for this tx stream and port, without timeout
229  if ((status = NT_NetTxGet(hNetTx, &hNetBufTx, PORT, PACKET_SIZE,
230  NT_NETTX_PACKET_OPTION_DEFAULT, -1)) != NT_SUCCESS) {
231  printError("NT_NetTxGet() failed", status);
232  return -1;
233  }
234 
235  // Set the timestamp. Note that for the NT descriptor, this is in 10ns
236  // ticks. The descriptor has been cleared, so TXNOW is set to 0. If one
237  // wishes to send a packet as soon as possible while transmit on timestamp
238  // is enabled, use NT_NET_SET_PKT_TXNOW to set TXNOW to 1.
239  NT_NET_SET_PKT_TIMESTAMP(hNetBufTx, timestamp);
240  timestamp += 50000;
241 
242  // Fill the packet with an incrementing payload. Note that this will result
243  // in a garbage ethernet frame.
244  uint32_t *ptr = (uint32_t*)NT_NET_GET_PKT_L2_PTR(hNetBufTx);
245  for (uint32_t i = 0; i < PACKET_SIZE/4; i++) {
246  *(ptr+i) = i;
247  }
248 
249  // Release the TX buffer to commit the packet. It will transmit once the
250  // timestamp is reached, or when transmit on timestamp is disabled.
251  if ((status = NT_NetTxRelease(hNetTx, hNetBufTx)) != NT_SUCCESS) {
252  printError("NT_NetTxRelease() failed", status);
253  return -1;
254  }
255  }
256 
257  //
258  // Wait for all packets to be transmitted. There are multiple ways to do
259  // this, but in this example, we read the adapter timestamp in a loop, and
260  // compare it to the value of our timestamp variable from the loop above.
261  //
262  printf("Waiting for transmission to end\n");
263 
265  config.u.timestampRead.adapter = ADAPTER;
266 
267  uint64_t newAdapterTS;
268  do {
269 #if defined(__linux__) || defined(__FreeBSD__)
270  sleep(1);
271 #elif defined(WIN32) || defined (WIN64)
272  Sleep(1000); // sleep 1000 milliseconds = 1 second
273 #endif
274  if ((status = NT_ConfigRead(hConfig, &config)) != NT_SUCCESS) {
275  printError("NT_ConfigRead() failed", status);
276  return -1;
277  }
278 
279  newAdapterTS = config.u.timestampRead.data.nativeUnixTs * 10;
280  } while (newAdapterTS <= (adapterTS + timestamp));
281 
282  //
283  // Disable transmit on timestamp. If any packets are left in the buffera this
284  // point, they will transmit unhindered at line rate.
285  //
287  config.u.transmitOnTimestamp.portNo = (uint8_t)PORT;
288  config.u.transmitOnTimestamp.data.timeDelta = 0;
290  config.u.transmitOnTimestamp.data.enable = false;
292 
293  if ((status = NT_ConfigWrite(hConfig, &config)) != NT_SUCCESS) {
294  printError("NT_ConfigWrite() failed", status);
295  return -1;
296  }
297 
298  //
299  // Terminate
300  //
301  printf("Done: %d packets sent\n", numPackets);
302 
303  // Close the TX stream
304  NT_NetTxClose(hNetTx);
305 
306  // Close the API
307  NT_Done();
308 
309  return 0;
310 }