NdisMRegisterScatterGatherDma (Compact 2013)

  • Article

3/26/2014

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 PNDIS_SG_DMA_DESCRIPTION  DmaDescription,
    OUT PNDIS_HANDLE  NdisMiniportDmaHandle
    );

Parameters

  • MiniportAdapterHandle
    The miniport handle that NDIS passed to MiniportInitializeEx.

  • 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 finished building the scatter/gather list.
    • SharedMemAllocateCompleteHandler
      This field is unused and should be set to NULL.
    • 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.
  • 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 later calls to NDIS that involve this DMA resource.

Return Value

NdisMRegisterScatterGatherDma returns one of the following:

Value

Meaning

NDIS_STATUS_SUCCESS

NdisMRegisterScatterGatherDma successfully allocated resources for bus-master DMA operations.

NDIS_STATUS_RESOURCES

NdisMRegisterScatterGatherDma failed because of insufficient resources.

NDIS_STATUS_NOT_SUPPORTED

NdisMRegisterScatterGatherDma failed because the miniport did not specify that it supports NDIS 6.0 or later versions, or because the miniport driver did not specify that its NIC is a bus-master DMA device. A miniport driver specifies its NDIS version when it calls NdisMRegisterMiniportDriver. A miniport driver specifies that it supports bus-master DMA devices when it calls NdisMSetMiniportAttributes.

NDIS_STATUS_BAD_VERSION

The current version of NDIS does not support the version that is specified in the Revision member of the Header structure of DmaDescription.

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 later calls to NDIS scatter/gather DMA functions.

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

Requirements

Header

ndis.h

See Also

Reference

NDIS Scatter/Gather DMA Functions
MiniportInitializeEx
NDIS_OBJECT_HEADER
NdisMAllocateNetBufferSGList
NdisMDeregisterScatterGatherDma
NdisMRegisterMiniportDriver
NdisMSetMiniportAttributes