MINIPORT_WDI_TX_TARGET_DESC_INIT callback function (dot11wdi.h)

Article
10/22/2021

Important

This topic is part of the WDI driver model released in Windows 10. The WDI driver model is in maintenance mode and will only receive high priority fixes. WiFiCx is the Wi-Fi driver model released in Windows 11. We recommend that you use WiFiCx to take advantage of the latest features.

The MINIPORT_WDI_TX_TARGET_DESC_INIT callback function associates an opaque target TX descriptor with the NET_BUFFER_LIST (MiniportReserved[1] field) and (if applicable) populates the TX cost field (in credit units) in the WDI_FRAME_METADATA buffer of the NET_BUFFER_LIST (MiniportReserved[0]).

This is a WDI miniport handler inside NDIS_MINIPORT_WDI_DATA_HANDLERS.

Note You must declare the function by using the MINIPORT_WDI_TX_TARGET_DESC_INIT type. For more information, see the following Examples section.

Syntax

MINIPORT_WDI_TX_TARGET_DESC_INIT MiniportWdiTxTargetDescInit;

void MiniportWdiTxTargetDescInit(
  [in]  TAL_TXRX_HANDLE MiniportTalTxRxContext,
  [in]  PNET_BUFFER_LIST pNBL,
  [out] NDIS_STATUS *pWifiStatus
)
{...}

Parameters

[in] MiniportTalTxRxContext

TAL device handle returned by the IHV miniport in the MINIPORT_WDI_TAL_TXRX_INITIALIZE callback function.

[in] pNBL

Pointer to a single NET_BUFFER_LIST.

[out] pWifiStatus

Pointer to the status set by the IHV to indicate the result of the MINIPORT_WDI_TX_TARGET_DESC_INIT callback function.

Return value

None

Remarks

A status of NDIS_STATUS_RESOURCES must only be used when Tx descriptors are exhausted. The best behavior occurs if the IHV miniport does not use NDIS_STATUS_RESOURCES. Any status other than NDIS_STATUS_SUCCESS and NDIS_STATUS_RESOURCES must be used for any other error that indicates the IHV miniport or firmware is unable to process the NET_BUFFER_LIST.

The IHV miniport may utilize the backfill in the NET_BUFFER by using the appropriate NDIS retreat and advance functions. The start of the packet offset must be restored before or in the MINIPORT_WDI_TX_TARGET_DESC_DEINIT callback function. The TxMgr determines the frame length during dequeue time so any change to the frame length in the MINIPORT_WDI_TX_TARGET_DESC_INIT callback function is included in limiting the dequeue size to the quantum. In this case, the IHV miniport should appropriately adjust the quantum to account for the delta.

Important The IHV miniport is not permitted to make any indication in the context of this call. The TxMgr serializes calls to TxTargetDescInitHandler.

Examples

To define a MINIPORT_WDI_TX_TARGET_DESC_INIT callback function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a MINIPORT_WDI_TX_TARGET_DESC_INIT callback function that is named "MyTxTargetDescInit", use the MINIPORT_WDI_TX_TARGET_DESC_INIT type as shown in this code example:

MINIPORT_WDI_TX_TARGET_DESC_INIT MyTxTargetDescInit;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyTxTargetDescInit(
    TAL_TXRX_HANDLE MiniportTalTxRxContext,
    PNET_BUFFER_LIST pNBL,
    NDIS_STATUS *pWifiStatus
    )
  {...}

The MINIPORT_WDI_TX_TARGET_DESC_INIT function type is defined in the dot11wdi.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the MINIPORT_WDI_TX_TARGET_DESC_INIT function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Windows 10
Minimum supported server	Windows Server 2016
Target Platform	Windows
Header	dot11wdi.h