NdisMAllocateNetBufferSGList 函数 (ndis.h)

项目
02/27/2024

注意

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

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

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

总线主微型端口驱动程序调用 NdisMAllocateNetBufferSGList 函数，以获取与 NET_BUFFER 结构关联的网络数据的散点/收集列表。

语法

NDIS_STATUS NdisMAllocateNetBufferSGList(
  [in]           NDIS_HANDLE NdisMiniportDmaHandle,
  [in]           PNET_BUFFER NetBuffer,
  [in]           PVOID       Context,
  [in]           ULONG       Flags,
  [in, optional] PVOID       ScatterGatherListBuffer,
  [in]           ULONG       ScatterGatherListBufferSize
);

参数

[in] NdisMiniportDmaHandle

NDIS 用于管理 DMA 资源的上下文区域的句柄。调用方通过调用获取此句柄 NdisMRegisterScatterGatherDma 函数。

[in] NetBuffer

指向NET_BUFFER结构的指针。 NdisMAllocateNetBufferSGList 为与此NET_BUFFER结构关联的网络数据分配散点/收集列表。散点/收集列表是从在关联NET_BUFFER_DATA结构的 CurrentMdl 成员中指定的 MDL 开头开始的数据生成的。

[in] Context

指向调用方创建的上下文区域的指针。在 HAL 创建散点/收集列表后，HAL 将此指针传递到 MiniportProcessSGList 。调用方可以将此上下文区域用于自己的目的。

[in] Flags

可与 OR 操作组合的 NDIS 标志。若要清除所有标志，请将此成员设置为零。此函数支持以下NDIS_SG_LIST_WRITE_TO_DEVICE标志：如果已设置，则指示 DMA 传输的方向是从NET_BUFFER传输到设备。如果NDIS_SG_LIST_WRITE_TO_DEVICE清晰，则传输来自设备。当 DMA 操作将数据从NET_BUFFER传输到设备时，微型端口驱动程序应在发送路径上设置此标志。从设备到预分配NET_BUFFER执行 DMA 操作的微型端口驱动程序（例如，在接收操作期间支持烟囱卸载的 NIC）应清除此标志。

[in, optional] ScatterGatherListBuffer

如果不是 NULL， 则 ScatterGatherListBuffer 指定指向调用方分配用于保存散点/收集列表的存储的指针。如果 为 NULL，则 NDIS 为散点/收集列表分配存储。

[in] ScatterGatherListBufferSize

如果 ScatterGatherListBuffer 参数不为 NULL， 则 ScatterGatherListBufferSize 指定包含散点/收集列表的缓冲区的大小。如果此大小太小，NDIS 会为散点/收集列表分配存储。如果 ScatterGatherListBuffer 参数为 NULL，则不使用此参数。

返回值

NdisMAllocateNetBufferSGList 返回下列值之一：

返回代码	说明
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList 已成功为指定的NET_BUFFER结构生成散点/收集列表。
NDIS_STATUS_RESOURCES	NdisMAllocateNetBufferSGList 由于资源不足而失败。

注解

NDIS 总线主微型端口驱动程序从其调用 NdisMAllocateNetBufferSGList MiniportSendNetBufferLists 函数。微型端口驱动程序为每个必须获取散点/收集列表NET_BUFFER结构调用 NdisMAllocateNetBufferSGList 一次。

当微型端口驱动程序调用 NdisMAllocateNetBufferSGList 时，NDIS 调用 HAL 来生成散点/收集列表。 HAL 生成散点/收集列表后，它会调用微型端口驱动程序通过调用注册的 MiniportProcessSGList 函数 NdisMRegisterScatterGatherDma。

HAL 可以在 NDIS 从 NdisMAllocateNetBufferSGList 返回之前或之后调用 MiniportProcessSGList。在 HAL 调用 MiniportProcessSGList 之前，微型端口驱动程序不得尝试访问散点/收集列表。

若要提高系统性能，微型端口驱动程序应预先分配缓冲区，以便在 NdisMAllocateNetBufferSGList 的 ScatterGatherListBuffer 参数中使用。当微型端口驱动程序调用 NdisMRegisterScatterGatherDma 时，NDIS 为 DmaDescription 参数的 ScatterGatherListSize 成员中的缓冲区提供建议的大小。微型端口驱动程序在调用 NdisMAllocateNetBufferSGList 时指定 ScatterGatherListBufferSize 参数中的缓冲区大小。

即使微型端口驱动程序在 ScatterGatherListBuffer 参数中指定缓冲区，NDIS 也可能分配缓冲区。如果指定的缓冲区太小，无法容纳散点/收集列表，则可能会发生这种情况。因此，驱动程序编写器不得假定 ScatterGatherListBuffer 参数中指定的缓冲区包含散点/收集列表。 HAL 将正确的散点/收集列表指针传递到微型端口驱动程序的 MiniportProcessSGList 函数。

为了提高系统性能，从在关联NET_BUFFER_DATA结构的 CurrentMdl 成员中指定的 MDL 开头的网络数据生成散点 / 收集列表。 SG 列表中的网络数据的开头与 SG 列表的开头偏移了关联NET_BUFFER_DATA结构的 CurrentMdlOffset 成员中指定的值。

微型端口驱动程序必须调用 NdisMFreeNetBufferSGList 函数来释放散点/收集列表。

要求

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