A class that represents an RX/TX Enso Pipe. More...

#include <pipe.h>

Public Member Functions
	RxTxPipe (const RxTxPipe &)=delete

RxTxPipe &	operator= (const RxTxPipe &)=delete

	RxTxPipe (RxTxPipe &&)=delete

RxTxPipe &	operator= (RxTxPipe &&)=delete

int	Bind (uint16_t dst_port, uint16_t src_port, uint32_t dst_ip, uint32_t src_ip, uint32_t protocol)
	Binds the pipe to a given flow entry. Can be called multiple times to bind to multiple flows.

uint32_t	Recv (uint8_t **buf, uint32_t max_nb_bytes)
	Receives a batch of bytes.

uint32_t	Peek (uint8_t **buf, uint32_t max_nb_bytes)
	Receives a batch of bytes without removing them from the queue.

void	ConfirmBytes (uint32_t nb_bytes)
	Confirms a certain number of bytes have been received.

template<typename T >
RxPipe::MessageBatch< T >	RecvMessages (int32_t max_nb_messages=-1)
	Receives a batch of generic messages.

RxPipe::MessageBatch< PktIterator >	RecvPkts (int32_t max_nb_pkts=-1)
	Receives a batch of packets.

RxPipe::MessageBatch< PeekPktIterator >	PeekPkts (int32_t max_nb_pkts=-1)
	Receives a batch of packets without removing them from the queue.

void	Prefetch ()
	Prefetches the next batch of bytes to be received on the RxTxPipe.

void	SendAndFree (uint32_t nb_bytes)
	Sends and deallocates a given number of bytes.

void	ProcessCompletions ()
	Process completions for this pipe, potentially freeing up space to receive more data.

uint8_t *	buf () const
	Returns the pipe's internal buffer.

enso_pipe_id_t	rx_id () const
	Return the pipe's RX ID.

enso_pipe_id_t	tx_id () const
	Return the pipe's TX ID.

void *	context () const
	Returns the context associated with the pipe.

void	set_context (void *new_context)
	Sets the context associated with the pipe.

Static Public Attributes
static constexpr uint32_t	kQuantumSize = RxPipe::kQuantumSize

static constexpr uint32_t	kMaxCapacity = RxPipe::kMaxCapacity

Friends
class	Device

Detailed Description

A class that represents an RX/TX Enso Pipe.

This is suitable for applications that need to modify data in place and send them back. Should be instantiated using a Device object.

See also: RxPipe for a description of the common methods for RX.

Different from a TxPipe, an RxTxPipe can only be used to send data that has been received, after potentially modifying it in place. Therefore, it lacks most of the methods that are available in TxPipe.

Example:

auto device = Device::Create(core_id, nb_pipes, pcie_addr);
enso::RxTxPipe* rx_tx_pipe = device->AllocateRxTxPipe();
rx_tx_pipe->Bind(...);
 
auto batch = rx_tx_pipe->RecvPkts();
for (auto pkt : batch) {
  // Do something with the packet.
}
rx_tx_pipe->SendAndFree(batch_length);

Definition at line 1071 of file pipe.h.

Member Function Documentation

◆ Bind()

int enso::RxTxPipe::Bind	(	uint16_t	dst_port,
		uint16_t	src_port,
		uint32_t	dst_ip,
		uint32_t	src_ip,
		uint32_t	protocol
	)

inline

Binds the pipe to a given flow entry. Can be called multiple times to bind to multiple flows.

Warning: Currently the hardware ignores the source IP and source port for UDP packets. You must set them to 0 when binding to UDP.

Note: Binding semantics depend on the functionality implemented on the NIC. More flexible steering may require different kinds of bindings.

While binding semantics will vary for different NIC implementations, here we describe how the NIC implementation that accompanies Enso behaves.

Every call to Bind() will result in a new flow entry being created on the NIC using all the fields specified in the function arguments (5-tuple). For every incoming packet, the NIC will try to find a matching flow entry. If it does, it will steer the packet to the corresponding RX pipe. If it does not, it will steer the packet to one of the fallback pipes, or dropped if there are no fallback pipes.

The fields that are used to find a matching entry depend on the incoming packet:

If the packet protocol is TCP (6):
- If the SYN flag is set, the NIC will match it to a flow entry based on dst IP, dst port, and protocol, all the other fields will be set to 0 when looking for a matching flow entry.
- For TCP packets without a SYN flag set, the NIC will use all the fields, i.e., dst IP, dst port, src IP, src port, and protocol.
If the packet protocol is UDP (17), the NIC will use only dst IP, dst port, and protocol when looking for a matching flow entry. All the other fields will be set to 0.
For all the other protocols, the NIC will use only the destination IP when looking for a matching flow entry. All the other fields will be set to 0.

Therefore, if you want to listen for new TCP connections, you should bind to the destination IP and port and set all the other fields to 0. If you want to receive packets from an open TCP connection, you should bind to all the fields, i.e., dst IP, dst port, src IP, src port, and protocol. If you want to receive UDP packets, you should bind to the destination IP and port and set all the other fields to 0.

Parameters

dst_port	Destination port (little-endian).
src_port	Source port (little-endian).
dst_ip	Destination IP (little-endian).
src_ip	Source IP (little-endian).
protocol	Protocol (little-endian).

Returns: 0 on success, a different value otherwise.

Definition at line 1081 of file pipe.h.

◆ buf()

uint8_t * enso::RxTxPipe::buf ( ) const

inline

Returns the pipe's internal buffer.

Returns: A pointer to the start of the pipe's internal buffer.

Definition at line 1179 of file pipe.h.

◆ ConfirmBytes()

void enso::RxTxPipe::ConfirmBytes ( uint32_t nb_bytes )

inline

Confirms a certain number of bytes have been received.

This will make sure that the next call to Recv or Peek will return a buffer that starts at the next byte after the last confirmed byte.

When using Recv, this is not necessary, as Recv will automatically confirm the bytes received. You may use this to confirm bytes received by Peek.

Parameters

nb_bytes The number of bytes to confirm (must be a multiple of 64).

Definition at line 1105 of file pipe.h.

◆ context()

void * enso::RxTxPipe::context ( ) const

inline

Returns the context associated with the pipe.

Applications can use context to associate arbitrary pointers with a given pipe that can later be retrieved in a different point. For instance, when using Device::NextRxTxPipeToRecv(), the application may use the context to retrieve application data associated with the returned pipe.

See also: RxTxPipe::set_context()

Returns: The context associated with the pipe.

Definition at line 1207 of file pipe.h.

◆ Peek()

uint32_t enso::RxTxPipe::Peek	(	uint8_t **	buf,
		uint32_t	max_nb_bytes
	)

inline

Receives a batch of bytes without removing them from the queue.

Parameters

buf	A pointer that will be set to the start of the received bytes.
max_nb_bytes	The maximum number of bytes to receive.

Returns: The number of bytes received.

Definition at line 1097 of file pipe.h.

◆ PeekPkts()

RxPipe::MessageBatch< PeekPktIterator > enso::RxTxPipe::PeekPkts ( int32_t max_nb_pkts = -1 )

inline

Receives a batch of packets without removing them from the queue.

Parameters

max_nb_pkts The maximum number of packets to receive. If set to -1, all packets in the pipe will be received.

Returns: A MessageBatch object that can be used to iterate over the received packets.

Definition at line 1129 of file pipe.h.

◆ Prefetch()

void enso::RxTxPipe::Prefetch ( )

inline

Prefetches the next batch of bytes to be received on the RxTxPipe.

Warning: Explicit prefetching from the application cannot be used in conjunction with the NextRxPipeToRecv and NextRxTxPipeToRecv functions. These functions only support implicit prefetching, which can be enabled by compiling the library with -Dlatency_opt=true (the default).

Definition at line 1144 of file pipe.h.

◆ ProcessCompletions()

void enso::RxTxPipe::ProcessCompletions ( )

inline

Process completions for this pipe, potentially freeing up space to receive more data.

Definition at line 1164 of file pipe.h.

◆ Recv()

uint32_t enso::RxTxPipe::Recv	(	uint8_t **	buf,
		uint32_t	max_nb_bytes
	)

inline

Receives a batch of bytes.

Parameters

buf	A pointer that will be set to the start of the received bytes.
max_nb_bytes	The maximum number of bytes to receive.

Returns: The number of bytes received.

Definition at line 1089 of file pipe.h.

◆ RecvMessages()

template<typename T >

RxPipe::MessageBatch< T > enso::RxTxPipe::RecvMessages ( int32_t max_nb_messages = -1 )

inline

Receives a batch of generic messages.

Parameters

T	An iterator for the particular message type. Refer to `enso::PktIterator` for an example of a raw packet iterator.
max_nb_messages	The maximum number of messages to receive. If set to -1, all messages in the pipe will be received.

Returns: A MessageBatch object that can be used to iterate over the received messages.

Definition at line 1113 of file pipe.h.

◆ RecvPkts()

RxPipe::MessageBatch< PktIterator > enso::RxTxPipe::RecvPkts ( int32_t max_nb_pkts = -1 )

inline

Receives a batch of packets.

Parameters

max_nb_pkts The maximum number of packets to receive. If set to -1, all packets in the pipe will be received.

Returns: A MessageBatch object that can be used to iterate over the received packets.

Definition at line 1121 of file pipe.h.

◆ rx_id()

enso_pipe_id_t enso::RxTxPipe::rx_id ( ) const

inline

Return the pipe's RX ID.

Returns: The pipe's RX ID.

Definition at line 1186 of file pipe.h.

◆ SendAndFree()

void enso::RxTxPipe::SendAndFree ( uint32_t nb_bytes )

inline

Sends and deallocates a given number of bytes.

You can only send bytes that have been received and confirmed. Such as using Recv or a combination of Peek and ConfirmBytes, as well as the equivalent methods for raw packets and messages.

Parameters

nb_bytes The number of bytes to send.

Definition at line 1155 of file pipe.h.

◆ set_context()

void enso::RxTxPipe::set_context ( void * new_context )

inline

Sets the context associated with the pipe.

See also: RxTxPipe::context()

Definition at line 1214 of file pipe.h.

◆ tx_id()

enso_pipe_id_t enso::RxTxPipe::tx_id ( ) const

inline

Return the pipe's TX ID.

Returns: The pipe's TX ID.

Definition at line 1193 of file pipe.h.

Friends And Related Function Documentation

◆ Device

friend class Device

friend

Definition at line 1264 of file pipe.h.

Member Data Documentation

◆ kMaxCapacity

constexpr uint32_t enso::RxTxPipe::kMaxCapacity = RxPipe::kMaxCapacity

staticconstexpr

Maximum capacity achievable by the pipe. There should always be at least one buffer quantum available.

Definition at line 1226 of file pipe.h.

◆ kQuantumSize

constexpr uint32_t enso::RxTxPipe::kQuantumSize = RxPipe::kQuantumSize

staticconstexpr

The size of a "buffer quantum" in bytes. This is the minimum unit that can be sent at a time. Every transfer should be a multiple of this size.

Definition at line 1221 of file pipe.h.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Function Documentation

◆ Bind()

◆ buf()

◆ ConfirmBytes()

◆ context()

◆ Peek()

◆ PeekPkts()

◆ Prefetch()

◆ ProcessCompletions()

◆ Recv()

◆ RecvMessages()

◆ RecvPkts()

◆ rx_id()

◆ SendAndFree()

◆ set_context()

◆ tx_id()

Friends And Related Function Documentation

◆ Device

Member Data Documentation

◆ kMaxCapacity

◆ kQuantumSize