A class that represents a TX Enso Pipe. More...

#include <pipe.h>

Public Member Functions
	TxPipe (const TxPipe &)=delete

TxPipe &	operator= (const TxPipe &)=delete

	TxPipe (TxPipe &&)=delete

TxPipe &	operator= (TxPipe &&)=delete

uint8_t *	AllocateBuf (uint32_t target_capacity=0)
	Allocates a buffer in the pipe.

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

uint32_t	TryExtendBuf ()
	Explicitly requests a best-effort buffer extension.

uint32_t	ExtendBufToTarget (uint32_t target_capacity)
	Explicitly requests a buffer extension with a target capacity.

uint32_t	capacity () const
	Returns the allocated buffer's current available capacity.

uint32_t	pending_transmission () const
	Returns the number of bytes that are currently being transmitted.

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 a TX Enso Pipe.

Should be instantiated using a Device object.

Example:

enso::Device* device = enso::Device::Create(pcie_addr);
enso::TxPipe* tx_pipe = device->AllocateTxPipe();
uint8_t* buf = tx_pipe->AllocateBuf(data_size);
 
// AllocateBuf with a non-zero argument may block waiting for the capacity
// to be free. Alternatively, one may use AllocateBuf with data_size = 0
// and use and useTryExtendBuf to avoid blocking, potentially dropping
// data instead of waiting.
 
// Fill the buffer with data.
[...]
 
// Send the data and retrieve a new buffer.
tx_pipe->SendAndFree(data_size);
buf = tx_pipe.AllocateBuf(data_size);

Definition at line 777 of file pipe.h.

Member Function Documentation

◆ AllocateBuf()

uint8_t * enso::TxPipe::AllocateBuf ( uint32_t target_capacity = 0 )

inline

Allocates a buffer in the pipe.

There can only be a single buffer allocated at a time for a given Pipe. Calling this function again when a buffer is already allocated will return the same address.

The buffer capacity can be retrieved by calling capacity(). Note that the buffer capacity can increase without notice but will never decrease. The user can also explicitly request for the buffer to be extended by calling ExtendBufToTarget().

The buffer is valid until the user calls SendAndFree(). In which case, the buffer will be freed and a new one must be allocated by calling this function again.

If SendAndFree() only partially sends the buffer, the previous buffer address will still not be valid. But allocating a new buffer will return a a buffers that starts with the remaining data.

Warning: The capacity will never be go beyond TxPipe::kMaxCapacity. Therefore, specifying a target_capacity larger than TxPipe::kMaxCapacity will cause this function to block forever.

Parameters

target_capacity Target capacity of the buffer. It will block until the buffer is at least this big. May set it to 0 to avoid blocking (the default).

Returns: The allocated buffer address.

Definition at line 814 of file pipe.h.

◆ buf()

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

inline

Returns the pipe's internal buffer.

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

Definition at line 917 of file pipe.h.

◆ capacity()

uint32_t enso::TxPipe::capacity ( ) const

inline

Returns the allocated buffer's current available capacity.

The buffer capacity can increase without notice but will never decrease. The user can use this function to check the current capacity.

Returns: The capacity of the allocated buffer in bytes.

Definition at line 899 of file pipe.h.

◆ context()

void * enso::TxPipe::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.

See also: TxPipe::set_context()

Returns: The context associated with the pipe.

Definition at line 936 of file pipe.h.

◆ ExtendBufToTarget()

uint32_t enso::TxPipe::ExtendBufToTarget ( uint32_t target_capacity )

inline

Explicitly requests a buffer extension with a target capacity.

Different from TryExtendBuf(), this function will block until the capacity is at least as large as the target capacity. Other than that the behavior is the same.

User may use capacity() to check the total number of available bytes after calling this function or simply use the return value.

Warning: The capacity will never be extended beyond TxPipe::kMaxCapacity. Therefore, specifying a target capacity larger than TxPipe::kMaxCapacity will block forever.

Returns: The new buffer capacity after extending.

Definition at line 882 of file pipe.h.

◆ id()

enso_pipe_id_t enso::TxPipe::id ( ) const

inline

Returns the pipe's ID.

Returns: The pipe's ID.

Definition at line 924 of file pipe.h.

◆ pending_transmission()

uint32_t enso::TxPipe::pending_transmission ( ) const

inline

Returns the number of bytes that are currently being transmitted.

Returns: Number of bytes pending transmission.

Definition at line 908 of file pipe.h.

◆ SendAndFree()

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

inline

Sends and deallocates a given number of bytes.

After calling this function, the previous buffer address is no longer valid. Accessing it will lead to undefined behavior.

Note: The user must use AllocateBuf() to allocate a new buffer after calling this function.

The pipe's capacity will also be reduced by the number of bytes sent. If sending more bytes than the pipe's current capacity, the behavior is undefined. The user must also make sure not to modify the sent bytes after calling this function.

Parameters

nb_bytes The number of bytes to send. Must be a multiple of kQuantumSize.

Definition at line 836 of file pipe.h.

◆ set_context()

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

inline

Sets the context associated with the pipe.

See also: TxPipe::context()

Definition at line 943 of file pipe.h.

◆ TryExtendBuf()

uint32_t enso::TxPipe::TryExtendBuf ( )

inline

Explicitly requests a best-effort buffer extension.

Will check for completed transmissions to try to extend the capacity of the currently allocated buffer. After this, capacity will be at least as large as it was before. The user can continue to use the same buffer address as before.

User may use capacity() to check the total number of available bytes after calling this function or simply use the return value.

Note: The capacity will never be extended beyond TxPipe::kMaxCapacity.

Returns: The new buffer capacity after extending.

Definition at line 861 of file pipe.h.

Friends And Related Function Documentation

◆ Device

friend class Device

friend

Definition at line 999 of file pipe.h.

Member Data Documentation

◆ kMaxCapacity

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

staticconstexpr

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

Definition at line 955 of file pipe.h.

◆ kQuantumSize

constexpr uint32_t enso::TxPipe::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 949 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

◆ AllocateBuf()

◆ buf()

◆ capacity()

◆ context()

◆ ExtendBufToTarget()

◆ id()

◆ pending_transmission()

◆ SendAndFree()

◆ set_context()

◆ TryExtendBuf()

Friends And Related Function Documentation

◆ Device

Member Data Documentation

◆ kMaxCapacity

◆ kQuantumSize