Rtnl2CreateLogicalRxQueue creates a Logical Receive Queue object on top of a Physical Receive Queue specified by the handle of the owning interface and the index of the Physical Receive Queue within that interface.
Syntax
RTNL2_HLOGICAL_RX_QUEUE Rtnl2CreateLogicalRxQueue(
[in] RTNL2_HINTERFACE Interface,
[in] ULONG PhysicalRxQueueIndex,
[in] ULONG BufferCount,
[out] HANDLE *pRxEvent
);Parameters
[in] Interface
A handle to the owning interface.
[in] PhysicalRxQueueIndex
The index of the Physical Receive Queue on which the Logical Receive Queue is created.
[in] BufferCount
The number of local Buffers that will compose the Logical Receive Queue.
[out] pRxEvent
A pointer to a handle of the associated Receive event.
Return Value
If the function succeeds, it returns a handle to the created Logical Receive Queue object. If the function fails, it returns NULL. Call GetLastError to obtain an error code if the function fails.
Possible error codes:
| Error code | Meaning |
|---|---|
|
ERROR_ACCESS_DENIED |
The Physical Receive Queue is currently acquired by another application that is directly using the Physical Queue. |
|
ERROR_NOT_READY |
The calling process has not called Rtnl2Init. |
|
ERROR_INVALID_PARAMETER |
One of the following conditions occurred:
|
|
ERROR_OUTOFMEMORY |
Unable to allocate memory. |
|
ERROR_RESOURCE_NOT_AVAILABLE |
The calling process has already opened more Logical Receive Queue handles than the maximum number (500) a given application process can have open at one 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. |
|
RTNL2_ERROR_SERIALIZED_COMMAND_TIMEOUT |
The NL2 process didn’t reply within an acceptable amount of time. |
Remarks
This function allocates BufferCount NL2 Buffers and arranges them in a Logical Receive Queue structure. The size of each buffer is equal to RTNL2_INTERFACE_FEATURES.RxBufferLength.
This function also creates a Receive event and returns a pointer to the event handle in parameter pRxEvent, which will be signaled by the NL2 every time new frames are available for that Logical Receive Queue. The Receive event is an auto-reset event.
Note: At creation time, the Logical Receive Queue is stopped. Please use function Rtnl2StartLogicalRxQueue to start it.
There is no limit to the number of Logical Receive Queues that can be created on the same Physical Receive Queue, either by the same application process or by several different processes.
When no longer needed, a Logical Receive Queue must be destroyed by calling Rtnl2DestroyLogicalRxQueue.
Characteristics
| Real-time | ||
|
Deterministic |
No |
|
| Local memory usage | ||
|
Process |
External MSpace usage |
Internal MSpace usage |
|
System |
No |
Yes. This function will allocate memory for the Receive Event kernel object and other kernel objects needed to synchronize the access to the Physical Receive Queue. |
|
NL2 process |
Yes. This function will allocate memory for the Logical Receive Queue structure and the local buffers. Also, this function may allocate memory for the driver state structure, depending on the underlying driver. |
Yes. This function will allocate memory for the handle to the Receive Event kernel object and the other kernel objects created to synchronize the access to the Physical Receive Queue. |
|
Calling process |
No |
Yes. This function will allocate memory for the handles to the Receive Event kernel object and the other kernel objects created by the NL2 process to synchronize the access to the Physical Receive Queue. |
| Contiguous memory usage | ||
|
Usage |
No |
|
Requirements
| Minimum supported version | Header | Library |
|---|---|---|
|
eRTOS 1.0 SDK |
Rtnl2Api.h |
Rtnl2Api.lib |
See Also:
