Transmit

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.

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.

To transmit data using this method push previously filled packet buffers to the handle by using brawcap_tx_buffer_send. After that the buffer will be locked down by the handle and added to it´s transmission queue.

For creating a new packet buffer which can be used for transmission use brawcap_buffer_create.

When a packet buffer transmission has completed the transmit callback will be called for this handle and with the corresponding packet buffer. From within the callback the buffer can be accessed for post processing (it is unlocked before entering the callback). It is also possible to do post processing from a different thread and after the callback.

In general executing to long in the callback can lead to a bottleneck in the transmission. It´s not as critical as it is for receiving but it should be still kept in mind.

Like brawcap_tx_packet does, also each packet in transmitted packet buffers will be updated (e.g. packet status, transmission timestamp). The user application can access those updated information after transmission has completed.

A completed packet buffer transmission will automatically detach the buffer from the handle. It is not needed to detach it explicitly (which would be required for receive buffers).

Note

The buffers are transmitted in the same order they have been added by the user application with brawcap_tx_buffer_send.

Invariant

The user parameter allows access to user defined context. The given pointer is not used and validated by bRAWcap. Therefore the user is responsible for validating the context in the callback before accessing it.

Attention

After starting transmission, brawcap_tx_packet can not be used - on this handle - until tranmission is stopped with brawcap_tx_stop, because parallel transmissions are not allowed

Parameters

[in]	pHandle	bRAWcap handle to transmit on.
[in]	callback	Function pointer to user application transmit callback.
[in]	pUser	Pointer to a user defined context. Can be NULL if no user context is required.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_WARNING_PENDING	Another transmit is pending or transmission is already started.

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.

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.

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.

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.