Función NdisMAllocateSharedMemoryAsyncEx (ndis.h)

Artículo
08/07/2023

Precaución

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 de DMA en controladores kmDF.

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

Los controladores de Miniport llaman a la función NdisMAllocateSharedMemoryAsyncEx para asignar memoria adicional compartida entre el controlador y su NIC DMA de bus-master, 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 mediante una llamada a 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 a la función MiniportSharedMemoryAllocateComplete 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 describa la memoria compartida asignada. Si se produce un error en el intento de asignar memoria compartida, NDIS llama a MiniportSharedMemoryAllocateComplete y pasa punteros NULL .
NDIS_STATUS_FAILURE	La memoria solicitada no se pudo asignar en este momento. Si NdisMAllocateSharedMemoryAsyncEx devuelve este estado, una llamada posterior con los mismos parámetros podría realizarse correctamente, dependiendo de si los recursos del sistema están disponibles.

Comentarios

Nota Un controlador de minipuerto ya debe haber llamado a 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 dinámicamente memoria compartida. 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 impone demandas excesivas en el espacio de memoria compartido existente.

Este controlador de minipuerto 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 mínimo determinado por el controlador, el controlador de miniporta llama a NdisMAllocateSharedMemoryAsyncEx para asignar más espacio de búfer en memoria compartida. Cuando el número de búferes disponibles sube a un alto determinado por el controlador, el controlador de minipuerto 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 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 minipuerto 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 como para que el controlador no se quede sin búferes. No sea 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	Value
Cliente mínimo compatible	Compatible con NDIS 6.0 y versiones posteriores.
Plataforma de destino	Universal
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL
Reglas de cumplimiento de DDI	Irql_Gather_DMA_Function(ndis)