Rtnl2SubmitToPhysicalRxQueue

Rtnl2SubmitToPhysicalRxQueue submits one or more NL2 buffers for reception through a given Physical Receive Queue.

Syntax

Copy

BOOL Rtnl2SubmitToPhysicalRxQueue(
  [in]                RTNL2_HPHYSICAL_RX_QUEUE PhysicalRxQueue, 
  [in]                RTNL2_BUFFER_HEADER *pToBeSubmitted, 
  [out, optional]     ULONG *pNbSubmitted, 
  [out]               RTNL2_BUFFER_HEADER **pNotSubmitted
);

Parameters

[in] PhysicalRxQueue

A handle to the Physical Receive Queue obtained from Rtnl2AcquirePhysicalRxQueue.

[in] pToBeSubmitted

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

[out, optional] pNbSubmitted

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

[out] pNotSubmitted

The address of the buffer header of the first buffer that could not been submitted, or NULL if all supplied buffers were submitted.

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. There are two 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 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.

Note: The function cannot return TRUE when pNotSubmitted is not populated with NULL because all NL2 Receive Buffers are statically allocated to fit into the Rx DMA Ring. It’s not possible for the application to request more buffers to be submitted than there is space for in the Receive DMA ring. This differs from Physical Transmit Queues, where the application can allocate more NL2 Transmit Buffers than the Transmit DMA Ring space allows.

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

Error code	Meaning
ERROR_NOT_READY	The calling process has not called Rtnl2Init.
ERROR_INVALID_PARAMETER	One of the following conditions occurred: The supplied Physical Receive Queue handle is invalid. pNotSubmitted is NULL.
RTNL2_ERROR_PHYSICAL_RX_QUEUE_IS_RELEASING	Another thread of the calling process is executing Rtnl2ReleasePhysicalRxQueue at the same time.
RTNL2_ERROR_PHYSICAL_RX_QUEUE_BUFFER_NOT_OWNED	One or more of the supplied NL2 Buffers is already owned by the NL2.
RTNL2_ERROR_PHYSICAL_RX_QUEUE_CONCURRENT_ACCESS_NOT_ALLOWED	The Physical Receive Queue has been acquired with the RTNL2_PHYSICAL_RX_QUEUE_FLAG_NO_SERIALIZE flag and another thread of the calling process is executing Rtnl2ExtractFromPhysicalRxQueue at the same time.
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.

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 Receive Queue was acquired with the RTNL2_PHYSICAL_RX_QUEUE_FLAG_NO_SERIALIZE flag and the underlying driver supports deterministic receive operation, No otherwise. Please refer to your driver’s documentation to determine whether it supports deterministic receive operation.
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