Myricom logo

Data Structures | Typedefs | Functions
Packet injection

Data Structures

struct  snf_pkt_fragment
 Fragment for snf_inject_send_v. More...
 
struct  snf_inject_stats
 

Typedefs

typedef struct snf_inject_handle * snf_inject_t
 

Functions

int snf_inject_open (int portnum, int flags, snf_inject_t *handle)
 Open a port for injection and allocate an injection handle. More...
 
int snf_get_injection_speed (snf_inject_t devhandle, uint64_t *speed)
 
int snf_inject_send (snf_inject_t inj, int timeout_ms, int flags, const void *pkt, uint32_t length)
 Send a packet and optionally block until send resources are available. More...
 
int snf_inject_sched (snf_inject_t inj, int timeout_ms, int flags, const void *pkt, uint32_t length, uint64_t delay_ns)
 Send a packet with hardware delay and optionally block until send resources are available. More...
 
int snf_inject_send_v (snf_inject_t inj, int timeout_ms, int flags, struct snf_pkt_fragment *frags_vec, int nfrags, uint32_t length_hint)
 Send a packet assembled from a vector of fragments and optionally block until send resources are available. More...
 
int snf_inject_sched_v (snf_inject_t inj, int timeout_ms, int flags, struct snf_pkt_fragment *frags_vec, int nfrags, uint32_t length_hint, uint64_t delay_ns)
 Send a packet assembled from a vector of fragments at a scheduled point relative to the start of the prior packet and optionally block until send resources are available. More...
 
int snf_inject_close (snf_inject_t inj)
 Close injection handle. More...
 
int snf_inject_getstats (snf_inject_t inj, struct snf_inject_stats *stats)
 Get statistics from an injection handle. More...
 

Detailed Description

SNF Packet injection routines that can be used for independent packet generation or coupled to reinject packets received with snf_ring_recv.

Typedef Documentation

typedef struct snf_inject_handle* snf_inject_t

Opaque injection handle, allocated by snf_inject_open. There are only a limited amount of injection handles per NIC/port.

Function Documentation

int snf_get_injection_speed ( snf_inject_t  devhandle,
uint64_t *  speed 
)

Get link speed on opened injection handle

Parameters
devhandleDevice handle
speedReturns speed in bits-per-second for the link
Remarks
The cost of retrieving the link speed requires a function call that reads information kept in kernel host memory (i.e. no PCI bus reads).
int snf_inject_close ( snf_inject_t  inj)

Close injection handle.

This function closes an injection handle and ensures that all pending sends are sent by the NIC.

Parameters
injInjection handle
Return values
0Successful
Postcondition
Once closed, the injection handle will have ensured that any pending sends have been sent out on the wire. The handle is then made available again for the underlying port's limited amount of handles.
int snf_inject_getstats ( snf_inject_t  inj,
struct snf_inject_stats stats 
)

Get statistics from an injection handle.

Parameters
injInjection Handle
statsUser-provided pointer to a statistics structure snf_inject_stats, filled in by the SNF implementation.
Remarks
This call is provided as a convenience and should not be relied on for time-critical applications or for high levels of accuracy. Statistics are only updated by the NIC periodically.
Warning
Administrative clearing of NIC counters while a Sniffer-based application is running may cause some of the counters to be incorrect.
int snf_inject_open ( int  portnum,
int  flags,
snf_inject_t handle 
)

Open a port for injection and allocate an injection handle.

Parameters
portnumPorts are numbered from 0 to N-1 where 'N' is the number of Myricom ports available on the system. snf_getifaddrs() may be a useful utility to retrieve the port number by interface name or mac address if there are multiple
flagsFlags for injection handle. None are currently defined.
handleInjection handle allocated if the call is successful.
Return values
0Success. An injection handle is opened and allocated.
EBUSYRan out of injection handles for this port
ENOMEMRan out of memory to allocate new injection handle
int snf_inject_sched ( snf_inject_t  inj,
int  timeout_ms,
int  flags,
const void *  pkt,
uint32_t  length,
uint64_t  delay_ns 
)

Send a packet with hardware delay and optionally block until send resources are available.

This send function is used for paced packet injection. This function can be used as part of a packet replay program. When the function returns successfully, the packet is guaranteed to be completely buffered by SNF: no references are kept to the input data and the caller is free to safely modify its contents. The SNF implementation delays transmitting the packet according to the delay_ns parameter, relative to the start of the prior packet.

Parameters
injInjection handle
timeout_msTimeout in milliseconds to wait if insufficient send resources are available to inject a new packet. Insufficient resources can be a lack of send descriptors or a full send queue ring. If timeout_ms is 0, the function won't block for send resources and returns EAGAIN.
flagsFlags (currently none).
pktPointer to the packet to be sent. The packet must be a pointer to a complete Ethernet frame (without the trailing CRC) and start with a valid Ethernet header. The hardware will append 4-CRC bytes at the end of the packet. The maximum valid packet size is 9000 bytes and is enforced by the library. The minimum valid packet size is 60 bytes, although any packet smaller than 60 bytes will be accepted by the library and padded by the hardware.
lengthThe length of the packet, excluding the trailing 4 CRC bytes.
delay_nsThe minimum delay between the start of the prior packet and the start of this packet. Packets with a delay less than the time to send the prior packet are send immediately. It is recommened to use 0 as the delta on the first packet sent.
Return values
0Successful. The packet is buffered by SNF.
EAGAINInsufficient resources to send packet. If timeout_ms is non-zero, the caller will have blocked at least that many milliseconds before resources could become available.
EINVALPacket length is larger than 9000 bytes.
ENOTSUPThe hardware does not support injection pacing.
Postcondition
If successful, the packet is completely buffered for sending by SNF. The implementation guarantees that it will eventually send the packet out, as scheduled, without requiring further calls into SNF.
int snf_inject_sched_v ( snf_inject_t  inj,
int  timeout_ms,
int  flags,
struct snf_pkt_fragment frags_vec,
int  nfrags,
uint32_t  length_hint,
uint64_t  delay_ns 
)

Send a packet assembled from a vector of fragments at a scheduled point relative to the start of the prior packet and optionally block until send resources are available.

This send function follows the same semantics as snf_inject_send except that the packet to be injected can be assembled from multiple fragments (or buffers).

Parameters
injInjection handle
timeout_msTimeout in milliseconds to wait if insufficient send resources are available to inject a new packet. Insufficient resources can be a lack of send descriptors or a full send queue ring. If timeout_ms is 0, the function won't block for send resources and returns EAGAIN.
flagsFlags (currently none).
frags_vecPointer to a vector of 1 or more buffers/fragments that can be used to compose a complete Ethernet frame (not including the trailing CRC header). The first fragment must point to a valid Ethernet header and the hardware will append its own (valid 4-byte CRC) at the end of the last buffer/fragment passed in the frags_vec. When all the fragments are added up, the maximum valid packet size is 9000 bytes and is enforced by the library. The minimum valid packet size is 60 bytes, although any packet smaller than 60 bytes will be accepted by the library and padded by the hardware.
nfragsNumber of elements in the io vector
length_hintIf non-zero, the amount is expected to be the sum of all the lengths passed in the io vector. This parameters can help the library account for space when injecting packets.
delay_nsThe minimum delay between the start of the prior packet and the start of this packet. Packets with a delay less than the time to send the prior packet are send immediately. It is recommened to use 0 as the delta on the first packet sent.
Return values
0Successful. The packet is buffered by SNF.
EAGAINInsufficient resources to send packet. If timeout_ms is non-zero, the caller will have blocked at least that many milliseconds before resources could become available.
EINVALPacket length is larger than 9000 bytes.
ENOTSUPThe hardware does not support injection pacing.
Postcondition
If successful, the packet is completely buffered for send by SNF. The implementation guarantees that it will eventually send the packet out in a timely fashion without requiring further calls into SNF.
// Example that takes an existing packet and prepends the existing
// ethernet type with a vlan header.
//
int
send_prepend__vlan_tag(uint16_t vtag, void *pkt, uint32_t len)
{
uint32_t vlanhdr = htonl(0x8100 << 16 | vtag);
struct snf_pkt_fragment vec[3];
// We assume that the input 'pkt' does not already contain a vlan tag
// and that the pkt is not terminated with a CRC. The hardware will
// add the CRC. We also use no timeout in the send meaning that the
// send may return EAGAIN if there are insufficient resources to
// queue the send.
vec[0].ptr = (void *) pkt;
vec[0].length = 12; // dest and src mac
vec[1].ptr = &vlanhdr;
vec[1].length = sizeof(vlanhdr);
vec[2].ptr = (void *)((uint8_t *)pkt + 12);
vec[2].length = len - 12;
len += sizeof(vlanhdr);
// Schedule the packet to be sent 3 us. from the last.
return snf_inject_sched_v(hinj, 0, 0, vec, 3, len, 3000);
}
int snf_inject_send ( snf_inject_t  inj,
int  timeout_ms,
int  flags,
const void *  pkt,
uint32_t  length 
)

Send a packet and optionally block until send resources are available.

This send function is optimized for high packet rate injection. While it can be coupled with a receive ring to reinject a packet, it is not strictly necessary. This function can be used as part of a packet generator. When the function returns successfully, the packet is guaranteed to be completely buffered by SNF: no references are kept to the input data and the caller is free to safely modify its contents. A successful return does not, however, guarantee that the packet has been injected into the network. The SNF implementation may choose to hold on to the packet for coalescing in order to improve packet throughput.

Parameters
injInjection handle
timeout_msTimeout in milliseconds to wait if insufficient send resources are available to inject a new packet. Insufficient resources can be a lack of send descriptors or a full send queue ring. If timeout_ms is 0, the function won't block for send resources and returns EAGAIN.
flagsFlags (currently none).
pktPointer to the packet to be sent. The packet must be a pointer to a complete Ethernet frame (without the trailing CRC) and start with a valid Ethernet header. The hardware will append 4-CRC bytes at the end of the packet. The maximum valid packet size is 9000 bytes and is enforced by the library. The minimum valid packet size is 60 bytes, although any packet smaller than 60 bytes will be accepted by the library and padded by the hardware.
lengthThe length of the packet, excluding the trailing 4 CRC bytes.
Return values
0Successful. The packet is buffered by SNF.
EAGAINInsufficient resources to send packet. If timeout_ms is non-zero, the caller will have blocked at least that many milliseconds before resources could become available.
EINVALPacket length is larger than 9000 bytes.
Postcondition
If successful, the packet is completely buffered for sending by SNF. The implementation guarantees that it will eventually send the packet out in a timely fashion without requiring further calls into SNF.
int snf_inject_send_v ( snf_inject_t  inj,
int  timeout_ms,
int  flags,
struct snf_pkt_fragment frags_vec,
int  nfrags,
uint32_t  length_hint 
)

Send a packet assembled from a vector of fragments and optionally block until send resources are available.

This send function follows the same semantics as snf_inject_send except that the packet to be injected can be assembled from multiple fragments (or buffers).

Parameters
injInjection handle
timeout_msTimeout in milliseconds to wait if insufficient send resources are available to inject a new packet. Insufficient resources can be a lack of send descriptors or a full send queue ring. If timeout_ms is 0, the function won't block for send resources and returns EAGAIN.
flagsFlags (currently none).
frags_vecPointer to a vector of 1 or more buffers/fragments that can be used to compose a complete Ethernet frame (not including the trailing CRC header). The first fragment must point to a valid Ethernet header and the hardware will append its own (valid 4-byte CRC) at the end of the last buffer/fragment passed in the frags_vec. When all the fragments are added up, the maximum valid packet size is 9000 bytes and is enforced by the library. The minimum valid packet size is 60 bytes, although any packet smaller than 60 bytes will be accepted by the library and padded by the hardware.
nfragsNumber of elements in the io vector
length_hintIf non-zero, the amount is expected to be the sum of all the lengths passed in the io vector. This parameters can help the library account for space when injecting packets.
Return values
0Successful. The packet is buffered by SNF.
EAGAINInsufficient resources to send packet. If timeout_ms is non-zero, the caller will have blocked at least that many milliseconds before resources could become available.
EINVALPacket length (in length_hint or the sum of all frags_vec lens) is larger than 9000 bytes.
Postcondition
If successful, the packet is completely buffered for send by SNF. The implementation guarantees that it will eventually send the packet out in a timely fashion without requiring further calls into SNF.
// Example that takes an existing packet and prepends the existing
// ethernet type with a vlan header.
//
int
send_prepend__vlan_tag(uint16_t vtag, void *pkt, uint32_t len)
{
uint32_t vlanhdr = htonl(0x8100 << 16 | vtag);
struct snf_pkt_fragment vec[3];
// We assume that the input 'pkt' does not already contain a vlan tag
// and that the pkt is not terminated with a CRC. The hardware will
// add the CRC. We also use no timeout in the send meaning that the
// send may return EAGAIN if there are insufficient resources to
// queue the send.
vec[0].ptr = (void *) pkt;
vec[0].length = 12; // dest and src mac
vec[1].ptr = &vlanhdr;
vec[1].length = sizeof(vlanhdr);
vec[2].ptr = (void *)((uint8_t *)pkt + 12);
vec[2].length = len - 12;
len += sizeof(vlanhdr);
return snf_inject_send_v(hinj, 0, 0, vec, 3, len);
}
Myricom banner
Wed Jan 26 2022 18:21:06 - SNF 3.0.26.50935