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