Types and functions for bRAWcap transmitting. More...

Macros
#define	BRAWCAP_TX_DRIVER_QUEUE_SIZE_DEFAULT 512
	Default size in number of packets for driver transmit queues.

#define	BRAWCAP_TX_DRIVER_QUEUE_SIZE_MIN 256
	Minimum size in number of packets supported for driver transmit queues.

#define	BRAWCAP_TX_DRIVER_QUEUE_SIZE_MAX 4096
	Maximum size in number of packets supported for driver transmit queues.

#define	BRAWCAP_TX_TIMESTAMP_MODE_DEFAULT BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP
	Default timestamp mode for transmitted packets.

Typedefs
typedef void(*	brawcap_tx_callback_t) (brawcap_handle_t const pHandle, const brawcap_status_t status, brawcap_buffer_t const pBuffer, void *pUser)
	Transmit callback which is called each time a transmission initiated with brawcap_tx_buffer_send has finished.

Functions
brawcap_status_t	brawcap_tx_packet (brawcap_handle_t const pHandle, brawcap_packet_t const pPacket)
	Transmits a single packet on the specified handle.

brawcap_status_t	brawcap_tx_start (brawcap_handle_t const pHandle, brawcap_tx_callback_t const callback, void pUser)
	Starts the internal transmit loop.

brawcap_status_t	brawcap_tx_stop (brawcap_handle_t *const pHandle)
	Stops the internal transmit loop.

brawcap_status_t	brawcap_tx_buffer_send (brawcap_handle_t const pHandle, brawcap_buffer_t const pBuffer, const BOOLEAN synchronized)
	Pushes the specified buffer to the specified handle transmit queue.

brawcap_status_t	brawcap_tx_driver_queue_size_set (brawcap_handle_t *const pHandle, const brawcap_queue_size_t size)
	Sets the driver queue size (in number of packets) for the specified handle.

brawcap_status_t	brawcap_tx_driver_queue_size_get (brawcap_handle_t const pHandle, brawcap_queue_size_t const pSize)
	Reads out the currently configured driver transmit queue size for the specified handle.

brawcap_status_t	brawcap_tx_timestamp_capabilities (brawcap_handle_t const pHandle, brawcap_timestamp_capabilities_t const pCapabilities)
	Reads out the available transmit timestamp modes for the specified handle.

brawcap_status_t	brawcap_tx_timestamp_mode_set (brawcap_handle_t *const pHandle, const brawcap_timestamp_mode_t mode)
	Configures the used transmit time stamping mode for the specified handle.

brawcap_status_t	brawcap_tx_timestamp_mode_get (brawcap_handle_t const pHandle, brawcap_timestamp_mode_t const pMode)
	Reads out the currently configured transmit time stamping mode for the specified handle.

Detailed Description

Types and functions for bRAWcap transmitting.

List of examples:

Buffered Packet Transmitter

Typedef Documentation

◆ brawcap_tx_callback_t

typedef void(* brawcap_tx_callback_t) (brawcap_handle_t *const pHandle, const brawcap_status_t status, brawcap_buffer_t *const pBuffer, void *pUser)

#include <brawcap_types_um.h>

Transmit callback which is called each time a transmission initiated with brawcap_tx_buffer_send has finished.

Note: Before any buffer can be transmitted the tranmission has to be started with brawcap_tx_start and stopped with brawcap_tx_stop.

Parameters

[in]	pHandle	Handle on which the transmission has finished.
[in]	status	The overall transmission status see brawcap_status_t for possible return values.
[in]	pBuffer	Pointer to the buffer which has finished transmission (initiated with brawcap_tx_buffer_send). It can be used to access all packets in the buffer - after transmission - and allows to retrieve information about each packet (e.g. (transmission) status, timestamp, ...).
[in]	pUser	Pointer to a user defined context (allows access to user specific data within the callback).

Function Documentation

◆ brawcap_tx_packet()

brawcap_status_t brawcap_tx_packet	(	brawcap_handle_t *const	pHandle,
		brawcap_packet_t *const	pPacket
	)

#include <brawcap.h>

Transmits a single packet on the specified handle.

The caller must provide a valid packet filled up with the payload to transmit.

For creating a packet use brawcap_packet_create. After creating the packet set all the required packet fields and than call this function to initiate a transmission.

When transmission has finished (the function returns) the packet fields are updated.

To check if the transmission was successful check for the function return status or the packet status itself with brawcap_packet_status_get. If the packet was transmitted and transmit time stamping was enabled the packet timestamp will contain the transmission time, which be accessed with brawcap_packet_timestamp_get.

Parameters

[in]	pHandle	bRAWcap handle to transmit on.
[in,out]	pPacket	Packet to be transmitted.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE	bRAWcap driver is not active (anymore) on the adapter.
BRAWCAP_STATUS_WARNING_DEMO_MODE	Running in demo mode (no license).
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.
BRAWCAP_STATUS_WARNING_NOT_ALL_PROCESSED	The transmission failed (or payload was not fully transmitted).

◆ brawcap_tx_start()

brawcap_status_t brawcap_tx_start	(	brawcap_handle_t *const	pHandle,
		brawcap_tx_callback_t const	callback,
		void *	pUser
	)

#include <brawcap.h>

Starts the internal transmit loop.

Enables asynchronous / buffered transmission mode on a handle. After the loop is started the application queues packet buffers with brawcap_tx_buffer_send. Each queued buffer is locked until it has been fully processed and the transmit callback returns.

Usage pattern:

Prepare one or more packet buffers (filled packets, optional timestamps if synchronized sending desired).
Call brawcap_tx_start(handle, callback, userCtx).
Push buffers via brawcap_tx_buffer_send (optionally specifying synchronized transmission).
In the callback, reclaim / reuse / free completed buffers.
Stop transmission with brawcap_tx_stop when finished.

Constraints:

Only one active transmit loop per handle (returns WARNING_PENDING if already running).
While the loop is running single packet API brawcap_tx_packet MUST NOT be used on the same handle.
Callback executions are serialized per handle (never concurrent on same handle).
The callback MUST return promptly; long blocking degrades throughput.

Callback contract:

Signature: brawcap_tx_callback_t(brawcap_handle_t* handle, brawcap_buffer_t* buffer, void* userCtx, brawcap_status_t status)
status reflects completion status for the processed buffer.
buffer is unlocked while inside the callback allowing immediate inspection / reuse.
userCtx is the same pointer provided in pUser (not validated by bRAWcap).

Thread safety: Starting/stopping is not thread-safe with itself; synchronize if multiple threads may initiate.

Parameters

[in]	pHandle	bRAWcap handle to start transmission on.
[in]	callback	User transmit completion callback (required, must not be NULL).
[in]	pUser	Opaque user context pointer passed to each callback invocation (may be NULL).

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Transmit loop started.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	pHandle or callback invalid.
BRAWCAP_STATUS_WARNING_PENDING	A transmit loop is already running.
BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE	Driver not active on adapter.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Driver communication failed.

Examples: 10_transmit_buffered_transmitter_f.c.

◆ brawcap_tx_stop()

brawcap_status_t brawcap_tx_stop ( brawcap_handle_t *const pHandle )

#include <brawcap.h>

Stops the internal transmit loop.

Parameters

[in] pHandle bRAWcap handle to stop transmission on.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_INFO_NOT_RUNNING	There was no transmission running.

Examples: 10_transmit_buffered_transmitter_f.c.

◆ brawcap_tx_buffer_send()

brawcap_status_t brawcap_tx_buffer_send	(	brawcap_handle_t *const	pHandle,
		brawcap_buffer_t *const	pBuffer,
		const BOOLEAN	synchronized
	)

#include <brawcap.h>

Pushes the specified buffer to the specified handle transmit queue.

After pushing a packet buffer to the handle for transmission it is locked down by the handle until transmission has completed (and the transmit callback is called).

With the synchronized flag it is possible to activate a synchronized transmission of the specified packet buffer. This means that the driver reads the time gap between each packet in the packet buffer and waits until it has been elapsed before initiating transmission. Test

Attention: For synchronized transmission it is necessary to sort the packets in the buffer by rising timestamp. Furthermore, it is currently not supported to specify a "start time" when the first packet should be transmitted. Therefore if you want to start transmission depending on the first packet timestamp you should wait until the time is reached and after this initiate the transmission by calling this function. The driver itself only evaluates the time gaps between each packet in the buffer.

Note: Packet buffers are transmitted in the same order they was pushed to the handle.

Invariant: Keep in mind that the packet timestamp is updated after transmission has been completed by the transmission timestamp (depending on the configured timestamp mode). Therefore if there was a packet timestamp set for example to send synchronized, this timestamp will be overwritten.

Parameters

[in]	pHandle	bRAWcap handle for sending the buffer.
[in]	pBuffer	Packet buffer to be sent.
[in]	synchronized	Flag indicating if the packets in the packet buffer should be sent synchronized.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	The buffer is already in use / locked down by another operation.

Examples: 10_transmit_buffered_transmitter_f.c.

◆ brawcap_tx_driver_queue_size_set()

brawcap_status_t brawcap_tx_driver_queue_size_set	(	brawcap_handle_t *const	pHandle,
		const brawcap_queue_size_t	size
	)

#include <brawcap.h>

Sets the driver queue size (in number of packets) for the specified handle.

For transmission the driver queue size may be increased if high data rates should be reached (for example 10GBit/s). With a larger transmission queue the driver can forward more packets to the network adapter at the same time. Therefore if the transmission rate is below the expected value it may be solved by a larger driver queue size.

The driver queue size can be adjusted at any time.

Note: The default queue size is

See also: BRAWCAP_TX_DRIVER_QUEUE_SIZE_DEFAULT (in number of packets). And its max limitation is; BRAWCAP_TX_DRIVER_QUEUE_SIZE_MAX (in number of packets).

Attention: Reducing the queue size during runtime may result in packet transmission cancellation. This may be the case if there are more packets pending for transmission than the new size can accommodate.

Parameters

[in]	pHandle	bRAWcap handle to be configured.
[in]	size	Driver transmit queue size to be set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Specified queue size is out of range/invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

◆ brawcap_tx_driver_queue_size_get()

brawcap_status_t brawcap_tx_driver_queue_size_get	(	brawcap_handle_t *const	pHandle,
		brawcap_queue_size_t *const	pSize
	)

#include <brawcap.h>

Reads out the currently configured driver transmit queue size for the specified handle.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pSize	Will contain the currently configured driver transmit queue size, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.

◆ brawcap_tx_timestamp_capabilities()

brawcap_status_t brawcap_tx_timestamp_capabilities	(	brawcap_handle_t *const	pHandle,
		brawcap_timestamp_capabilities_t *const	pCapabilities
	)

#include <brawcap.h>

Reads out the available transmit timestamp modes for the specified handle.

Some of the timestamp capabilities depend on the features provided by the underlying adapter. Those modes are named with "adapter".

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pCapabilities	Will contain the available transmit timestamp modes, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

◆ brawcap_tx_timestamp_mode_set()

brawcap_status_t brawcap_tx_timestamp_mode_set	(	brawcap_handle_t *const	pHandle,
		const brawcap_timestamp_mode_t	mode
	)

#include <brawcap.h>

Configures the used transmit time stamping mode for the specified handle.

Note: Only available timestamp modes are accepted. It is recommended to check if a timestamp mode is supported before setting it. To check if a timestamp mode is available use brawcap_tx_timestamp_capabilities.

Parameters

[in]	pHandle	bRAWcap handle to be configured.
[in]	mode	The transmit timestamp mode to be configured.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE	Specified timestamp mode not available.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

◆ brawcap_tx_timestamp_mode_get()

brawcap_status_t brawcap_tx_timestamp_mode_get	(	brawcap_handle_t *const	pHandle,
		brawcap_timestamp_mode_t *const	pMode
	)

#include <brawcap.h>

Reads out the currently configured transmit time stamping mode for the specified handle.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pMode	Will contain the currently used transmit time stamping mode, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ brawcap_tx_callback_t

Function Documentation

◆ brawcap_tx_packet()

◆ brawcap_tx_start()

◆ brawcap_tx_stop()

◆ brawcap_tx_buffer_send()

◆ brawcap_tx_driver_queue_size_set()

◆ brawcap_tx_driver_queue_size_get()

◆ brawcap_tx_timestamp_capabilities()

◆ brawcap_tx_timestamp_mode_set()

◆ brawcap_tx_timestamp_mode_get()