NdisMRegisterScatterGatherDma function (ndis.h)

Bus master miniport drivers call the NdisMRegisterScatterGatherDma function from MiniportInitializeEx to initialize a scatter/gather DMA channel.

Syntax

NDIS_STATUS NdisMRegisterScatterGatherDma(
  [in]      NDIS_HANDLE              MiniportAdapterHandle,
  [in, out] PNDIS_SG_DMA_DESCRIPTION DmaDescription,
  [out]     PNDIS_HANDLE             NdisMiniportDmaHandle
);

Parameters

[in] MiniportAdapterHandle

The miniport handle that NDIS passed to MiniportInitializeEx.

[in, out] DmaDescription

A pointer to an NDIS_SG_DMA_DESCRIPTION structure. This structure describes the scatter/gather DMA properties of the miniport driver. The structure is defined as follows:

typedef struct _NDIS_SG_DMA_DESCRIPTION {
  NDIS_OBJECT_HEADER  Header;
  ULONG  Flags;
  ULONG  MaximumPhysicalMapping;
  MINIPORT_PROCESS_SG_LIST_HANDLER  ProcessSGListHandler;
  MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE_HANDLER  SharedMemAllocateCompleteHandler;
  ULONG  ScatterGatherListSize;
} NDIS_SG_DMA_DESCRIPTION, *PNDIS_SG_DMA_DESCRIPTION;
 

This structure includes the following members:

Header

The NDIS_OBJECT_HEADER structure for the NDIS_SG_DMA_DESCRIPTION structure. Set the Type member of the structure that Header specifies to NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION, the Revision member to NDIS_SG_DMA_DESCRIPTION_REVISION_1, and the Size member to NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1.

Flags

A set of bit flags that define scatter/gather characteristics. Set this member to the bitwise OR of all the required flags.

The NDIS_SG_DMA_64_BIT_ADDRESS flag specifies that the NIC can use 64-bit addressing for DMA operations. Otherwise, the NIC uses 32-bit addressing.

Set this member to zero if 64-bit addressing is not required.

MaximumPhysicalMapping

The maximum number of bytes that the NIC can transfer in a single DMA operation. NDIS provides this value to the hardware abstraction layer (HAL) when allocating a DMA channel, and HAL uses this value to determine the maximum number of map registers to reserve for the NIC.

ProcessSGListHandler

The MiniportProcessSGList function that NDIS calls when HAL is done building the scatter/gather list.

SharedMemAllocateCompleteHandler

The MiniportSharedMemoryAllocateComplete function for miniport drivers that call NdisMAllocateSharedMemoryAsyncEx. This field is optional and it should be NULL if the miniport driver does not call NdisMAllocateSharedMemoryAsyncEx.

ScatterGatherListSize

The size, in bytes, of the memory that is required to hold a scatter/gather list. NDIS sets this value before it returns from NdisMRegisterScatterGatherDma. Miniport drivers should use this size to preallocate memory for each scatter/gather list.

[out] NdisMiniportDmaHandle

A pointer to a variable that the caller supplies and that NDIS fills with a handle. The handle identifies a context area that NDIS uses to manage this DMA resource. The miniport driver passes this handle to NDIS in subsequent calls to NDIS that involve this DMA resource.

Return value

NdisMRegisterScatterGatherDma returns one of the following:

Remarks

An NDIS bus-master miniport driver calls NdisMRegisterScatterGatherDma within its MiniportInitializeEx function to initialize resources for scatter/gather DMA operations. The DmaDescription parameter that the miniport driver passes to NdisMRegisterScatterGatherDma contains the information that NDIS uses to initialize the scatter/gather DMA resources. After NdisMRegisterScatterGatherDma returns, the ScatterGatherListSize member of DmaDescription contains a buffer size that should be sufficient to hold a scatter/gather list. Miniport drivers should use this size to preallocate the memory for scatter/gather lists.

The ProcessSGListHandler member in the DmaDescription parameter defines the entry point in the miniport driver for the MiniportProcessSGList function. When a miniport driver calls NdisMAllocateNetBufferSGList, NDIS calls HAL to provide the scatter/gather list to the miniport driver. HAL calls MiniportProcessSGList after HAL finishes building the scatter/gather list. NDIS can call MiniportProcessSGList outside the context of the call to NdisMAllocateNetBufferSGList.

NdisMRegisterScatterGatherDma returns a pointer to a context area that is opaque to the miniport driver. The miniport driver must use this handle in subsequent calls to NDIS scatter/gather DMA functions.

Bus-master miniport drivers call NdisMAllocateSharedMemoryAsyncEx to dynamically allocate shared memory for data transfer operations. This call is required when high network traffic causes the miniport driver to run low on the shared memory space that the driver allocated during initialization. If NdisMAllocateSharedMemoryAsyncEx returns NDIS_STATUS_PENDING, NDIS calls the MiniportSharedMemoryAllocateComplete function to complete the operation at a later time. Miniport drivers specify the entry point for the MiniportSharedMemoryAllocateComplete function in the SharedMemAllocateCompleteHandler member of the DmaDescription parameter.

Miniport drivers call the NdisMDeregisterScatterGatherDma function to deallocate the DMA resources that NdisMRegisterScatterGatherDma allocated.

Requirements

See also

MiniportInitializeEx

MiniportProcessSGList

NDIS Scatter/Gather DMA

NDIS_OBJECT_HEADER

NdisMAllocateNetBufferSGList

NdisMRegisterMiniportDriver

NdisMSetMiniportAttributes