adapter.c File Reference

This file contains the definitions of common functions that comprise the CDI adapter API. More...

#include "adapter_api.h"
#include "endpoint_manager.h"
#include "internal.h"
#include "internal_log.h"
#include "internal_tx.h"
#include "internal_rx.h"
#include "internal_utility.h"
#include "list_api.h"

Enumerations
enum	SignalIndex { kSignalIndexConnectionList = 0 , kSignalIndexArray = 1 }
	This enumeration is used in the notification signal array to indicate the index of specific OS signals. More...

Functions
static Packet *	GetNextPacket (AdapterEndpointState *endpoint_ptr, int num_signals, CdiSignalType *notification_signal_array, bool *last_packet_ret_ptr)
static void	UpdateThreadUtilizationStats (CdiAdapterEndpointStats *endpoint_stats_ptr, bool idle, ThreadUtilizationState *utilization_ptr)
static bool	RxPollProcess (AdapterEndpointState *endpoint_state_ptr)
static void	ControlInterfacePoll (AdapterConnectionState *adapter_con_state_ptr, int num_signals, CdiSignalType *notification_signal_array)
static bool	DataPoll (AdapterConnectionState *adapter_con_state_ptr)
static CDI_THREAD	PollThread (void *ptr)
static void	PollThreadConnectionAdd (PollThreadState *poll_thread_state_ptr, AdapterConnectionState *adapter_con_state_ptr)
static void	PollThreadDestroy (PollThreadState *poll_thread_state_ptr, CdiSignalType shutdown_signal)
static void	PollThreadConnectionRemove (AdapterConnectionState *adapter_con_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	CdiAdapterPollEndpoint (AdapterEndpointHandle handle)
CdiReturnStatus	CdiAdapterStartEndpoint (AdapterEndpointHandle handle)
CdiReturnStatus	CdiAdapterResetEndpoint (AdapterEndpointHandle handle)
CdiReturnStatus	CdiAdapterCloseEndpoint (AdapterEndpointHandle handle)
EndpointTransmitQueueLevel	CdiAdapterGetTransmitQueueLevel (AdapterEndpointHandle handle)
CdiReturnStatus	CdiAdapterEnqueueSendPackets (const AdapterEndpointHandle handle, const CdiSinglyLinkedList *packet_list_ptr)
CdiReturnStatus	CdiAdapterEnqueueSendPacket (const AdapterEndpointHandle handle, const struct sockaddr_in *destination_address_ptr, Packet *packet_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

This file contains the definitions of common functions that comprise the CDI adapter API.

Enumeration Type Documentation

SignalIndex

enum SignalIndex

This enumeration is used in the notification signal array to indicate the index of specific OS signals.

Enumerator
kSignalIndexConnectionList	Index of signal used for connection list changes.
kSignalIndexArray	Starting index of array of signals used for other notifications.

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.

ControlInterfacePoll()

static void ControlInterfacePoll ( AdapterConnectionState * adapter_con_state_ptr, int num_signals, CdiSignalType * notification_signal_array )

static

Used directly by PollThread() to process polling for a control interface endpoint. NOTE: This logic may block until a packet is received or a notification signal is set.

Parameters

adapter_con_state_ptr	Pointer to adapter connection state data.
num_signals	Number of signals in notification_signal_array.
notification_signal_array	Array of signals used to cancel waiting.

DataPoll()

static bool DataPoll ( AdapterConnectionState * adapter_con_state_ptr )

static

Used directly by PollThread() to process polling for a data endpoint.

Parameters

adapter_con_state_ptr

Pointer to adapter connection state data.

Returns

true if all endpoints for the specified connection are idle (no work to do).

GetNextPacket()

static Packet * GetNextPacket ( AdapterEndpointState * endpoint_ptr, int num_signals, CdiSignalType * notification_signal_array, bool * last_packet_ret_ptr )

static

Gets the next packet to transmit. Packets arrive as lists from a queue. When a list is removed from the queue, it is stored in the endpoint state and the packets are removed from the list until it's empty. The function will block until a packet is available if notification_signal is not NULL otherwise it will return NULL immediately instead of the address of a packet.

Parameters

endpoint_ptr	Pointer to the endpoint's state.
num_signals	Number of signals in notification_signal_array
notification_signal_array	Array of signals used to cancel waiting to pop a packet list from the incoming queue. Specify NULL if the adapter is a polling type adapter in which case NULL will be returned when no packets are waiting.
last_packet_ret_ptr	Pointer to a bool which is set to true upon last packet currently available. This is only modified in the case where NULL is not returned.

Returns

The address of the Packet structure dequeued or NULL if no packet was waiting.

PollThread()

static CDI_THREAD PollThread ( void * ptr )

static

Thread used to process polling for an endpoint.

Parameters

ptr	Pointer to adapter endpoint state data (AdapterConnectionState).

Returns

The return value is not used.

PollThreadConnectionAdd()

static void PollThreadConnectionAdd ( PollThreadState * poll_thread_state_ptr, AdapterConnectionState * adapter_con_state_ptr )

static

Add an adapter connection to the specified poll thread.

Parameters

poll_thread_state_ptr	Pointer to poll thread state data.
adapter_con_state_ptr	Pointer to adapter connection to add to the poll thread.

PollThreadConnectionRemove()

static void PollThreadConnectionRemove ( AdapterConnectionState * adapter_con_state_ptr )

static

Remove the specified adapter connection from the poll thread.

Parameters

adapter_con_state_ptr

Pointer to adapter connection to remove.

PollThreadDestroy()

static void PollThreadDestroy ( PollThreadState * poll_thread_state_ptr, CdiSignalType shutdown_signal )

static

Destroy poll thread.

Parameters

poll_thread_state_ptr	Pointer to poll thread state data.
shutdown_signal	Shutdown signal.

RxPollProcess()

static bool RxPollProcess ( AdapterEndpointState * endpoint_state_ptr )

static

Perform poll process for Rx endpoint.

Parameters

endpoint_state_ptr

Pointer to adapter endpoint state data.

Returns

true if useful work was done, false if the function did nothing productive.

UpdateThreadUtilizationStats()

static void UpdateThreadUtilizationStats ( CdiAdapterEndpointStats * endpoint_stats_ptr, bool idle, ThreadUtilizationState * utilization_ptr )

static

Update thread utilization statistics.

Parameters

endpoint_stats_ptr	Pointer to adapter endpoint statistics data.
idle	If true thread was idle, otherwise thread was utilized.
utilization_ptr	Pointer to thread utilization data to update.