MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE callback function (ndis.h)

Article
10/21/2021

NDIS calls a miniport driver's MiniportSharedMemoryAllocateComplete function to complete a shared memory allocation request that the miniport driver started by calling the NdisMAllocateSharedMemoryAsyncEx function.

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

Syntax

MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE MiniportAllocateSharedMemComplete;

void MiniportAllocateSharedMemComplete(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PVOID VirtualAddress,
  [in] PNDIS_PHYSICAL_ADDRESS PhysicalAddress,
  [in] ULONG Length,
  [in] PVOID Context
)
{...}

Parameters

[in] MiniportAdapterContext

The handle to a context area allocated by the miniport driver in which the driver maintains state information for a NIC. The driver allocates this context area in the MiniportInitializeEx function.

[in] VirtualAddress

The base virtual address of the shared memory that the miniport driver allocated by calling NdisMAllocateSharedMemoryAsyncEx. VirtualAddress is NULL if the allocation attempt failed.

[in] PhysicalAddress

The base physical address for the NIC to use that is mapped to the address that the VirtualAddress parameter specifies.

[in] Length

The number of bytes that NdisMAllocateSharedMemoryAsyncEx allocated.

[in] Context

A pointer to a context area that the miniport driver specified in the preceding call to NdisMAllocateSharedMemoryAsyncEx.

Return value

None

Remarks

MiniportAllocateSharedMemoryComplete is an optional function for miniport drivers. A miniport driver registers a MiniportAllocateSharedMemoryComplete function in the NDIS_SG_DMA_DESCRIPTION structure that the driver passed to the NdisMRegisterScatterGatherDma function.

Miniport drivers call NdisMAllocateSharedMemoryAsyncEx to allocate shared memory. If NdisMAllocateSharedMemoryAsyncEx returns NDIS_STATUS_PENDING, NDIS calls MiniportAllocateSharedMemoryComplete to pass the memory to the miniport driver.

NDIS calls MiniportSharedMemoryAllocateComplete at IRQL PASSIVE_LEVEL.

Examples

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

MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE MySharedMemoryAllocateComplete;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MySharedMemoryAllocateComplete(
    NDIS_HANDLE  MiniportAdapterContext,
    PVOID  VirtualAddress,
    PNDIS_PHYSICAL_ADDRESS  PhysicalAddress,
    ULONG  Length,
    PVOID  Context
    )
  {...}

The MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE 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_ALLOCATE_SHARED_MEM_COMPLETE 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	PASSIVE_LEVEL