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

#include <pipe.h>

Classes
class	MessageBatch
	A class that represents a batch of messages. More...

Public Member Functions
	RxPipe (const RxPipe &)=delete

RxPipe &	operator= (const RxPipe &)=delete

	RxPipe (RxPipe &&)=delete

RxPipe &	operator= (RxPipe &&)=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.

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

constexpr uint32_t	capacity () const
	Returns the number of bytes allocated in the pipe, i.e., the number of bytes owned by the application.

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

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

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 RxPipe.

void	Free (uint32_t nb_bytes)
	Frees a given number of bytes previously received on the RxPipe.

void	Clear ()
	Frees all bytes previously received on the RxPipe.

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

enso_pipe_id_t	id () const
	Returns the pipe's 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 = 64

static constexpr uint32_t	kMaxCapacity = kEnsoPipeSize * 64 - kQuantumSize

Friends
class	Device

Detailed Description

A class that represents an RX Enso Pipe.

Should be instantiated using a Device object.

Example:

Device* device = Device::Create(core_id, nb_pipes, pcie_addr);
RxPipe* rx_pipe = device->AllocateRxPipe();
rx_pipe->Bind(...);
 
auto batch = rx_pipe->RecvPkts();
for (auto pkt : batch) {
  // Do something with the packet.
}
rx_pipe->Clear();

Definition at line 389 of file pipe.h.

Member Function Documentation

◆ Bind()

int enso::RxPipe::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.

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 64 of file pipe.cpp.

◆ buf()

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

inline

Returns the pipe's internal buffer.

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

Definition at line 673 of file pipe.h.

◆ capacity()

constexpr uint32_t enso::RxPipe::capacity ( ) const

inlineconstexpr

Returns the number of bytes allocated in the pipe, i.e., the number of bytes owned by the application.

Returns: The number of bytes allocated in the pipe.

Definition at line 590 of file pipe.h.

◆ Clear()

void enso::RxPipe::Clear ( )

Frees all bytes previously received on the RxPipe.

See also: Free()

Definition at line 91 of file pipe.cpp.

◆ ConfirmBytes()

constexpr void enso::RxPipe::ConfirmBytes ( uint32_t nb_bytes )

inlineconstexpr

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 578 of file pipe.h.

◆ context()

void * enso::RxPipe::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::NextRxPipeToRecv(), the application may use the context to retrieve application data associated with the returned pipe.

See also: RxPipe::set_context()

Returns: The context associated with the pipe.

Definition at line 694 of file pipe.h.

◆ Free()

void enso::RxPipe::Free ( uint32_t nb_bytes )

Frees a given number of bytes previously received on the RxPipe.

See also: Clear()

Parameters

nb_bytes The number of bytes to free.

Definition at line 85 of file pipe.cpp.

◆ id()

enso_pipe_id_t enso::RxPipe::id ( ) const

inline

Returns the pipe's ID.

Returns: The pipe's ID.

Definition at line 680 of file pipe.h.

◆ Peek()

uint32_t enso::RxPipe::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 76 of file pipe.cpp.

◆ PeekPkts()

MessageBatch< PeekPktIterator > enso::RxPipe::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 637 of file pipe.h.

◆ Prefetch()

void enso::RxPipe::Prefetch ( )

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

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 89 of file pipe.cpp.

◆ Recv()

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

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 70 of file pipe.cpp.

◆ RecvMessages()

template<typename T >

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

inlineconstexpr

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 609 of file pipe.h.

◆ RecvPkts()

MessageBatch< PktIterator > enso::RxPipe::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 624 of file pipe.h.

◆ set_context()

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

inline

Sets the context associated with the pipe.

See also: RxPipe::context()

Definition at line 701 of file pipe.h.

Friends And Related Function Documentation

◆ Device

friend class Device

friend

Definition at line 742 of file pipe.h.

Member Data Documentation

◆ kMaxCapacity

constexpr uint32_t enso::RxPipe::kMaxCapacity = kEnsoPipeSize * 64 - kQuantumSize

staticconstexpr

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

Definition at line 713 of file pipe.h.

◆ kQuantumSize

constexpr uint32_t enso::RxPipe::kQuantumSize = 64

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 707 of file pipe.h.

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

Classes

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Function Documentation

◆ Bind()

◆ buf()

◆ capacity()

◆ Clear()

◆ ConfirmBytes()

◆ context()

◆ Free()

◆ id()

◆ Peek()

◆ PeekPkts()

◆ Prefetch()

◆ Recv()

◆ RecvMessages()

◆ RecvPkts()

◆ set_context()

Friends And Related Function Documentation

◆ Device

Member Data Documentation

◆ kMaxCapacity

◆ kQuantumSize