NdisMAllocateSharedMemoryAsyncEx 函数 (ndis.h)

项目
02/29/2024

注意

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

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

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

微型端口驱动程序调用 NdisMAllocateSharedMemoryAsyncEx 函数，以分配驱动程序与其总线主 DMA NIC 之间共享的额外内存，通常当微型端口驱动程序的可用 NIC 接收缓冲区不足时。

语法

NDIS_STATUS NdisMAllocateSharedMemoryAsyncEx(
  [in] NDIS_HANDLE MiniportDmaHandle,
  [in] ULONG       Length,
  [in] BOOLEAN     Cached,
  [in] PVOID       Context
);

参数

[in] MiniportDmaHandle

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

[in] Length

要分配的字节数。

[in] Cached

(缓存内存始终在 x86 和 x64 系统上使用) ，则忽略此参数。

[in] Context

指向驱动程序确定的上下文的指针，该上下文将在调用时传递给 MiniportSharedMemoryAllocateComplete 函数。

返回值

NdisMAllocateSharedMemoryAsyncEx 可以返回下列值之一：

返回代码	说明
NDIS_STATUS_PENDING	NDIS 将调用 MiniportSharedMemoryAllocateComplete 函数，并提供描述已分配共享内存的信息。如果尝试分配共享内存失败，NDIS 将调用 MiniportSharedMemoryAllocateComplete 并传递 NULL 指针。
NDIS_STATUS_FAILURE	此时无法分配请求的内存。如果 NdisMAllocateSharedMemoryAsyncEx 返回此状态，则具有相同参数的后续调用可能会成功，具体取决于系统资源是否可用。

注解

注意微型端口驱动程序必须已调用 NdisMRegisterScatterGatherDma 或 NdisMRegisterDmaChannel 来初始化散点/收集 DMA 通道，然后才能调用 NdisMAllocateSharedMemoryAsyncEx。

总线主 DMA NIC 的驱动程序调用 NdisMAllocateSharedMemoryAsyncEx 以动态分配共享内存。此类驱动程序还会在初始化期间分配共享内存空间。当高网络流量对现有共享内存空间提出过多需求时，这些驱动程序使用动态分配的共享内存进行传输操作。

此类微型端口驱动程序通常维护一个或多个状态变量，以跟踪可用于传入传输的共享内存缓冲区的数量。当可用缓冲区数达到驱动程序确定的低时，微型端口驱动程序会调用 NdisMAllocateSharedMemoryAsyncEx ，以在共享内存中分配更多缓冲区空间。当可用缓冲区数攀升到驱动程序确定的高点时，微型端口驱动程序调用 NdisMFreeSharedMemory 一次或多次以释放其前面的动态分配。

通常，此类微型端口驱动程序会保留其 MiniportInitializeEx 函数使用 NdisMAllocateSharedMemory 分配的共享内存块，直到删除 NIC。删除 NIC 后，NDIS 会调用微型端口驱动程序的 MiniportHaltEx 函数。此分配足以处理通过 NIC 传输的平均需求。

微型端口驱动程序应设置可分配的共享内存量的限制。此限制特定于驱动程序，应足够高，以便驱动程序不会耗尽缓冲区。不要使用过高的限制，因为这可能会浪费共享内存，从而降低系统性能。

任何调用 NdisMAllocateSharedMemoryAsyncEx 或 NdisMAllocateSharedMemory 的微型端口驱动程序都必须在删除 NIC 时释放所有未完成的分配，并调用 NdisMFreeSharedMemory 。

要求

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