NdisMInitializeScatterGatherDma function

Article
06/19/2017

Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisMInitializeScatterGatherDma, which is called by miniport drivers that manage bus-master DMA NICs, initializes system resources during miniport driver initialization for use in subsequent DMA operations.

Syntax

NDIS_STATUS NdisMInitializeScatterGatherDma(
  _In_ NDIS_HANDLE MiniportAdapterHandle,
  _In_ BOOLEAN     Dma64BitAddresses,
  _In_ ULONG       MaximumPhysicalMapping
);

Parameters

MiniportAdapterHandle [in]
Specifies the handle input to MiniportInitialize.
Dma64BitAddresses [in]
Specifies TRUE if the NIC can use 64-bit addressing for DMA operations. Specifies FALSE if the NIC can use only 32-bit addressing for DMA operations.
MaximumPhysicalMapping [in]
Specifies the maximum number of bytes that the NIC can transfer as a single DMA operation. If the miniport driver supports Large Send Offload (LSO), it should not pass the Ethernet frame size. Instead, it should pass the maximum packet size (for example, 32 or 64 Kbytes) that it supports in its LSO code.

Return value

NdisMInitializeScatterGatherDma can return one of the following:

Return code	Description
NDIS_STATUS_SUCCESS	System resources were successfully allocated for bus-master DMA operations.
NDIS_STATUS_RESOURCES	System resources could not be allocated due to system resource constraints.
NDIS_STATUS_NOT_SUPPORTED	The caller did not register as an NDIS 5.0 or NDIS 5.1 miniport driver when it called NdisMRegisterMiniport or the caller did not specify that its NIC is a bus-master DMA device when it called NdisMSetAttributes or NdisMSetAttributesEx.

Remarks

A miniport driver that manages a bus-master DMA NIC calls NdisMInitializeScatterGatherDma from its MiniportInitialize function. The miniport driver must call NdisMInitializeScatterGatherDma after calling NdisMSetAttributes or NdisMSetAttributesEx and before calling NdisMAllocateSharedMemory.

NdisMInitializeScatterGatherDma reserves system resources for DMA operations performed by the miniport driver. A miniport driver that calls NdisMInitializeScatterGatherDma does not have to allocate map registers for DMA operations or release such registers on the completion of DMA operations.

If MiniportInitialize did not specify that the NIC is a bus master when it called NdisMSetAttributes or NdisMSetAttributesEx, NdisMInitializeScatterGatherDma simply returns control without attempting to reserve system resources.

NdisMInitializeScatterGatherDma supports only 32-bit and 64-bit DMA addresses. It does not support 24-bit DMA addresses.

A miniport driver that calls NdisMInitializeScatterGatherDma during DMA initialization does the following to obtain the mapped logical address ranges of buffers containing DMA data: for each packet descriptor passed to its MiniportSend or MiniportCoSendPackets function, the miniport driver calls NDIS_PER_PACKET_INFO_FROM_PACKET with an InfoType of ScatterGatherListPacketInfo. The miniport driver supplies the obtained logical address ranges to its NIC so that the NIC can perform the DMA transfer.

Requirements

Target platform	Universal
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisMRegisterScatterGatherDmainstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL