Reference Documentation

Napatech SmartNIC
Reference Information

Go to the documentation of this file.

1/** 2 * %NT_SOFTWARE_LICENSE% 3 */ 4 5/** 6 * @file 7 */ 8#ifndef _PATH_DELAY_H_ 9#define _PATH_DELAY_H_ 10 11/** @addtogroup MainDocMainFeaturesPathDelay 12 * @{ 13@section path_delay_overview Overview 14 15An adapter uses time stamps for time-stamping incoming packets, and 16for sending packets at the correct time. When receiving a packet 17there is a delay from the time that a packet (frame) arrives and until 18the adapter time-stamps it. This delay is called the RX path delay. 19When transmitting a packet there is a delay from the time that the 20adapter releases a packet (frame) and until it is transmitted. This 21delay is called the TX path delay. 22 23An application can retrieve the path delay from the driver. 24A path delay is a non-zero value in nanoseconds. The delay 25information may not always be available, and an application must be 26ready to handle that situation. 27 28When delay information is available, the application can subtract the 29RX path delay from the time stamp in a packet descriptor to calculate 30when an incoming packet (frame) arrived at the port. When using 31global sync mode, the application can adjust for the TX path delay 32when calculating the value of the single TX clock origin. 33 34To use the feature properly, an application must query the delay when 35the link speed changes, or a NIM module is inserted. The system 36provides suitable <em>events</em> for this purpose, 37see @ref sec_link_speed_nim_module_update. 38 39 40@section path_delay_api API 41 42An application can use the information stream to retrieve the path 43delays for a port. 44 45- The information stream provides access to path delays. An 46 application must use the @ref NtInfo_t structure and set the 47 <tt>cmd</tt> member to @ref NT_INFO_CMD_READ_PATH_DELAY command and 48 the @ref NtInfoCmdPortPathDelay_s command structure to retrieve the 49 path delay for a port. The application should set the 50 <tt>direction</tt> member to NT_PATH_DELAY_RX_DIR or 51 NT_PATH_DELAY_TX_DIR to retrieve the RX and TX path delays, 52 respectively. Section @ref sec_example_program contains a simple 53 example program that retrieves the RX and TX delays for port number 54 zero. 55 56- RX and TX path delays are kept separate in the API. This means that 57 an application cannot retrieve both types of delays for a given port 58 at the same time. 59 60- The API returns a delay value and a status code via the @ref 61 NtInfoPortPathDelay_s structure. The member <tt>status</tt> 62 provides the status code, and the <tt>member</tt> is the returned 63 delay. The status code is an enumeration @ref NtPathDelayStatus_e 64 that indicates whether the delay value is valid. The returned value 65 is an integer, which is the path delay in nano-seconds. 66 67- The returned delay is a single value that is the sum of the adapter 68 and the NIM module contributions, or in some cases only the adapter 69 delay without the NIM module delay. An application must use the 70 status code to interpret the delay value correctly. Section @ref 71 sec_status_codes describes the meaning of the return codes. 72 73- Status code NT_PATH_DELAY_SUCCESS means the link is up, and the 74 driver has recognized the adapter/FPGA and the installed NIM 75 modules. The returned delay value is the sum of the adapter and NIM 76 module delays. 77 78- Status codes NT_PATH_DELAY_LINK_DOWN and NT_PATH_DELAY_NOT_SUPPORTED 79 mean the delay value is unavailable. If the staus code is 80 NT_PATH_DELAY_LINK_DOWN, an application may try to retrieve the 81 delay value later, or it can catch the NT_EVENT_PORT_LINK_UP event. 82 83- Status code NT_PATH_DELAY_UNKNOWN_NIM means the link is up, and the 84 driver has recognized the adapter/FPGA but not the NIM module. The 85 returned delay value is without the NIM module delay. 86 87@note Observe the @ref path_delay_limitations "limitations" in the 88current implementation. 89 90@subsection sec_status_codes Path Delay Status Codes 91 92The status code is the <tt>status</tt> member of the @ref 93NtInfoPortPathDelay_s structure. 94 95<table width="100%" border="1" cellspacing="0" cellpadding="1"> 96 <caption align="top">Path Delay Status Codes</caption> 97 <tr> 98 <td width="15%" align="center" style='background:#BFBFBF'>@b Code</td> 99 <td align="center" style='background:#BFBFBF'>@b Meaning</td> 100 </tr> 101 <tr> 102 <td>NT_PATH_DELAY_LINK_DOWN</td> 103 <td>Link is down, no delay to return, 104 not even if the NIM module is optical.</td> 105 </tr> 106 <tr> 107 <td>NT_PATH_DELAY_NOT_SUPPORTED</td> 108 <td>No delay available for the FPGA version. 109 It is undefined whether the NIM module is known.</td> 110 </tr> 111 <tr> 112 <td>NT_PATH_DELAY_SUCCESS</td> 113 <td>Link is up and FPGA and NIM modules are known.</td> 114 </tr> 115 <tr> 116 <td>NT_PATH_DELAY_UNKNOWN_NIM</td> 117 <td>NIM is unknown but the FPGA version is known. 118 The returned delay does not contain any contribution 119 from the NIM module.</td> 120 </tr> 121</table> 122 123@subsection sec_link_speed_nim_module_update Detecting Link Speed Change or New NIM Module 124 125The path delay depends on the link speed and NIM module type, and an 126application must retrieve the delay whenever the link speed changes, 127or the NIM module is replaced. This is also true if the same NIM is 128removed and reinserted. 129 130An application can catch the NT_EVENT_PORT_NIM_REMOVED and 131NT_EVENT_PORT_NIM_INSERTED events to detect replacement of a NIM 132module, but although a NIM is a requisite for a network link, it 133is not until the link is up, and the link speed is set, that the 134correct path delay is available. Remember that the path delay depends 135on the NIM module type and link speed. An application can, and 136<em>must</em>, detect whenever a link goes down, and when the link is 137up again; the application must retrieve the path delay (again). An 138application can detect a change of the link speed indirectly by 139catching the events NT_EVENT_PORT_LINK_DOWN and NT_EVENT_PORT_LINK_UP, 140and retrieve the path delay when the link is up again. 141 142Note that the solution does not provide a way for an application to 143identify the first network packet that pertains to a new link speed. 144An application must implement logic for that purpose itself. Since 145the solution requires a link is up for the delay to be available, 146there is a small time period following a link down event, where 147packets may arrive without the application knowing the correct 148(receive) delay; the application can either disregard the delay or 149postpone processing of the packets until the delay has been retrieved. 150 151@note A user may consider disabling auto negotiation to avoid 152externally imposed link speed changes, however even with auto 153negotiation @e enabled, a link will go down and come back up when the 154speed changes, which gives an application the possibility to detect 155the change. 156 157 158@section path_delay_limitations Limitations 159 160The version number mentioned in this section can be found by running 161the <tt>adapterinfo</tt> command. The version number is the third 162number series in the line that begins with <tt>FPGA ID</tt>. The 163following command line gives an example that illustrates a version 164number of 47. 165 166@verbatim 167# /opt/napatech3/bin/adapterinfo | grep "^FPGA " 168FPGA ID: 200-9220-47-01-00 169@endverbatim 170 171The current implementation has the following limitation: 172 173- GEN1 capture adapters are not supported. The system returns 174 NT_PATH_DELAY_NOT_SUPPORTED for GEN1 capture adapters. 175 176 177@section sec_example_program Example Program 178 179@code 180// Save in get_path_delay.c and build with 181// cc -I/opt/napatech3/include -L/opt/napatech3/lib -lntapi \ 182// -g -o get_path_delay get_path_delay.c 183 184#include "nt.h" 185#include <stdio.h> 186#include <assert.h> 187 188static NtInfoStream_t hInfo = NULL; 189 190static const char *status2text(enum NtPathDelayStatus_e status) 191{ 192 switch (status) { 193 case NT_PATH_DELAY_SUCCESS: 194 return "SUCCESS"; 195 case NT_PATH_DELAY_NOT_SUPPORTED: 196 return "NOT_SUPPORTED"; 197 case NT_PATH_DELAY_LINK_DOWN: 198 return "LINK_DOWN"; 199 case NT_PATH_DELAY_UNKNOWN_NIM: 200 return "UNKNOWN_NIM"; 201 default: 202 assert(0); 203 } 204} 205 206int main() 207{ 208 const uint8_t virtualPortNo = 0; 209 NtInfo_t info; 210 char errBuf[1024]; 211 int status; 212 213 // Initialize NTAPI 214 if ((status = NT_Init(NTAPI_VERSION)) != NT_SUCCESS) { 215 NT_ExplainError(status, errBuf, sizeof(errBuf)); 216 fprintf(stderr, ">>> Error: NT_Init failed. Code 0x%x = %s\n", 217 status, errBuf); 218 return 1; 219 } 220 221 // Open information stream 222 if ((status = NT_InfoOpen(&hInfo, "CONFIG")) != NT_SUCCESS) { 223 NT_ExplainError(status, errBuf, sizeof(errBuf)); 224 fprintf(stderr, ">>> Error: NT_InfoOpen failed. Code 0x%x = %s\n", 225 status, errBuf); 226 return 1; 227 } 228 229 // Read RX path delay for port `virtualPortNo' 230 info.cmd = NT_INFO_CMD_READ_PATH_DELAY; 231 info.u.pathDelay.portNo = virtualPortNo; 232 info.u.pathDelay.direction = NT_PATH_DELAY_RX_DIR; 233 234 if ((status = NT_InfoRead(hInfo, &info)) != NT_SUCCESS) { 235 NT_ExplainError(status, errBuf, sizeof(errBuf)); 236 fprintf(stderr, ">>> Error: NT_InfoRead failed. Code 0x%x = %s\n", 237 status, errBuf); 238 return 1; 239 } 240 241 (void)printf("RX port path delay for port %u: status = %s; delay = %d\n", 242 info.u.pathDelay.portNo, 243 status2text(, 244; 245 246 // Read TX path delay for port `virtualPortNo' 247 info.u.pathDelay.direction = NT_PATH_DELAY_TX_DIR; 248 if ((status = NT_InfoRead(hInfo, &info)) != NT_SUCCESS) { 249 NT_ExplainError(status, errBuf, sizeof(errBuf)); 250 fprintf(stderr, ">>> Error: NT_InfoRead failed. Code 0x%x = %s\n", 251 status, errBuf); 252 return 1; 253 } 254 (void)printf("TX port path delay for port %u: status = %s; delay = %d\n", 255 info.u.pathDelay.portNo, 256 status2text(, 257; 258 return 0; 259} 260@endcode 261 262 *@} 263**/ 264 265#include "nt.h" /* Cannot include stream_info.h directly */ 266int getPathDelay(NtInfo_t *); 267 268#endif