NdisMAllocateNetBufferSGList 函数 （ndis.h）
谨慎
对于 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传输到设备时，微型端口驱动程序应在发送路径上设置此标志。 从设备执行 DMA作的微型端口驱动程序应清除此标志，例如接收作期间能够卸载能够卸载的 NIC 的预分配NET_BUFFER。
[in, optional] ScatterGatherListBuffer
如果未 NULL，ScatterGatherListBuffer 指定调用方分配用于保存散点/收集列表的存储的指针。 如果 NULL，则 NDIS 将为散点/收集列表分配存储。
[in] ScatterGatherListBufferSize
如果 ScatterGatherListBuffer 参数未 NULL，ScatterGatherListBufferSize 指定包含散点/收集列表的缓冲区的大小。 如果此大小太小，NDIS 将为散点/收集列表分配存储。 如果 ScatterGatherListBuffer 参数 NULL，则不使用此参数。
返回值
NdisMAllocateNetBufferSGList 返回以下项之一：
| 返回代码 | 描述 |
|---|---|
|
NdisMAllocateNetBufferSGList 成功为指定的NET_BUFFER结构生成散点/收集列表。 |
|
NdisMAllocateNetBufferSGList 由于资源不足而失败。 |
言论
NDIS 总线主微型端口驱动程序从其调用 NdisMAllocateNetBufferSGList MiniportSendNetBufferLists 函数。 微型端口驱动程序为每个必须获取散点/收集列表的每个 NET_BUFFER 结构调用 NdisMAllocateNetBufferSGList 一次。
当微型端口驱动程序调用 NdisMAllocateNetBufferSGList时，NDIS 调用 HAL 以生成散点/收集列表。 HAL 生成散点/收集列表后，它会调用通过调用注册的微型端口驱动程序 函数 MiniportProcessSGList NdisMRegisterScatterGatherDma.
HAL 可以在 NDIS 从 NdisMAllocateNetBufferSGList返回之前或之后调用 MiniportProcessSGList。 在 HAL 调用 MiniportProcessSGList之后，微型端口驱动程序不得尝试访问散点/收集列表。
为了提高系统性能，微型端口驱动程序应预分配缓冲区，以便在 NdisMAllocateNetBufferSGList的 ScatterGatherListBuffer 参数中使用。 当微型端口驱动程序调用 NdisMRegisterScatterGatherDma时，NDIS 为 DmaDescription 参数 成员中的缓冲区提供建议的大小。 微型端口驱动程序在调用 NdisMAllocateNetBufferSGList时，在 ScatterGatherListBufferSize 参数中指定缓冲区的大小。
即使微型端口驱动程序在 ScatterGatherListBuffer 参数中指定了缓冲区，NDIS 也可以分配缓冲区。 如果指定的缓冲区太小，无法保存散点/收集列表，则可能会发生这种情况。 因此，驱动程序编写器不得假定 ScatterGatherListBuffer 参数中指定的缓冲区包含散点/收集列表。 HAL 将正确的散点/收集列表指针传递给微型端口驱动程序的 MiniportProcessSGList 函数。
为了提高系统性能，从在关联 NET_BUFFER_DATA 结构的 CurrentMdl 成员指定的 MDL 开头的网络数据生成散点/收集列表。 SG 列表中的网络数据的起始位置由 CurrentMdlOffset 中指定的值 关联NET_BUFFER_DATA结构的成员从 SG 列表的开头偏移。
微型端口驱动程序必须调用 NdisMFreeNetBufferSGList 函数来释放散点/收集列表。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | NDIS 6.0 及更高版本中受支持。 |
| 目标平台 | 普遍 |
| 标头 | ndis.h （包括 Ndis.h） |
| 库 | Ndis.lib |
| IRQL | DISPATCH_LEVEL |
| DDI 符合性规则 | Irql_Gather_DMA_Function（ndis） |