Función NdisMAllocateSharedMemoryAsyncEx (ndis.h)

2025-02-07

Cautela

En el caso de los procesadores ARM y ARM64, se recomienda encarecidamente que los escritores de controladores NDIS usen WDF DMA o WDM DMA en lugar de NDIS Scatter/Gather DMA.

Para obtener más información sobre WDF DMA, vea control de operaciones DMA en controladores kmDF.

Para obtener más información sobre WDM DMA, consulte los temas secundarios relacionados con DMA de Administración de entradas y salidas para controladores.

Los controladores de miniport llaman a la función NdisMAllocateSharedMemoryAsyncEx para asignar memoria adicional compartida entre el controlador y su NIC DMA maestra de bus, normalmente cuando el controlador de miniporte se está ejecutando bajo en los búferes de recepción de NIC disponibles.

Sintaxis

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

Parámetros

[in] MiniportDmaHandle

Identificador de un área de contexto que NDIS usa para administrar un recurso DMA. El autor de la llamada obtuvo este identificador llamando al función NdisMRegisterScatterGatherDma.

[in] Length

Número de bytes que se van a asignar.

[in] Cached

Este parámetro se omite (la memoria almacenada en caché siempre se usa en sistemas x86 y x64).

[in] Context

Puntero al contexto determinado por el controlador que se va a pasar al MiniportSharedMemoryAllocateComplete función cuando se llama a ella.

Valor devuelto

NdisMAllocateSharedMemoryAsyncEx puede devolver una de las siguientes opciones:

Código devuelto	Descripción
NDIS_STATUS_PENDING	NDIS llamará a la función MiniportSharedMemoryAllocateComplete y proporcionará información que describe la memoria compartida asignada. Si se produce un error en el intento de asignar memoria compartida, las llamadas NDIS miniportSharedMemoryAllocateComplete y pasan punteros de NULL.
NDIS_STATUS_FAILURE	La memoria solicitada no se pudo asignar en este momento. Si NdisMAllocateSharedMemoryAsyncEx devuelve este estado, es posible que una llamada posterior con los mismos parámetros se realice correctamente, en función de si los recursos del sistema están disponibles.

Observaciones

Nota Un controlador de miniporte debe haber llamado ya canal NdisMRegisterScatterGatherDma o NdisMRegisterDmaChannel para inicializar un canal DMA de dispersión o recopilación antes de llamar a NdisMAllocateSharedMemoryAsyncEx.

Los controladores de NIC DMA de bus-master llaman a NdisMAllocateSharedMemoryAsyncEx para asignar memoria compartida dinámicamente. Estos controladores también asignan espacio de memoria compartido durante la inicialización. Estos controladores usan la memoria compartida asignada dinámicamente para las operaciones de transferencia cuando el tráfico de red elevado exige excesivamente el espacio de memoria compartido existente.

Este miniportador normalmente mantiene una o varias variables de estado para realizar un seguimiento del número de búferes de memoria compartidos disponibles para las transferencias entrantes. Cuando el número de búferes disponibles alcanza un bajo determinado por el controlador, el controlador de miniporta llama a NdisMAllocateSharedMemoryAsyncEx para asignar más espacio de búfer en la memoria compartida. Cuando el número de búferes disponibles sube a un alto determinado por el controlador, el controlador de miniporta llama a NdisMFreeSharedMemory una o varias veces para liberar sus asignaciones dinámicas anteriores.

Normalmente, este tipo de controlador de minipuerto conserva el bloque de memoria compartida que su función de MiniportInitializeEx asignada con NdisMAllocateSharedMemory hasta que se quita una NIC. Cuando se quita la NIC, NDIS llama a la función miniporthaltEx del controlador de miniport. Esta asignación es suficiente para controlar una demanda media de transferencias a través de la NIC.

Un controlador de miniport debe establecer un límite en la cantidad de memoria compartida que puede asignar. Este límite es específico del controlador y debe ser lo suficientemente alto para que el controlador no se quede sin búferes. No et un límite excesivamente alto, ya que esto podría dar lugar a un consumo desperdiciado de memoria compartida que podría reducir el rendimiento del sistema.

Cualquier controlador de miniport que llame a NdisMAllocateSharedMemoryAsyncEx o NdisMAllocateSharedMemory debe liberar todas las asignaciones pendientes con una o varias llamadas a NdisMFreeSharedMemory cuando se quita su NIC.

Requisitos

Requisito	Valor
cliente mínimo admitido	Se admite en NDIS 6.0 y versiones posteriores.
de la plataforma de destino de	Universal
encabezado de	ndis.h (incluya Ndis.h)
irQL	<= DISPATCH_LEVEL
reglas de cumplimiento de DDI	Irql_Gather_DMA_Function(ndis)