NdisMRegisterScatterGatherDma 函数 (ndis.h)

项目
08/07/2023

注意

对于 ARM 和 ARM64 处理器，我们强烈建议 NDIS 驱动程序编写器使用 WDF DMA 或 WDM DMA，而不是 NDIS 散点/收集 DMA。

有关 WDF DMA 的详细信息，请参阅处理 KMDF 驱动程序中的 DMA 操作。

有关 WDM DMA 的详细信息，请参阅管理驱动程序的输入/输出中与 DMA 相关的子主题。

总线主微型端口驱动程序调用 MiniportInitializeEx 中的 NdisMRegisterScatterGatherDma 函数来初始化散点/收集 DMA 通道。

语法

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

参数

[in] MiniportAdapterHandle

NDIS 传递给 MiniportInitializeEx 的微型端口句柄。

[in, out] DmaDescription

指向NDIS_SG_DMA_DESCRIPTION结构的指针。此结构描述微型端口驱动程序的散点/收集 DMA 属性。结构定义如下：

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;

此结构包括以下成员：

NDIS_SG_DMA_DESCRIPTION 结构的NDIS_OBJECT_HEADER结构。将 Header 指定的结构的 Type 成员设置为 NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION，将 Revision 成员设置为 NDIS_SG_DMA_DESCRIPTION_REVISION_1，并将 Size 成员设置为 NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1。

Flags

定义散点/收集特征的一组位标志。将此成员设置为所有必需标志的按位 OR。

NDIS_SG_DMA_64_BIT_ADDRESS 标志指定 NIC 可以对 DMA 操作使用 64 位寻址。否则，NIC 使用 32 位寻址。

如果不需要 64 位寻址，请将此成员设置为零。

MaximumPhysicalMapping

NIC 可以在单个 DMA 操作中传输的最大字节数。分配 DMA 通道时，NDIS 向硬件抽象层提供此值， (HAL) ，HAL 使用此值来确定要为 NIC 保留的最大映射寄存器数。

ProcessSGListHandler

NDIS 在完成 HAL 生成散点/收集列表时调用的 MiniportProcessSGList 函数。

SharedMemAllocateCompleteHandler

The MiniportSharedMemoryAllocateComplete 函数，用于调用微型端口驱动程序 NdisMAllocateSharedMemoryAsyncEx. 此字段是可选的，如果微型端口驱动程序不调用 NdisMAllocateSharedMemoryAsyncEx，则此字段应为 NULL。

ScatterGatherListSize

保存散点/收集列表所需的内存大小（以字节为单位）。 NDIS 在从 NdisMRegisterScatterGatherDma 返回之前设置此值。微型端口驱动程序应使用此大小来预分配每个散点/收集列表的内存。

[out] NdisMiniportDmaHandle

指向调用方提供且 NDIS 用句柄填充的变量的指针。句柄标识 NDIS 用于管理此 DMA 资源的上下文区域。微型端口驱动程序在后续调用涉及此 DMA 资源的 NDIS 时将此句柄传递给 NDIS。

返回值

NdisMRegisterScatterGatherDma 返回下列值之一：

返回代码	说明
NDIS_STATUS_SUCCESS	NdisMRegisterScatterGatherDma 已成功为总线主 DMA 操作分配资源。
NDIS_STATUS_RESOURCES	NdisMRegisterScatterGatherDma 由于资源不足而失败。
NDIS_STATUS_NOT_SUPPORTED	NdisMRegisterScatterGatherDma 失败，因为微型端口未指定它支持 NDIS 6.0 或更高版本，或者微型端口驱动程序未指定其 NIC 是总线主 DMA 设备。微型端口驱动程序在调用时指定其 NDIS 版本 NdisMRegisterMiniportDriver。微型端口驱动程序指定它在调用时支持总线主 DMA 设备 NdisMSetMiniportAttributes。
NDIS_STATUS_BAD_VERSION	NDIS 的当前版本不支持 DmaDescription 的标头结构的 Revision 成员中指定的版本。

注解

NDIS 总线主微型端口驱动程序在其 MiniportInitializeEx 函数中调用 NdisMRegisterScatterGatherDma，以初始化散点/收集 DMA 操作的资源。微型端口驱动程序传递给 NdisMRegisterScatterGatherDma 的 DmaDescription 参数包含 NDIS 用于初始化散点/收集 DMA 资源的信息。 NdisMRegisterScatterGatherDma 返回后，DmaDescription 的 ScatterGatherListSize 成员包含的缓冲区大小应足以容纳散点/收集列表。微型端口驱动程序应使用此大小来预分配散点/收集列表的内存。

DmaDescription 参数中的 ProcessSGListHandler 成员定义 MiniportProcessSGList 函数的微型端口驱动程序中的入口点。当微型端口驱动程序调用时 NdisMAllocateNetBufferSGList， NDIS 调用 HAL 以向微型端口驱动程序提供散点/收集列表。 HAL 在 HAL 完成构建散点/收集列表后调用 MiniportProcessSGList 。 NDIS 可以在调用 NdisMAllocateNetBufferSGList 的上下文外部调用 MiniportProcessSGList。

NdisMRegisterScatterGatherDma 返回指向微型端口驱动程序不透明的上下文区域的指针。微型端口驱动程序必须在对 NDIS 散点/收集 DMA 函数的后续调用中使用此句柄。

总线主微型端口驱动程序调用 NdisMAllocateSharedMemoryAsyncEx 为数据传输操作动态分配共享内存。当高网络流量导致微型端口驱动程序在初始化期间分配的共享内存空间不足时，需要此调用。如果 NdisMAllocateSharedMemoryAsyncEx 返回NDIS_STATUS_PENDING，则 NDIS 将调用 MiniportSharedMemoryAllocateComplete 函数，以便稍后完成操作。微型端口驱动程序在 DmaDescription 参数的 SharedMemAllocateCompleteHandler 成员中指定 MiniportSharedMemoryAllocateComplete 函数的入口点。

微型端口驱动程序调用 NdisMDeregisterScatterGatherDma 函数，用于解除分配 NdisMRegisterScatterGatherDma 分配的 DMA 资源。

要求

要求	值
最低受支持的客户端	在 NDIS 6.0 及更高版本中受支持。
目标平台	通用
标头	ndis.h (包括 Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI 符合性规则	Init_RegisterSG (ndis) ， Irql_Gather_DMA_Function (ndis)