net/transmit_pcap/transmit_pcap_example.c

Reference Documentation

Platform
Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.10
Napatech Software Suite: net/transmit_pcap/transmit_pcap_example.c
net/transmit_pcap/transmit_pcap_example.c

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:

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.
[System]
TimestampFormat = NATIVE
[Adapter0]
AdapterType = NT20E2
BusId = 00:0a:00.00
HostBuffersTx = [1,4,0]

Program flow

The following is required to transmit packages:

  • #include/nt.h - Applications/Tools only need to include nt.h to obtain prototypes, macros etc. from NTAPI.
  • NT_Init(NTAPI_VERSION) - Initialize the NTAPI library. NTAPI_VERSION is a define that describes the version of the API described in the header files included by nt.h. NT_Init() will ask the NTAPI library to convert return data to the NTAPI_VERSION if possible. This will ensure that applications can run on NTAPI libraries of newer versions.
  • NT_NetTxOpen_v2() - Open a hostbuffer than can transmit packets to port 0.
  • 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.
    • NT_NET_GET_PKT_DESCR_PTR() is used to retrieve the descriptor
    • NT_NET_GET_PKT_L2_PTR() is used to get the L2 pointer to the tx buffer, this is where the payload is placed.
  • NT_NetTxRelease() - Release the tx packet buffer. Once a tx buffer is released it will be transmitted
  • NT_NetTxClose() - Close the TX stream.
  • NT_Done() - Close down the NTAPI library.

Code

/*
*
* 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.
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) {
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
//
NtNetTxAttr_t txAttr;
NT_NetTxOpenAttrSetName(&txAttr, "pcaptransmit_example_txstream");
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->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
return 0;
}