Rtnl2CreateLogicalTxQueue

Rtnl2CreateLogicalTxQueue creates a Logical Transmit Queue object above the Physical Transmit Queue specified by the handle of the owning interface and the index of the Physical Transmit Queue within that interface.

Syntax

Copy 
RTNL2_HLOGICAL_TX_QUEUE Rtnl2CreateLogicalTxQueue(
  [in]    RTNL2_HINTERFACE Interface,
  [in]    ULONG PhysicalTxQueueIndex,
  [in]    ULONG BufferCount
);

Parameters

[in] hInterface

A handle to the interface.

[in] PhysicalTxQueueIndex

The index of the Physical Transmit Queue that will be shared by the created Logical Transmit Queue.

[in] BufferCount

The number of NL2 Buffers that will compose the Logical Transmit Queue.

Return Value

If the function succeeds, it returns a handle to the created Logical 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 Physical Transmit Queue is currently acquired.

ERROR_NOT_READY

The calling process has not called Rtnl2Init.

ERROR_INVALID_PARAMETER

One of the following conditions occurred:

  • The supplied interface handle is invalid.
  • Parameter PhysicalTxQueueIndex doesn’t correspond to an enabled queue.
  • Parameter BufferCount is NULL.

ERROR_OUTOFMEMORY

Unable to allocate memory.

ERROR_RESOURCE_NOT_AVAILABLE

The calling process has already opened more Logical Transmit 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 local Buffers and arranges them in a Logical Transmit Queue structure. The size of each buffer is equal to the maximum length of the frames that this interface can transmit (see RTNL2_INTERFACE_FEATURES.TxBufferLength).

There is no limit to the number of Logical Transmit Queues that can be created on the same Physical Transmit Queue, either by the same application process or several different processes.

When no longer needed, a Logical Transmit Queue must be destroyed by calling Rtnl2DestroyLogicalTxQueue.

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 kernel objects needed to synchronize the access to the Physical Transmit Queue.

NL2 process

Yes. This function will allocate memory for the Logical Transmit Queue structure and for 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 handles to the kernel objects created to synchronize the access to the Physical Transmit Queue.

Calling process

Yes. This function may allocate memory for application-specific state structure, depending on the underlying driver.

Yes. This function will allocate memory for the handles to the kernel objects created by the NL2 process to synchronize the access to the Physical Transmit Queue.
Contiguous memory usage

Usage

No

Requirements

Minimum supported version Header Library

eRTOS 1.0 SDK

Rtnl2Api.h

Rtnl2Api.lib

See Also: