NdisMRegisterScatterGatherDma 函数 (ndis.h)

注意

对于 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 指定要NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION的结构的 Type 成员、要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 完成生成散点/收集列表时 NDIS 调用的 MiniportProcessSGList 函数。

SharedMemAllocateCompleteHandler

必须向用于调用的微型端口驱动程序的 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 操作的资源。 微型端口驱动程序传递给 NdisMRegisterScatterGatherDmaDmaDescription 参数包含 NDIS 用来初始化散点/收集 DMA 资源的信息。 NdisMRegisterScatterGatherDma 返回后,DmaDescriptionScatterGatherListSize 成员包含的缓冲区大小应该足以容纳散点/收集列表。 微型端口驱动程序应使用此大小来预分配散点/收集列表的内存。

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)

另请参阅

MiniportInitializeEx

MiniportProcessSGList

MiniportSharedMemoryAllocateComplete

NDIS 分散/聚合 DMA

NDIS_OBJECT_HEADER

NdisMAllocateNetBufferSGList

NdisMAllocateSharedMemoryAsyncEx NdisMDeregisterScatterGatherDma

NdisMRegisterMiniportDriver

NdisMSetMiniportAttributes