Función NdisMRegisterScatterGatherDma (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 miniporte maestro de bus llaman a la función NdisMRegisterScatterGatherDma de MiniportInitializeEx para inicializar un canal DMA de dispersión y recopilación.

Sintaxis

NDIS_STATUS NdisMRegisterScatterGatherDma(
  [in]      NDIS_HANDLE              MiniportAdapterHandle,
  [in, out] PNDIS_SG_DMA_DESCRIPTION DmaDescription,
  [out]     PNDIS_HANDLE             NdisMiniportDmaHandle
);

Parámetros

[in] MiniportAdapterHandle

Controlador de minipuerto que NDIS pasó a MiniportInitializeEx.

[in, out] DmaDescription

Puntero a una estructura de NDIS_SG_DMA_DESCRIPTION. Esta estructura describe las propiedades de dispersión y recopilación de DMA del controlador de minipuerto. La estructura se define de la siguiente manera:

typedef struct _NDIS_SG_DMA_DESCRIPTION {
  NDIS_OBJECT_HEADER  Header;
  ULONG  Flags;
  ULONG  MaximumPhysicalMapping;
  MINIPORT_PROCESS_SG_LIST_HANDLER  ProcessSGListHandler;
  MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE_HANDLER  SharedMemAllocateCompleteHandler;
  ULONG  ScatterGatherListSize;
} NDIS_SG_DMA_DESCRIPTION, *PNDIS_SG_DMA_DESCRIPTION;

Esta estructura incluye los siguientes miembros:

Estructura NDIS_OBJECT_HEADER de la estructura NDIS_SG_DMA_DESCRIPTION. Establezca el miembro Type de la estructura que Header especifica para NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION, el miembro Revision en NDIS_SG_DMA_DESCRIPTION_REVISION_1 y el miembro Size en NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1.

Marcas

Conjunto de marcas de bits que definen características de dispersión y recopilación. Establezca este miembro en el OR bit a bit de todas las marcas necesarias.

La marca NDIS_SG_DMA_64_BIT_ADDRESS especifica que la NIC puede usar el direccionamiento de 64 bits para las operaciones DMA. De lo contrario, la NIC usa direccionamiento de 32 bits.

Establezca este miembro en cero si no se requiere direccionamiento de 64 bits.

MaximumPhysicalMapping

Número máximo de bytes que la NIC puede transferir en una sola operación DMA. NDIS proporciona este valor a la capa de abstracción de hardware (HAL) al asignar un canal DMA y HAL usa este valor para determinar el número máximo de registros de mapa que se reservarán para la NIC.

ProcessSGListHandler

La función MiniportProcessSGList a la que llama NDIS cuando HAL termina de crear la lista de dispersión y recopilación.

SharedMemAllocateCompleteHandler

The MiniportSharedMemoryAllocateComplete function for miniport drivers that call NdisMAllocateSharedMemoryAsyncEx. Este campo es opcional y debe ser NULL si el controlador de minipuerto no llama a NdisMAllocateSharedMemoryAsyncEx.

ScatterGatherListSize

Tamaño, en bytes, de la memoria necesaria para contener una lista de dispersión y recopilación. NDIS establece este valor antes de que devuelva de NdisMRegisterScatterGatherDma. Los controladores de minipuerto deben usar este tamaño para preasignar memoria para cada lista de dispersión y recopilación.

[out] NdisMiniportDmaHandle

Puntero a una variable que el autor de la llamada proporciona y que NDIS rellena con un identificador. El identificador identifica un área de contexto que NDIS usa para administrar este recurso DMA. El controlador de miniporte pasa este identificador a NDIS en llamadas posteriores a NDIS que implican este recurso DMA.

Valor devuelto

NdisMRegisterScatterGatherDma devuelve una de las siguientes opciones:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	NdisMRegisterScatterGatherDma asignó correctamente recursos para las operaciones DMA de bus-master.
NDIS_STATUS_RESOURCES	Error de NdisMRegisterScatterGatherDma debido a recursos insuficientes.
NDIS_STATUS_NOT_SUPPORTED	Error de NdisMRegisterScatterGatherDma porque la miniporte no especificó que admite NDIS 6.0 o versiones posteriores, o porque el controlador de miniport no especificó que su NIC es un dispositivo DMA maestro de bus. Un controlador de minipuerto especifica su versión NDIS cuando llama a NdisMRegisterMiniportDriver. Un controlador de minipuerto especifica que admite dispositivos DMA maestros de bus cuando llama a . NdisMSetMiniportAttributes.
NDIS_STATUS_BAD_VERSION	La versión actual de NDIS no admite la versión especificada en el miembro Revision de la estructura Header de DmaDescription .

Comentarios

Un controlador de miniporte NDIS bus-master llama a NdisMRegisterScatterGatherDma dentro de su función MiniportInitializeEx para inicializar los recursos para las operaciones de dispersión y recopilación de DMA. El parámetro DmaDescription que el controlador de miniporte pasa a NdisMRegisterScatterGatherDma contiene la información que usa NDIS para inicializar los recursos DMA de dispersión y recopilación. Después de que NdisMRegisterScatterGatherDma devuelva, el miembro ScatterGatherListSize de DmaDescription contiene un tamaño de búfer que debe ser suficiente para contener una lista de dispersión y recopilación. Los controladores de minipuerto deben usar este tamaño para preasignar la memoria de las listas de dispersión y recopilación.

El miembro ProcessSGListHandler del parámetro DmaDescription define el punto de entrada en el controlador de miniport para la función MiniportProcessSGList . Cuando un controlador de minipuerto llama a NdisMAllocateNetBufferSGList, NDIS llama a HAL para proporcionar la lista de dispersión y recopilación al controlador de minipuerto. HAL llama a MiniportProcessSGList después de que HAL termine de compilar la lista de dispersión y recopilación. NDIS puede llamar a MiniportProcessSGList fuera del contexto de la llamada a NdisMAllocateNetBufferSGList.

NdisMRegisterScatterGatherDma devuelve un puntero a un área de contexto que es opaca para el controlador de minipuerto. El controlador de minipuerto debe usar este identificador en las llamadas posteriores a las funciones de dispersión y recopilación de DMA de NDIS.

Llamada a los conductores de minipuerto de Bus-master NdisMAllocateSharedMemoryAsyncEx para asignar dinámicamente memoria compartida para las operaciones de transferencia de datos. Esta llamada es necesaria cuando el tráfico de red elevado hace que el controlador de miniporte se ejecute poco en el espacio de memoria compartido que el controlador asignó durante la inicialización. Si NdisMAllocateSharedMemoryAsyncEx devuelve NDIS_STATUS_PENDING, NDIS llama al MiniportSharedMemoryAllocateComplete función para completar la operación más adelante. Los controladores de miniport especifican el punto de entrada para la función MiniportSharedMemoryAllocateComplete en el miembro SharedMemAllocateCompleteHandler del parámetro DmaDescription .

Los controladores de minipuerto llaman a Función NdisMDeregisterScatterGatherDma para desasignar los recursos DMA asignados a NdisMRegisterScatterGatherDma .

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)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	Init_RegisterSG(ndis), Irql_Gather_DMA_Function(ndis)