Rtnl2AcquirePhysicalTxQueue
Rtnl2AcquirePhysicalTxQueue acquires a Physical Transmit Queue object specified by the handle of the owning interface and the index of the Physical Transmit Queue within that interface.
Syntax
RTNL2_HPHYSICAL_TX_QUEUE Rtnl2AcquirePhysicalTxQueue(
[in] RTNL2_HINTERFACE Interface,
[in] ULONG PhysicalTxQueueIndex,
[in] ULONG BufferHeaderStructSize,
[in] Flags,
[out] pReadyEvent
);
Parameters
[in] Interface
A handle to the owning interface obtained from Rtnl2OpenInterface.
[in] PhysicalTxQueueIndex
The index of the Physical Transmit Queue to acquire within that interface.
[in] BufferHeaderStructSize
The Size of the RTNL2_BUFFER_HEADER structure.
[in] Flags
A bitwise OR of this optional flag:
Flag | Meaning |
---|---|
RTNL2_PHYSICAL_TX_QUEUE_FLAG_NO_SERIALIZE |
Don’t serialize hardware accesses to this Physical Transmit Queue. When this flag is set, the Rtnl2SubmitToPhysicalTxQueue, Rtnl2ExtractFromPhysicalTxQueue, and Rtnl2GetPhysicalTxQueueTimestamp functions will fail with RTNL2_ERROR_PHYSICAL_TX_QUEUE_CONCURRENT_ACCESS_NOT_ALLOWED if called from multiple threads at the same time. If the flag is not set, the functions mentioned above will block until the other thread is done. |
[out] pReadyEvent
A handle to the event used to notify the acquiring application when the Physical Transmit Queue is available. This parameter is optional and can be set to NULL by the caller.
Return Value
If the function succeeds, it returns a handle to the acquired Physical Transmit 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 target Physical Transmit Queue is already acquired or is currently used in the shared mode. |
ERROR_INVALID_PARAMETER |
One of these conditions occurred:
|
ERROR_NOT_READY |
The calling process has not called Rtnl2Init. |
ERROR_RESOURCE_NOT_AVAILABLE |
The calling process has already opened too many Physical Transmit Queue handles. |
RTNL2_ERROR_INCOMPATIBLE_REQUEST |
The supplied Flags parameter is not the result of a bitwise OR operation between a set of the supported flags defined above. This may be due to using a new SDK (that defines new flag values) with an old NL2 (that doesn’t know how to interpret those new flags). |
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_CONCURRENT_ACCESS_NOT_ALLOWED |
The supplied BufferHeaderStructSize value is below the minimum required by the NL2. This error can happen only if the caller doesn’t properly set BufferHeaderStructSize to sizeof(RTNL2_BUFFER_HEADER). |
RTNL2_ERROR_SERIALIZED_COMMAND_TIMEOUT |
The NL2 process didn’t reply within an acceptable delay. |
Remarks
Once acquired by a given application process, a Physical Transmit Queue object can't be acquired again, even by the same application process, until it gets released by Rtnl2ReleasePhysicalTxQueue.
The caller MUST set BufferHeaderStructSize to sizeof(RTNL2_BUFFER_HEADER) to ensure backward and forward compatibility. Subsequent to this call, any RTNL2_BUFFER_HEADER structure that the NL2 allocates for the buffers of this Physical Transmit Queue will have this exact size.
The following functions will fail with the error code RTNL2_ERROR_PHYSICAL_TX_QUEUE_NOT_READY if they are called before the Physical Transmit Queue is ready:
- Rtnl2GetPhysicalTxQueueBuffers
- Rtnl2ReturnPhysicalTxQueueBuffers
- Rtnl2EnablePhysicalTxQueueTimestamping
- Rtnl2SubmitToPhysicalTxQueue
- Rtnl2ExtractFromPhysicalTxQueue
- Rtnl2CreatePhysicalTxQueueEvent
- Rtnl2DestroyPhysicalTxQueueEvent
- Rtnl2GetPhysicalTxQueueTimestamp
Characteristics
Real-time | ||
Deterministic |
No |
|
Local memory usage | ||
Process |
External MSpace usage |
Internal MSpace usage |
System |
No | Yes. This function may create kernel objects, depending on the underlying driver. |
NL2 process |
No | No |
Calling process |
Yes. This function may allocate memory for application-specific state structure, depending on the underlying driver. |
Yes. This function may allocate memory for object handles, depending on the underlying driver. |
Contiguous memory usage | ||
Usage |
No |
Requirements
Minimum supported version | Header | Library |
---|---|---|
eRTOS 1.0 SDK |
Rtnl2Api.h |
Rtnl2Api.lib |
See Also:
- RTNL2_BUFFER_HEADER
- RTNL2_HINTERFACE
- RTNL2_HPHYSICAL_TX_QUEUE
- Rtnl2CloseInterface
- Rtnl2OpenInterface
- Rtnl2ReleasePhysicalTxQueue
- Rtnl2GetPhysicalTxQueueBuffers
- Rtnl2ReturnPhysicalTxQueueBuffers
- Rtnl2EnablePhysicalTxQueueTimestamping
- Rtnl2SubmitToPhysicalTxQueue
- Rtnl2ExtractFromPhysicalTxQueue
- Rtnl2CreatePhysicalTxQueueEvent
- Rtnl2DestroyPhysicalTxQueueEvent
- Rtnl2GetPhysicalTxQueueTimestamp