NdisMInitializeScatterGatherDma

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.

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

Parameters

MiniportAdapterHandle

Specifies the handle input to MiniportInitialize.

Dma64BitAddresses

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

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:

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.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

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 Miniport(Co)SendPackets 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.

Callers of NdisMInitializeScatterGatherDma run at IRQL = PASSIVE_LEVEL.

See Also

MiniportInitialize, NdisMAllocateSharedMemory, NdisMRegisterMiniport, NdisMSetAttributes, NdisMSetAttributesEx, NdisMStartBufferPhysicalMapping, NDIS_PER_PACKET_INFO_FROM_PACKET, NdisQueryPacket, SCATTER_GATHER_LIST