The declarations in this header file correspond to the definitions in adapter.c. More...

#include <stdbool.h>
#include <stdint.h>
#include "endpoint_manager.h"
#include "cdi_raw_api.h"

Data Structures
struct	Packet

struct	AdapterEndpointState
	Structure used to hold adapter endpoint state. More...

struct	RxAdapterConnectionState
	This defines a structure that contains the state information for an rx adapter connection. More...

struct	AdapterDataConnectionState
	This defines a structure that contains the state information for a data adapter connection (type is kEndpointTypeData). This adapter type is used to transmit all data that is not part of a control interface. More...

struct	AdapterControlConnectionState
	This defines a structure that contains the state information for a control interface adapter connection (type is kEndpointTypeControl). More...

struct	PollThreadState
	This defines a structure that contains the state information for a single instance of a poll thread. More...

struct	ThreadUtilizationState
	Type used to hold thread utilization state data. More...

struct	AdapterConnectionState
	Structure used to hold adapter connection state. More...

struct	AdapterVirtualFunctionPtrTable
	Structure definition used to define the virtual table API interface for adapters. More...

struct	CdiAdapterState
	Structure definition behind the handles shared with the user's application program. Its contents are opaque to the user's program where it only has a pointer to a declared but not defined structure. More...

struct	CdiAdapterConnectionConfigData
	Structure definition used to configure an adapter endpoint. More...

struct	CdiAdapterEndpointConfigData
	Structure definition used to configure an adapter endpoint. More...

Typedefs
typedef struct ControlInterfaceState *	ControlInterfaceHandle
	Forward reference.

typedef void(*	MessageFromEndpoint) (void param_ptr, Packet packet_ptr, EndpointMessageType message_type)
	Prototype of function used to process packet messages from the endpoint.

typedef struct AdapterEndpointState *	AdapterEndpointHandle
	Forward declaration to create pointer to adapter endpoint state when used.

typedef struct AdapterConnectionState *	AdapterConnectionHandle
	Forward declaration to create pointer to adapter connection state when used.

Enumerations
enum	AdapterPacketAckStatus { kAdapterPacketStatusOk , kAdapterPacketStatusFailed , kAdapterPacketStatusNotConnected }
	Values used for adapter packet acknowledgment status. More...

enum	EndpointDirection { kEndpointDirectionSend , kEndpointDirectionReceive , kEndpointDirectionBidirectional }
	The direction of packets that an endpoint will be used for. More...

enum	EndpointDataType { kEndpointTypeData , kEndpointTypeControl }
	The type of transmission data that an endpoint will be used for. More...

enum	EndpointTransmitQueueLevel { kEndpointTransmitQueueEmpty , kEndpointTransmitQueueIntermediate , kEndpointTransmitQueueFull , kEndpointTransmitQueueNa }

enum	EndpointMessageType { kEndpointMessageTypePacketSent , kEndpointMessageTypePacketReceived }

enum	PollState { kPollStart , kPollRunning , kPollStopping , kPollStopped }
	Values used to determine current running state of a poll thread. More...

Functions
CdiReturnStatus	EfaNetworkAdapterInitialize (CdiAdapterState *adapter_state_ptr, bool is_socket_based)

CdiReturnStatus	SocketNetworkAdapterInitialize (CdiAdapterState *adapter_state_ptr)

CdiReturnStatus	CdiAdapterCreateConnection (CdiAdapterConnectionConfigData config_data_ptr, AdapterConnectionHandle return_handle_ptr)

CdiReturnStatus	CdiAdapterStopConnection (AdapterConnectionHandle handle)

CdiReturnStatus	CdiAdapterDestroyConnection (AdapterConnectionHandle handle)

CdiReturnStatus	CdiAdapterOpenEndpoint (CdiAdapterEndpointConfigData config_data_ptr, AdapterEndpointHandle return_handle_ptr)

CdiReturnStatus	CdiAdapterStartEndpoint (AdapterEndpointHandle handle)

CdiReturnStatus	CdiAdapterResetEndpoint (AdapterEndpointHandle handle)

CdiReturnStatus	CdiAdapterCloseEndpoint (AdapterEndpointHandle handle)

CdiReturnStatus	CdiAdapterPollEndpoint (AdapterEndpointHandle handle)

EndpointTransmitQueueLevel	CdiAdapterGetTransmitQueueLevel (AdapterEndpointHandle handle)

CdiReturnStatus	CdiAdapterEnqueueSendPacket (const AdapterEndpointHandle handle, const struct sockaddr_in destination_address_ptr, Packet packet_ptr)

CdiReturnStatus	CdiAdapterEnqueueSendPackets (const AdapterEndpointHandle handle, const CdiSinglyLinkedList *packet_list_ptr)

CdiReturnStatus	CdiAdapterFreeBuffer (const AdapterEndpointHandle handle, const CdiSgList *sgl_ptr)

CdiReturnStatus	CdiAdapterGetPort (const AdapterEndpointHandle handle, int *port_number_ptr)

CdiReturnStatus	CdiAdapterShutdown (CdiAdapterHandle adapter)

void	CdiAdapterPollThreadFlushResources (AdapterEndpointHandle handle)

void	CdiAdapterTxPacketComplete (AdapterEndpointHandle handle, const Packet *packet_ptr)

Detailed Description

The declarations in this header file correspond to the definitions in adapter.c.

Typedef Documentation

◆ MessageFromEndpoint

typedef void(* MessageFromEndpoint) (void *param_ptr, Packet *packet_ptr, EndpointMessageType message_type)

Prototype of function used to process packet messages from the endpoint.

Parameters

param_ptr	A pointer to data used by the function.
packet_ptr	A pointer to packet state data.
message_type	Endpoint message type.

Enumeration Type Documentation

◆ AdapterPacketAckStatus

enum AdapterPacketAckStatus

Values used for adapter packet acknowledgment status.

Enumerator
kAdapterPacketStatusOk	The transmitted packet was acknowledged to have been received.
kAdapterPacketStatusFailed	The packet transmission resulted in an error.
kAdapterPacketStatusNotConnected	The packet could not be sent because the adapter endpoint isn't connected.

◆ EndpointDataType

enum EndpointDataType

The type of transmission data that an endpoint will be used for.

Enumerator
kEndpointTypeData	Endpoint used for normal data transmission.
kEndpointTypeControl	Endpoint used for control command transmission (uses sockets).

◆ EndpointDirection

enum EndpointDirection

The direction of packets that an endpoint will be used for.

Enumerator
kEndpointDirectionSend	Endpoint can send packets to its remote host.
kEndpointDirectionReceive	Endpoint can receive packets from its remote host.
kEndpointDirectionBidirectional	Endpoint can send packets to and receive from the remote host.

◆ EndpointMessageType

enum EndpointMessageType

Enumeration of possible values used to specify the type of message generated from an endpoint using the MessageFromEndpoint callback function.

Enumerator
kEndpointMessageTypePacketSent	Packet was sent.
kEndpointMessageTypePacketReceived	Packet was received.

◆ EndpointTransmitQueueLevel

enum EndpointTransmitQueueLevel

Enumeration of possible values that can be returned from the EfaGetTransmitQueueLevel() adapter API function.

Enumerator
kEndpointTransmitQueueEmpty	Transmit queue has no packets in it.
kEndpointTransmitQueueIntermediate	Transmit queue is somewhere between empty and full.
kEndpointTransmitQueueFull	Transmit queue has room for no more packets.
kEndpointTransmitQueueNa	Endpoint is not a polled mode driver.

◆ PollState

enum PollState

Values used to determine current running state of a poll thread.

Enumerator
kPollStart	Poll thread is starting and has not ran through a pool loop yet.
kPollRunning	Poll thread has ran through at least one poll loop.
kPollStopping	Poll thread is stopping.
kPollStopped	Poll thread stopped.

Function Documentation

◆ CdiAdapterCloseEndpoint()

CdiReturnStatus CdiAdapterCloseEndpoint ( AdapterEndpointHandle handle )

Close an endpoint and free its resources.

Parameters

handle The handle of the endpoint which is to be closed.

Returns: CdiReturnStatus kCdiStatusOk upon success otherwise an indication of the failure.

◆ CdiAdapterCreateConnection()

CdiReturnStatus CdiAdapterCreateConnection	(	CdiAdapterConnectionConfigData *	config_data_ptr,
		AdapterConnectionHandle *	return_handle_ptr )

Create an adapter connection. An endpoint is a one-way communications channel on which packets can be sent to or received from a remote host whose address and port number are specified here.

NOTE: This API only creates resources used by the endpoint. The CdiAdapterStartEndpoint() function must be used to start it.

Parameters

config_data_ptr	Pointer to adapter endpoint config data.
return_handle_ptr	The address of a location to have the newly opened endpoint's handle written.

Returns: CdiReturnStatus kCdiStatusOk upon successful open otherwise an indication of the failure.

◆ CdiAdapterDestroyConnection()

CdiReturnStatus CdiAdapterDestroyConnection ( AdapterConnectionHandle handle )

Destroy a connnection closing related open endpoints, freeing their resources.

Parameters

handle The handle of the connection which is to be closed.

Returns: CdiReturnStatus kCdiStatusOk upon success otherwise an indication of the failure.

◆ CdiAdapterEnqueueSendPacket()

CdiReturnStatus CdiAdapterEnqueueSendPacket	(	const AdapterEndpointHandle	handle,
		const struct sockaddr_in *	destination_address_ptr,
		Packet *	packet_ptr )

Add a single packet to the send packet queue. The packet will be sent to the remote host for the specified endpoint. Only valid for endpoints that were open for sending. NOTE: This function is called by the main payload thread TxPayloadThread() as well as by EFA probe control. MEMORY NOTE: The Packet structure is not copied, it is merely referenced. Its storage must come from a pool.

Parameters

handle	The handle of the endpoint through which to send the packet.
destination_address_ptr	Pointer to destination address data (sockaddr_in).
packet_ptr	The address of the packet to enqueue for sending to the connected endpoint.

Returns: CdiReturnStatus kCdiStatusOk if the packet was successfully queued for sending or a value that indicates the nature of the failure.

◆ CdiAdapterEnqueueSendPackets()

CdiReturnStatus CdiAdapterEnqueueSendPackets	(	const AdapterEndpointHandle	handle,
		const CdiSinglyLinkedList *	packet_list_ptr )

Add a list of packets to the send packet queue. The packets will be sent to the remote host for the specified endpoint. Only valid for endpoints that were open for sending. NOTE: This function is called by the main payload thread TxPayloadThread() as well as by EFA probe control. MEMORY NOTE: While the packet_list_ptr's contents are copied, the Packet structures referenced by it are not copied. Their storage must come from a pool.

Parameters

handle	The handle of the endpoint through which to send the packet.
packet_list_ptr	The address of the list of packets to enqueue for sending to the connected endpoint.

Returns: CdiReturnStatus kCdiStatusOk if the packet was successfully queued for sending or kCdiStatusQueueFull if the packet could not be queued on account of the queue being full.

◆ CdiAdapterFreeBuffer()

CdiReturnStatus CdiAdapterFreeBuffer	(	const AdapterEndpointHandle	handle,
		const CdiSgList *	sgl_ptr )

Free a buffer that was provided by the endpoint in a received packet through the queue function. The resources returned to the endpoint include the SGList structure, all of the SGL entries in the list, and the memory buffers addressed by the entries.

Parameters

handle	The handle of the endpoint from which the packet was received.
sgl_ptr	The SGL describing the resources to be returned to the endpoint.

Returns: CdiReturnStatus kCdiStatusOk if the packet buffer memory was successfully freed or a value that indicates the nature of the failure.

◆ CdiAdapterGetPort()

CdiReturnStatus CdiAdapterGetPort	(	const AdapterEndpointHandle	handle,
		int *	port_number_ptr )

Gets the number of the port to which the specified endpoint is using.

Parameters

handle	The handle of the endpoint to get the port number from.
port_number_ptr	Address of where the port number will be written.

Returns: CdiReturnStatus kCdiStatusOk if the packet buffer memory was successfully freed or a value that indicates the nature of the failure.

◆ CdiAdapterGetTransmitQueueLevel()

EndpointTransmitQueueLevel CdiAdapterGetTransmitQueueLevel ( AdapterEndpointHandle handle )

Checks transmitter queue level. A polled mode endpoint will return kEndpointTransmitBufferFull when its transmit queue is full while awaiting acknowledgements. Non-polled endpoints always return kEndpointTransmitBufferNa.

Parameters

handle The handle of the endpoint for which to check its transmit queue level.

Returns: EndpointTransmitQueueLevel a value indicating the current fullness of the transmit queue.

◆ CdiAdapterOpenEndpoint()

CdiReturnStatus CdiAdapterOpenEndpoint	(	CdiAdapterEndpointConfigData *	config_data_ptr,
		AdapterEndpointHandle *	return_handle_ptr )

Opens an endpoint for the specified connection. An endpoint is a one-way communications channel on which packets can be sent to or received from a remote host whose address and port number are specified here.

NOTE: This function only creates resources used by the endpoint. The CdiAdapterStartEndpoint() function must be used to start it.

Parameters

config_data_ptr	Pointer to adapter endpoint config data.
return_handle_ptr	The address of a location to have the newly opened endpoint's handle written.

Returns: CdiReturnStatus kCdiStatusOk upon successful open otherwise an indication of the failure.

◆ CdiAdapterPollEndpoint()

CdiReturnStatus CdiAdapterPollEndpoint ( AdapterEndpointHandle handle )

While a connection is open, this API function must be called on a regular basis to perform poll mode processing without having to create additional adapter worker threads.

Parameters

handle The handle of the endpoint to poll.

Returns: either kCdiStatusInternalIdle or kCdiStatusOk if successful, otherwise a value that indicates the nature of the failure is returned. kCdiStatusInternalIdle means that the function performed no productive work while kCdiStatusOk says that did.

◆ CdiAdapterPollThreadFlushResources()

void CdiAdapterPollThreadFlushResources ( AdapterEndpointHandle handle )

Flush resources associate with PollThread(). NOTE: This function should only be called after the thread has been paused using EndpointManagerThreadWait().

Parameters

handle The handle of the endpoint to flush resources.

◆ CdiAdapterResetEndpoint()

CdiReturnStatus CdiAdapterResetEndpoint ( AdapterEndpointHandle handle )

Reset an endpoint and free its resources.

Parameters

handle The handle of the endpoint to reset.

Returns: CdiReturnStatus kCdiStatusOk upon success otherwise an indication of the failure.

◆ CdiAdapterShutdown()

CdiReturnStatus CdiAdapterShutdown ( CdiAdapterHandle adapter )

Shut down the adapter and free all of the resources associated with it. The caller must not use the adapter's handle for any purpose after this function returns.

Parameters

adapter A handle to the adapter to close.

Returns: CdiReturnStatus kCdiStatusOk if the close operation was successfully or a value that indicates the nature of the failure.

◆ CdiAdapterStartEndpoint()

CdiReturnStatus CdiAdapterStartEndpoint ( AdapterEndpointHandle handle )

Starts an endpoint for the specified connection.

Parameters

handle The handle of the endpoint to started.

Returns: CdiReturnStatus kCdiStatusOk upon successful open otherwise an indication of the failure.

◆ CdiAdapterStopConnection()

CdiReturnStatus CdiAdapterStopConnection ( AdapterConnectionHandle handle )

Stop a connection, shutting down thread resources.

Parameters

handle The handle of the connection which is to be stopped.

Returns: CdiReturnStatus kCdiStatusOk upon success otherwise an indication of the failure.

◆ CdiAdapterTxPacketComplete()

void CdiAdapterTxPacketComplete	(	AdapterEndpointHandle	handle,
		const Packet *	packet_ptr )

Tx packet has ACKed.

Parameters

handle	The handle of the endpoint that a Tx packet is related to.
packet_ptr	Pointer to packet.

◆ EfaNetworkAdapterInitialize()

CdiReturnStatus EfaNetworkAdapterInitialize	(	CdiAdapterState *	adapter_state_ptr,
		bool	is_socket_based )

Initializes an EFA adapter specified by the values in the provided CdiAdapterState structure.

Parameters

adapter_state_ptr	The address of the generic adapter state preinitialized with the generic values including the CdiAdapterData structure which contains the values provided to the SDK by the user program.
is_socket_based	Specifies whether the adapter is socket-based (true) or EFA-based (false).

Returns: CdiReturnStatus kCdiStausOk if successful, otherwise a value indicating the nature of failure.

◆ SocketNetworkAdapterInitialize()

CdiReturnStatus SocketNetworkAdapterInitialize ( CdiAdapterState * adapter_state_ptr )

Initializes socket based adapter specified by the values in the provided CdiAdapterState structure.

Parameters

adapter_state_ptr The address of the generic adapter state preinitialized with the generic values including the CdiAdapterData structure which contains the values provided to the SDK by the user program.

Returns: CdiReturnStatus kCdiStausOk if successful, otherwise a value indicating the nature of failure.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MessageFromEndpoint

Enumeration Type Documentation

◆ AdapterPacketAckStatus

◆ EndpointDataType

◆ EndpointDirection

◆ EndpointMessageType

◆ EndpointTransmitQueueLevel

◆ PollState

Function Documentation

◆ CdiAdapterCloseEndpoint()

◆ CdiAdapterCreateConnection()

◆ CdiAdapterDestroyConnection()

◆ CdiAdapterEnqueueSendPacket()

◆ CdiAdapterEnqueueSendPackets()

◆ CdiAdapterFreeBuffer()

◆ CdiAdapterGetPort()

◆ CdiAdapterGetTransmitQueueLevel()

◆ CdiAdapterOpenEndpoint()

◆ CdiAdapterPollEndpoint()

◆ CdiAdapterPollThreadFlushResources()

◆ CdiAdapterResetEndpoint()

◆ CdiAdapterShutdown()

◆ CdiAdapterStartEndpoint()

◆ CdiAdapterStopConnection()

◆ CdiAdapterTxPacketComplete()

◆ EfaNetworkAdapterInitialize()

◆ SocketNetworkAdapterInitialize()