Edit

MINIPORT_PROCESS_SG_LIST callback function (ndis.h)

  • Article

A bus-master miniport driver provides a MiniportProcessSGList function to process scatter/gather lists for network data.

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

Syntax

MINIPORT_PROCESS_SG_LIST MiniportProcessSgList;

void MiniportProcessSgList(
  [in] PDEVICE_OBJECT pDO,
  [in] PVOID Reserved,
  [in] PSCATTER_GATHER_LIST pSGL,
  [in] PVOID Context
)
{...}

Parameters

[in] pDO

Miniport drivers should ignore this parameter.

[in] Reserved

Miniport drivers should ignore this parameter.

[in] pSGL

A pointer to a scatter/gather list buffer. This is not necessarily the same buffer as the one the driver specified in the call to the NdisMAllocateNetBufferSGList function

[in] Context

A pointer to a context area that the miniport driver created prior to calling NdisMAllocateNetBufferSGList.

Return value

None

Remarks

Miniport drivers call the NdisMRegisterScatterGatherDma function to register a MiniportProcessSGList function. When a miniport driver calls NdisMAllocateNetBufferSGList to create a scatter/gather list, NDIS calls HAL to create the list.

NDIS calls the miniport driver's MiniportProcessSGList function if NdisMAllocateNetBufferSGList is successful. However, a success return from that function does not guarantee the callback was already invoked; it can be invoked asynchronously.

When NDIS calls MiniportProcessSGList, the driver can send the NET_BUFFER structure to the hardware. MiniportProcessSGList submits the physical addresses of the scatter/gather list to the NIC's DMA and issues a send command to the NIC.

HAL can call MiniportProcessSGList before or after NDIS returns from NdisMAllocateNetBufferSGList. Therefore, driver writers should not assume that the call is made within the context of NdisMAllocateNetBufferSGList.

NDIS calls MiniportProcessSGList at IRQL = DISPATCH_LEVEL.

Examples

To define a MiniportProcessSGList 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 MiniportProcessSGList function that is named "MyProcessSGList", use the MINIPORT_PROCESS_SG_LIST type as shown in this code example:

MINIPORT_PROCESS_SG_LIST MyProcessSGList;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyProcessSGList(
    PDEVICE_OBJECT  pDO,
    PVOID  Reserved,
    PSCATTER_GATHER_LIST  pSGL,
    PVOID  Context
    )
  {...}

The MINIPORT_PROCESS_SG_LIST function type is defined in the Ndis.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_PROCESS_SG_LIST 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 Supported in NDIS 6.0 and later.
Target Platform Windows
Header ndis.h (include Ndis.h)
IRQL DISPATCH_LEVEL

See also

NdisMAllocateNetBufferSGList

NdisMRegisterScatterGatherDma