transmit_pcap_example.c 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.
 *
 *

 */

/**
 * @example net/transmit_pcap/transmit_pcap_example.c
 * @section transmit_pcap_example_description Description
 *
 * This source file is an example of how to transmit PCAP packets using the
 * packet interface in NTAPI. The example will transmit 2500000 packets with a
 * size of 1024 bytes from port 0. The packet contains an incrementing 32bit
 * pattern.
 *
 * PCAP can also be used with transmit on timestamp, or segment interfaces. See
 * the respective examples to see how to use those interfaces. Note that for
 * PCAP transmit on timestamp, the "forceTxOnTs" feature must be enabled.
 *
 * The following NTAPI functions are used:
 * - @ref NT_Init()
 * - @ref NT_NetTxOpen_v2()
 * - @ref NT_NetTxGet()
 *   - @ref NT_NET_GET_PKT_L2_PTR()
 * - @ref NT_NetTxRelease()
 * - @ref NT_NetTxClose()
 * - @ref NT_Done()
 * - @ref NT_ExplainError()
 *
 * @section transmit_pcap_example_prerequisites Prerequisites
 * - The ntservice.ini must have at least one HostBuffersTx defined. Below is
 * an example of a minimum ini-file. It will create a 4MB TX hostbuffer from
 * NUMA node 0.
 *
 * @code
 * [System]
 * TimestampFormat = NATIVE
 *
 * [Adapter0]
 * AdapterType     = NT20E2
 * BusId           = 00:0a:00.00
 * HostBuffersTx   = [1,4,0]
 * @endcode
 *
 * @section transmit_pcap_example_flow Program flow
 * @{
 * The following is required to transmit packages:
 * - \#include/nt.h - Applications/Tools only need to include @ref
 *   nt.h to obtain prototypes, macros etc. from NTAPI.
 * - @ref NT_Init(@ref NTAPI_VERSION) - Initialize the NTAPI
 *   library. @ref NTAPI_VERSION is a define that describes the version
 *   of the API described in the header files included by @ref
 *   nt.h. NT_Init() will ask the NTAPI library to convert return data
 *   to the @ref NTAPI_VERSION if possible. This will ensure that
 *   applications can run on NTAPI libraries of newer versions.
 * - @ref NT_NetTxOpen_v2() - Open a hostbuffer than can transmit packets to port 0.
 * - @ref NT_NetTxGet() - Get an empty tx buffer. This will get a 296 byte
 *   wire length packet buffer that will be sent onto port 0 when
 *   released.
 *   - @ref NT_NET_GET_PKT_DESCR_PTR() is used to retrieve the descriptor
 *   - @ref NT_NET_GET_PKT_L2_PTR() is used to get the L2 pointer to the tx
 *     buffer, this is where the payload is placed.
 * - @ref NT_NetTxRelease() - Release the tx packet buffer. Once a tx
 *   buffer is released it will be transmitted
 * - @ref NT_NetTxClose() - Close the TX stream.
 * - @ref NT_Done() - Close down the NTAPI library.
 *
 *<hr>
 * @section transmit_pcap_example_code Code
 * @}
 */

// Include this in order to access the Napatech API
#include <nt.h>

// default TX packet test setup
#define PACKETS      2500000
#define PACKET_SIZE  1024 // Packet size to transmit (incl crc.)
#define PORT        0

// This is the timespec for PCAP. For PCAP_NANO, the ts_usec field
// will instead of micro-seconds contain nanoseconds.
struct pcap_timespec_s {
  uint32_t ts_sec;
  uint32_t ts_usec;
};

// Standard PCAP record header.
struct pcap_record_s {
  struct pcap_timespec_s time;
  uint32_t incl_len;
  uint32_t orig_len;
};

// printError is a simple convenience function for printing an NTAPI error
// message to stderr.
static void printError(const char *prefix, int errorCode) {
  char errorBuffer[NT_ERRBUF_SIZE];
  NT_ExplainError(errorCode, errorBuffer, sizeof errorBuffer);
  fprintf(stderr, "%s: %s\n", prefix, errorBuffer);
}

int main(void)
{
  //
  // Initialize the API. This also checks if we are compatible with the
  // installed library version.
  //
  int status;

  if ((status = NT_Init(NTAPI_VERSION)) != NT_SUCCESS) {
    printError("NT_Init() failed", status);
    return -1;
  }

  //
  // Open a TX stream
  //
  NtNetStreamTx_t hNetTx;
  NtNetTxAttr_t txAttr;
  NT_NetTxOpenAttrSetName(&txAttr, "pcaptransmit_example_txstream");
  NT_NetTxOpenAttrSetPortMask(&txAttr, (1<<PORT));
  NT_NetTxOpenAttrSetNUMA(&txAttr, NT_NETTX_NUMA_ANY_HB);
  NT_NetTxOpenAttrSetDescriptor(&txAttr, NT_PACKET_DESCRIPTOR_TYPE_PCAP);
  NT_NetTxOpenAttrSetTimestampType(&txAttr, NT_TIMESTAMP_TYPE_PCAP);

  if ((status = NT_NetTxOpen_Attr(&hNetTx, &txAttr)) != NT_SUCCESS) {
    printError("NT_NetTxOpen_Attr() failed", status);
    return -1;
  }

  //
  // Retrieve a packet buffer, fill it, and repeat until we have transmitted
  // the requested amount of packets.
  //
  printf("Commencing transmission\n");

  NtNetBuf_t hNetBufTx;
  int numPackets;

  for (numPackets = 0; numPackets < PACKETS; numPackets++) {

    // Get a packet TX buffer for this tx stream and port, without timeout
    if ((status = NT_NetTxGet(hNetTx, &hNetBufTx, PORT, PACKET_SIZE,
            NT_NETTX_PACKET_OPTION_DEFAULT, -1)) != NT_SUCCESS) {
      printError("NT_NetTxGet() failed", status);
      return -1;
    }

    // Fill the packet with an incrementing payload. Note that this will result
    // in a garbage ethernet frame.
    uint32_t *ptr = (uint32_t*)NT_NET_GET_PKT_L2_PTR(hNetBufTx);
    for (uint32_t i = 0; i < PACKET_SIZE/4; i++) {
      *(ptr+i) = i;
    }

    // Set the pcap header fields. If used in a transmit on timestamp context,
    // the timeval fields must be set to a sensible value.
    struct pcap_record_s *hdr = (struct pcap_record_s*)NT_NET_GET_PKT_DESCR_PTR(hNetBufTx);
    hdr->incl_len = PACKET_SIZE;
    hdr->orig_len = PACKET_SIZE;
    hdr->time.ts_sec = 0;
    hdr->time.ts_usec = 0;

    // Release the TX buffer to transmit the packet.
    if ((status = NT_NetTxRelease(hNetTx, hNetBufTx)) != NT_SUCCESS) {
      printError("NT_NetTxRelease() failed", status);
      return -1;
    }
  }

  //
  // Terminate
  //
  printf("Done: %d packets sent\n", numPackets);

  // Close the TX stream
  NT_NetTxClose(hNetTx);

  // Close the API
  NT_Done();

  return 0;
}