r/Reference-Documentation/path_delay.h-Source-File

/**
 *
 * Copyright 2023 Napatech A/S. All Rights Reserved.
 *
 * 1. Copying, modification, and distribution of this file, or executable
 * versions of this file, is governed by the terms of the Napatech Software
 * license agreement under which this file was made available. If you do not
 * agree to the terms of the license do not install, copy, access or
 * otherwise use this file.
 *
 * 2. Under the Napatech Software license agreement you are granted a
 * limited, non-exclusive, non-assignable, copyright license to copy, modify
 * and distribute this file in conjunction with Napatech SmartNIC's and
 * similar hardware manufactured or supplied by Napatech A/S.
 *
 * 3. The full Napatech Software license agreement is included in this
 * distribution, please see "NP-0405 Napatech Software license
 * agreement.pdf"
 *
 * 4. Redistributions of source code must retain this copyright notice,
 * list of conditions and the following disclaimer.
 *
 * THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES, EXPRESS OR
 * IMPLIED, AND NAPATECH DISCLAIMS ALL IMPLIED WARRANTIES INCLUDING ANY
 * IMPLIED WARRANTY OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, OR OF
 * FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT NOT PROHIBITED BY
 * APPLICABLE LAW, IN NO EVENT SHALL NAPATECH BE LIABLE FOR PERSONAL INJURY,
 * OR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES WHATSOEVER,
 * INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, CORRUPTION OR
 * LOSS OF DATA, FAILURE TO TRANSMIT OR RECEIVE ANY DATA OR INFORMATION,
 * BUSINESS INTERRUPTION OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, ARISING
 * OUT OF OR RELATED TO YOUR USE OR INABILITY TO USE NAPATECH SOFTWARE OR
 * SERVICES OR ANY THIRD PARTY SOFTWARE OR APPLICATIONS IN CONJUNCTION WITH
 * THE NAPATECH SOFTWARE OR SERVICES, HOWEVER CAUSED, REGARDLESS OF THE THEORY
 * OF LIABILITY (CONTRACT, TORT OR OTHERWISE) AND EVEN IF NAPATECH HAS BEEN
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME JURISDICTIONS DO NOT ALLOW
 * THE EXCLUSION OR LIMITATION OF LIABILITY FOR PERSONAL INJURY, OR OF
 * INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION MAY NOT APPLY TO YOU.
 *
 *

 */

/**
 * @file
 */
#ifndef _PATH_DELAY_H_
#define _PATH_DELAY_H_

/** @addtogroup MainDocMainFeaturesPathDelay
 * @{
@section path_delay_overview Overview

An adapter uses time stamps for time-stamping incoming packets, and
for sending packets at the correct time.  When receiving a packet
there is a delay from the time that a packet (frame) arrives and until
the adapter time-stamps it.  This delay is called the RX path delay.
When transmitting a packet there is a delay from the time that the
adapter releases a packet (frame) and until it is transmitted.  This
delay is called the TX path delay.

An application can retrieve the path delay from the driver.
A path delay is an integer value in nanoseconds.  The delay
information may not always be available, and an application must be
ready to handle that situation.

When delay information is available, the application can subtract the
RX path delay from the time stamp in a packet descriptor to calculate
when an incoming packet (frame) arrived at the port.  When using
global sync mode, the application can adjust for the TX path delay
when calculating the value of the single TX clock origin.

To use the feature properly, an application must query the delay when
the link speed changes, or a NIM module is inserted.  The system
provides suitable <em>events</em> for this purpose,
see @ref sec_link_speed_nim_module_update.


@section path_delay_api API

An application can use the information stream to retrieve the path
delays for a port.

- The information stream provides access to path delays.  An
  application must use the @ref NtInfo_t structure and set the
  <tt>cmd</tt> member to @ref NT_INFO_CMD_READ_PATH_DELAY command and
  the @ref NtInfoCmdPortPathDelay_s command structure to retrieve the
  path delay for a port.  The application should set the
  <tt>direction</tt> member to NT_PATH_DELAY_RX_DIR or
  NT_PATH_DELAY_TX_DIR to retrieve the RX and TX path delays,
  respectively.  Section @ref sec_example_program contains a simple
  example program that retrieves the RX and TX delays for port number
  zero.

- RX and TX path delays are kept separate in the API.  This means that
  an application cannot retrieve both types of delays for a given port
  at the same time.

- The API returns a delay value and a status code via the @ref
  NtInfoPortPathDelay_s structure.  The member <tt>status</tt>
  provides the status code, and the <tt>member</tt> is the returned
  delay.  The status code is an enumeration @ref NtPathDelayStatus_e
  that indicates whether the delay value is valid.  The returned value
  is an integer, which is the path delay in nanoseconds.

- The returned delay is a single value that is the sum of the adapter
  and the NIM module contributions, or in some cases only the adapter
  delay without the NIM module delay.  An application must use the
  status code to interpret the delay value correctly.  Section @ref
  sec_status_codes describes the meaning of the return codes.

- Status code NT_PATH_DELAY_SUCCESS means the link is up, and the
  driver has recognized the adapter/FPGA and the installed NIM
  modules.  The returned delay value is the sum of the adapter and NIM
  module delays.

- Status codes NT_PATH_DELAY_LINK_DOWN and NT_PATH_DELAY_NOT_SUPPORTED
  mean the delay value is unavailable.  If the staus code is
  NT_PATH_DELAY_LINK_DOWN, an application may try to retrieve the
  delay value later, or it can catch the NT_EVENT_PORT_LINK_UP event.

- Status code NT_PATH_DELAY_UNKNOWN_NIM means the link is up, and the
  driver has recognized the adapter/FPGA but not the NIM module.  The
  returned delay value is without the NIM module delay.

@note Observe the @ref path_delay_limitations "limitations" in the
current implementation.

@subsection sec_status_codes Path Delay Status Codes

The status code is the <tt>status</tt> member of the @ref
NtInfoPortPathDelay_s structure.

<table width="100%" border="1" cellspacing="0" cellpadding="1">
 <caption align="top">Path Delay Status Codes</caption>
 <tr>
  <td width="15%" align="center" style='background:#BFBFBF'>@b Code</td>
  <td align="center" style='background:#BFBFBF'>@b Meaning</td>
 </tr>
 <tr>
  <td>NT_PATH_DELAY_LINK_DOWN</td>
  <td>Link is down, no delay to return,
      not even if the NIM module is optical.</td>
 </tr>
 <tr>
  <td>NT_PATH_DELAY_NOT_SUPPORTED</td>
  <td>No delay available for the FPGA version.
      It is undefined whether the NIM module is known.</td>
 </tr>
 <tr>
  <td>NT_PATH_DELAY_SUCCESS</td>
  <td>Link is up and FPGA and NIM modules are known.</td>
 </tr>
 <tr>
  <td>NT_PATH_DELAY_UNKNOWN_NIM</td>
  <td>NIM is unknown but the FPGA version is known.
      The returned delay does not contain any contribution
      from the NIM module.</td>
 </tr>
</table>

@subsection sec_link_speed_nim_module_update Detecting Link Speed Change or New NIM Module

The path delay depends on the link speed and NIM module type, and an
application must retrieve the delay whenever the link speed changes,
or the NIM module is replaced.  This is also true if the same NIM is
removed and reinserted.

An application can catch the NT_EVENT_PORT_NIM_REMOVED and
NT_EVENT_PORT_NIM_INSERTED events to detect replacement of a NIM
module, but although a NIM is a requisite for a network link, it
is not until the link is up, and the link speed is set, that the
correct path delay is available.  Remember that the path delay depends
on the NIM module type and link speed.  An application can, and
<em>must</em>, detect whenever a link goes down, and when the link is
up again; the application must retrieve the path delay (again).  An
application can detect a change of the link speed indirectly by
catching the events NT_EVENT_PORT_LINK_DOWN and NT_EVENT_PORT_LINK_UP,
and retrieve the path delay when the link is up again.

Note that the solution does not provide a way for an application to
identify the first network packet that pertains to a new link speed.
An application must implement logic for that purpose itself.  Since
the solution requires a link is up for the delay to be available,
there is a small time period following a link down event, where
packets may arrive without the application knowing the correct
(receive) delay; the application can either disregard the delay or
postpone processing of the packets until the delay has been retrieved.

@note A user may consider disabling auto negotiation to avoid
externally imposed link speed changes, however even with auto
negotiation @e enabled, a link will go down and come back up when the
speed changes, which gives an application the possibility to detect
the change.


@section path_delay_limitations Limitations

The version number mentioned in this section can be found by running
the <tt>adapterinfo</tt> command.  The version number is the third
number series in the line that begins with <tt>FPGA ID</tt>.  The
following command line gives an example that illustrates a version
number of 47.

@verbatim
# /opt/napatech3/bin/adapterinfo | grep "^FPGA "
FPGA ID:        200-9220-47-01-00
@endverbatim

The current implementation has the following limitation:

- GEN1 capture adapters are not supported.  The system returns
  NT_PATH_DELAY_NOT_SUPPORTED for GEN1 capture adapters.


@section sec_example_program Example Program

@code
// Save in get_path_delay.c and build with
//  cc -I/opt/napatech3/include -L/opt/napatech3/lib -lntapi \
//     -g -o get_path_delay get_path_delay.c

#include "nt.h"
#include <stdio.h>
#include <assert.h>

static NtInfoStream_t hInfo = NULL;

static const char *status2text(enum NtPathDelayStatus_e status)
{
  switch (status) {
  case NT_PATH_DELAY_SUCCESS:
    return "SUCCESS";
  case NT_PATH_DELAY_NOT_SUPPORTED:
    return "NOT_SUPPORTED";
  case NT_PATH_DELAY_LINK_DOWN:
    return "LINK_DOWN";
  case NT_PATH_DELAY_UNKNOWN_NIM:
    return "UNKNOWN_NIM";
  default:
    assert(0);
  }
}

int main()
{
  const uint8_t logicalPortNo = 0;
  NtInfo_t info;
  char errBuf[1024];
  int status;

  // Initialize NTAPI
  if ((status = NT_Init(NTAPI_VERSION)) != NT_SUCCESS) {
    NT_ExplainError(status, errBuf, sizeof(errBuf));
    fprintf(stderr, ">>> Error: NT_Init failed. Code 0x%x = %s\n",
            status, errBuf);
    return 1;
  }

  // Open information stream
  if ((status = NT_InfoOpen(&hInfo, "CONFIG")) != NT_SUCCESS) {
    NT_ExplainError(status, errBuf, sizeof(errBuf));
    fprintf(stderr, ">>> Error: NT_InfoOpen failed. Code 0x%x = %s\n",
            status, errBuf);
    return 1;
  }

  // Read RX path delay for port `logicalPortNo'
  info.cmd = NT_INFO_CMD_READ_PATH_DELAY;
  info.u.pathDelay.portNo = logicalPortNo;
  info.u.pathDelay.direction = NT_PATH_DELAY_RX_DIR;

  if ((status = NT_InfoRead(hInfo, &info)) != NT_SUCCESS) {
    NT_ExplainError(status, errBuf, sizeof(errBuf));
    fprintf(stderr, ">>> Error: NT_InfoRead failed. Code 0x%x = %s\n",
            status, errBuf);
    return 1;
  }

  (void)printf("RX port path delay for port %u: status = %s; delay = %d\n",
               info.u.pathDelay.portNo,
               status2text(info.u.pathDelay.data.status),
               info.u.pathDelay.data.delay);

  // Read TX path delay for port `logicalPortNo'
  info.u.pathDelay.direction = NT_PATH_DELAY_TX_DIR;
  if ((status = NT_InfoRead(hInfo, &info)) != NT_SUCCESS) {
    NT_ExplainError(status, errBuf, sizeof(errBuf));
    fprintf(stderr, ">>> Error: NT_InfoRead failed. Code 0x%x = %s\n",
            status, errBuf);
    return 1;
  }
  (void)printf("TX port path delay for port %u: status = %s; delay = %d\n",
               info.u.pathDelay.portNo,
               status2text(info.u.pathDelay.data.status),
               info.u.pathDelay.data.delay);
  return 0;
}
@endcode

 *@}
**/

#include "nt.h" /* Cannot include stream_info.h directly */
int getPathDelay(NtInfo_t *);

#endif