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传输到设备时，微型端口驱动程序应在发送路径上设置此标志。 从设备到预分配NET_BUFFER执行 DMA 操作的微型端口驱动程序（例如，在接收操作期间支持烟囱卸载的 NIC）应清除此标志。
[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 参数的 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) |