A class that represents a device. More...

#include <pipe.h>

Public Member Functions
	Device (const Device &)=delete

Device &	operator= (const Device &)=delete

	Device (Device &&)=delete

Device &	operator= (Device &&)=delete

RxPipe *	AllocateRxPipe (bool fallback=false) noexcept
	Allocates an RX pipe.

TxPipe *	AllocateTxPipe (uint8_t *buf=nullptr) noexcept
	Allocates a TX pipe.

int	GetNbFallbackQueues () noexcept
	Retrieves the number of fallback queues for this device.

RxTxPipe *	AllocateRxTxPipe (bool fallback=false) noexcept
	Allocates an RX/TX pipe.

RxPipe *	NextRxPipeToRecv ()
	Gets the next RxPipe that has data pending.

RxTxPipe *	NextRxTxPipeToRecv ()
	Gets the next RxTxPipe that has data pending.

void	ProcessCompletions ()
	Processes completions for all pipes associated with this device.

int	EnableTimeStamping (uint8_t offset=kDefaultRttOffset)
	Enables hardware time stamping.

int	DisableTimeStamping ()
	Disables hardware time stamping.

int	EnableRateLimiting (uint16_t num, uint16_t den)
	Enables hardware rate limiting.

int	DisableRateLimiting ()
	Disables hardware rate limiting.

int	EnableRoundRobin ()
	Enables round robing of packets among the fallback pipes.

int	DisableRoundRobin ()
	Disables round robing of packets among the fallback pipes. Will use a hash of the five-tuple to direct flows not binded to any pipe.

int	GetRoundRobinStatus () noexcept
	Gets the round robin status for the device.

int	ApplyConfig (struct TxNotification *config_notification)
	Sends the given config notification to the device.

Static Public Member Functions
static std::unique_ptr< Device >	Create (const std::string &pcie_addr="", const std::string &huge_page_prefix="") noexcept
	Factory method to create a device.

Friends
class	RxPipe

class	TxPipe

class	RxTxPipe

Detailed Description

A class that represents a device.

Should be instantiated using the factory method Create(). Use separate instances for each thread.

Example:

std::string pcie_addr = "0000:01:00.0";

auto device = Device::Create(pcie_addr);

enso::Device::Create

static std::unique_ptr< Device > Create(const std::string &pcie_addr="", const std::string &huge_page_prefix="") noexcept

Factory method to create a device.

Definition: pipe.cpp:149

Definition at line 82 of file pipe.h.

Constructor & Destructor Documentation

◆ ~Device()

enso::Device::~Device ( )

Definition at line 165 of file pipe.cpp.

Member Function Documentation

◆ AllocateRxPipe()

RxPipe * enso::Device::AllocateRxPipe ( bool fallback = false )

noexcept

Allocates an RX pipe.

Parameters

fallback Whether this pipe is a fallback pipe. Fallback pipes can receive data from any flow but are also guaranteed to receive data from all flows that they Bind() to.

Note: The hardware can only use a number of fallback pipes that is a power of two. If the number of fallback pipes is not a power of two, only the first power of two pipes allocated will be used.

Warning: Fallback pipes should be used by only one application at a time. If multiple applications use fallback pipes at once, the behavior is undefined.

Returns: A pointer to the pipe. May be null if the pipe cannot be created.

Definition at line 183 of file pipe.cpp.

◆ AllocateRxTxPipe()

RxTxPipe * enso::Device::AllocateRxTxPipe ( bool fallback = false )

noexcept

Allocates an RX/TX pipe.

Parameters

fallback Whether this pipe is a fallback pipe. Fallback pipes can receive data from any flow but are also guaranteed to receive data from all flows that they Bind() to.

Note: The hardware can only use a number of fallback pipes that is a power of two. If the number of fallback pipes is not a power of two, only the first power of two pipes allocated will be used.

Warning: Fallback pipes should be used by only one application at a time. If multiple applications use fallback pipes at once, the behavior is undefined.

Returns: A pointer to the pipe. May be null if the pipe cannot be created.

Definition at line 222 of file pipe.cpp.

◆ AllocateTxPipe()

TxPipe * enso::Device::AllocateTxPipe ( uint8_t * buf = nullptr )

noexcept

Allocates a TX pipe.

Parameters

buf	Buffer address to use for the pipe. It must be a pinned hugepage. If not specified, the buffer is allocated internally.

Returns: A pointer to the pipe. May be null if the pipe cannot be created.

Definition at line 205 of file pipe.cpp.

◆ ApplyConfig()

int enso::Device::ApplyConfig ( struct TxNotification * config_notification )

Sends the given config notification to the device.

Parameters

config_notification The config notification.

Returns: 0 on success, -1 on failure.

Definition at line 356 of file pipe.cpp.

◆ Create()

std::unique_ptr< Device > enso::Device::Create	(	const std::string &	pcie_addr = `""`,
		const std::string &	huge_page_prefix = `""`
	)

staticnoexcept

Factory method to create a device.

Parameters

pcie_addr	The PCIe address of the device. If empty, uses the first device found.
huge_page_prefix	The prefix to use for huge pages file. If empty, uses the default prefix.

Returns: A unique pointer to the device. May be null if the device cannot be created.

Definition at line 149 of file pipe.cpp.

◆ DisableRateLimiting()

int enso::Device::DisableRateLimiting ( )

Disables hardware rate limiting.

Note: This setting applies to all pipes that share the same hardware device.

See also: EnableRateLimiting

Returns: 0 if configuration was successful.

Definition at line 412 of file pipe.cpp.

◆ DisableRoundRobin()

int enso::Device::DisableRoundRobin ( )

Disables round robing of packets among the fallback pipes. Will use a hash of the five-tuple to direct flows not binded to any pipe.

Note: This setting applies to all pipes that share the same hardware device.

See also: EnableRoundRobin

Returns: 0 if configuration was successful.

Definition at line 424 of file pipe.cpp.

◆ DisableTimeStamping()

int enso::Device::DisableTimeStamping ( )

Disables hardware time stamping.

Note: This setting applies to all pipes that share the same hardware device.

See also: EnableTimeStamping

Definition at line 404 of file pipe.cpp.

◆ EnableRateLimiting()

int enso::Device::EnableRateLimiting	(	uint16_t	num,
		uint16_t	den
	)

Enables hardware rate limiting.

Once rate limiting is enabled, packets from all queues are sent at a rate of num / den * kMaxHardwareFlitRate flits per second (a flit is 64 bytes). Note that this is slightly different from how we typically define throughput and you will need to take the packet sizes into account to set this properly.

For example, suppose that you are sending 64-byte packets. Each packet occupies exactly one flit. For this packet size, line rate at 100Gbps is 148.8Mpps. So if kMaxHardwareFlitRate is 200MHz, line rate actually corresponds to a 744/1000 rate. Therefore, if you want to send at 50Gbps (50% of line rate), you can use a 372/1000 (or 93/250) rate.

The other thing to notice is that, while it might be tempting to use a large denominator in order to increase the rate precision. This has the side effect of increasing burstiness. The way the rate limit is implemented, we send a burst of num consecutive flits every den cycles. Which means that if num is too large, it might overflow the receiver buffer. For instance, in the example above, 93/250 would be a better rate than 372/1000. And 3/8 would be even better with a slight loss in precision.

You can find the maximum packet rate for any packet size by using the expression: line_rate / ((pkt_size + 20) * 8). So for 100Gbps and 128-byte packets we have: 100e9 / ((128 + 20) * 8) packets per second. Given that each packet is two flits, for kMaxHardwareFlitRate = 200e6, the maximum rate is 100e9 / ((128 + 20) * 8) * 2 / 200e6, which is approximately 125/148. Therefore, if you want to send packets at 20Gbps (20% of line rate), you should use a 25/148 rate.

Note: This setting applies to all pipes that share the same hardware device.

See also: DisableRateLimiting

Parameters

num	Rate numerator.
den	Rate denominator.

Returns: 0 if configuration was successful.

Definition at line 408 of file pipe.cpp.

◆ EnableRoundRobin()

int enso::Device::EnableRoundRobin ( )

Enables round robing of packets among the fallback pipes.

Note: This setting applies to all pipes that share the same hardware device.

See also: DisableRoundRobin

Returns: 0 if configuration was successful.

Definition at line 416 of file pipe.cpp.

◆ EnableTimeStamping()

int enso::Device::EnableTimeStamping ( uint8_t offset = kDefaultRttOffset )

Enables hardware time stamping.

All outgoing packets will receive a timestamp and all incoming packets will have an RTT (in number of cycles). Use get_pkt_rtt to retrieve the value.

Note: This setting applies to all pipes that share the same hardware device.

See also: DisableTimeStamping; get_pkt_rtt

Parameters

offset Packet offset to place the timestamp, default is kDefaultRttOffset bytes.

Definition at line 400 of file pipe.cpp.

◆ GetNbFallbackQueues()

int enso::Device::GetNbFallbackQueues ( )

noexcept

Retrieves the number of fallback queues for this device.

Definition at line 201 of file pipe.cpp.

◆ GetRoundRobinStatus()

int enso::Device::GetRoundRobinStatus ( )

noexcept

Gets the round robin status for the device.

Returns: 0 if round robin is disabled, 1 if round robin is enabled, -1 on failure.

Definition at line 420 of file pipe.cpp.

◆ NextRxPipeToRecv()

RxPipe * enso::Device::NextRxPipeToRecv ( )

Gets the next RxPipe that has data pending.

Warning: This function can only be used when there are only RX pipes. Trying to use this function when there are RX/TX pipes will result in undefined behavior.

Returns: A pointer to the pipe. May be nullptr if no pipe has data pending.

Definition at line 241 of file pipe.cpp.

◆ NextRxTxPipeToRecv()

RxTxPipe * enso::Device::NextRxTxPipeToRecv ( )

Gets the next RxTxPipe that has data pending.

Warning: This function can only be used when there are only RX/TX pipes. Trying to use this function when there are RX pipes allocated will result in undefined behavior.

Returns: A pointer to the pipe. May be nullptr if no pipe has data pending.

Definition at line 281 of file pipe.cpp.

◆ ProcessCompletions()

void enso::Device::ProcessCompletions ( )

Processes completions for all pipes associated with this device.

Definition at line 383 of file pipe.cpp.

Friends And Related Function Documentation

◆ RxPipe

friend class RxPipe

friend

Definition at line 348 of file pipe.h.

◆ RxTxPipe

friend class RxTxPipe

friend

Definition at line 350 of file pipe.h.

◆ TxPipe

friend class TxPipe

friend

Definition at line 349 of file pipe.h.

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

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~Device()

Member Function Documentation

◆ AllocateRxPipe()

◆ AllocateRxTxPipe()

◆ AllocateTxPipe()

◆ ApplyConfig()

◆ Create()

◆ DisableRateLimiting()

◆ DisableRoundRobin()

◆ DisableTimeStamping()

◆ EnableRateLimiting()

◆ EnableRoundRobin()

◆ EnableTimeStamping()

◆ GetNbFallbackQueues()

◆ GetRoundRobinStatus()

◆ NextRxPipeToRecv()

◆ NextRxTxPipeToRecv()

◆ ProcessCompletions()

Friends And Related Function Documentation

◆ RxPipe

◆ RxTxPipe

◆ TxPipe