Rtnl2SubmitToPhysicalTxQueue

Rtnl2SubmitToPhysicalTxQueue submits one or more NL2 buffers for transmission through a given physical transmit queue.

Syntax

Copy

BOOL Rtnl2SubmitToPhysicalTxQueue(
  [in]                RTNL2_HPHYSICAL_TX_QUEUE PhysicalTxQueue, 
  [in]                RTNL2_BUFFER_HEADER *pToBeSubmitted, 
  [out, optional]     ULONG *NbSubmitted, 
  [out]               RTNL2_BUFFER_HEADER **pNotSubmitted
);

Parameters

[in] PhysicalTxQueue

A handle to the physical transmit queue obtained from Rtnl2AcquirePhysicalTxQueue.

[in] pToBeSubmitted

The address of the first buffer header to submit for transmission.

[out, optional] NbSubmitted

The number of buffers added to the FIFO of submitted buffers.

[out] pNotSubmitted

The address of the first buffer header that could not be submitted due to a lack of space in the hardware DMA ring. If all supplied buffers have been submitted, it returns NULL.

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. There are three common return scenarios:

Returned values	Meaning
The function returns TRUE and pNotSubmitted is populated with NULL.	All buffers could be submitted without error.
The function returns TRUE and pNotSubmitted is not populated with NULL.	No error occurred but not all buffers could be submitted due to lack of space in the hardware DMA ring.
The function returns FALSE and pNotSubmitted is not populated with NULL.	An error occurred. Consequently, not all buffers could be submitted. See the list of possible errors below.

Call GetLastError to obtain an error code. Possible error codes:

Error code	Meaning
ERROR_DEVICE_FEATURE_NOT_SUPPORTED	Timestamping was requested for one or more of the supplied NL2 buffers, but the NIC doesn’t support hardware timestamping.
ERROR_INVALID_PARAMETER	One of the following conditions occurred: The supplied Physical Transmit Queue handle is invalid. pNotSubmitted is NULL.
ERROR_NOT_READY	The calling process has not called Rtnl2Init.
RTNL2_ERROR_NO_MORE_COMMUNICATION	Unable to communicate with the NL2 process. This might be because the NL2 process is not running anymore, or because an application process thread was terminated during a previous call to an NL2 API function.
RTNL2_ERROR_PHYSICAL_TX_QUEUE_BUFFER_NOT_OWNED	One or more of the supplied NL2 buffers is already owned by the NL2.
RTNL2_ERROR_PHYSICAL_TX_QUEUE_CONCURRENT_ACCESS_NOT_ALLOWED	The Physical Transmit Queue has been acquired with the RTNL2_PHYSICAL_TX_QUEUE_FLAG_NO_SERIALIZE flag and another thread of the calling process is executing Rtnl2ExtractFromPhysicalTxQueue or Rtnl2GetPhysicalTxQueueTimestamp at the same time.
RTNL2_ERROR_PHYSICAL_TX_QUEUE_IS_RELEASING	Another thread of the calling process is executing Rtnl2ReleasePhysicalTxQueue at the same time.
RTNL2_ERROR_PHYSICAL_TX_QUEUE_NOT_READY	The Physical Transmit Queue is not ready.
RTNL2_ERROR_OVERSIZED_FRAME	At least one of the supplied NL2 buffers has a frame length higher than what the hardware can transmit. See Rtnl2GetInterfaceFeatures and RTNL2_INTERFACE_FEATURES for the maximum frame length.
RTNL2_ERROR_PHYSICAL_TX_QUEUE_TIMESTAMPING_NOT_ENABLED	Timestamping has been requested for one or more of the supplied NL2 buffers, but Rtnl2EnablePhysicalTxQueueTimestamping was not called successfully for this Physical Transmit Queue.

Remarks

An application can request to submit multiple buffers by linking all the buffer headers together and giving the address of the first buffer header to this function.

If parameter pNbSubmitted is set to NULL, the function ignores it and doesn’t return the corresponding value.

No matter whether the function returns TRUE or FALSE, it always populates pNotSubmitted and pNbSubmitted with valid values (unless the passed address is NULL).

Characteristics

Real-time
Deterministic	Yes if the Physical Transmit Queue was acquired with the RTNL2_PHYSICAL_TX_QUEUE_FLAG_NO_SERIALIZE flag and the underlying driver supports deterministic transmit operation. No otherwise. Please refer to your driver’s documentation to determine whether it supports deterministic transmit operations.
Local memory usage
Process	External MSpace usage	Internal MSpace usage
System	No	No
NL2 process	No	No
Calling process	No	No
Contiguous memory usage
Usage	No

Requirements

Minimum supported version	Header	Library
eRTOS 1.0 SDK	Rtnl2Api.h	Rtnl2Api.lib