Función NdisMAllocateNetBufferSGList (ndis.h)

Artículo
02/07/2025

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 miniporte maestro de bus llaman a la función NdisMAllocateNetBufferSGList para obtener una lista de dispersión y recopilación de los datos de red asociados a una estructura de NET_BUFFER.

Sintaxis

NDIS_STATUS NdisMAllocateNetBufferSGList(
  [in]           NDIS_HANDLE NdisMiniportDmaHandle,
  [in]           PNET_BUFFER NetBuffer,
  [in]           PVOID       Context,
  [in]           ULONG       Flags,
  [in, optional] PVOID       ScatterGatherListBuffer,
  [in]           ULONG       ScatterGatherListBufferSize
);

Parámetros

[in] NdisMiniportDmaHandle

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] NetBuffer

Puntero a una estructura NET_BUFFER. NdisMAllocateNetBufferSGList asigna una lista de dispersión y recopilación para los datos de red asociados a esta estructura de NET_BUFFER. La lista de dispersión y recopilación se genera a partir de los datos que comienzan al principio de la MDL que se especifica en el currentMdl miembro de la estructura de NET_BUFFER_DATA asociada.

[in] Context

Puntero a un área de contexto que creó el autor de la llamada. HAL pasa este puntero a MiniportProcessSGList después de que HAL cree la lista de dispersión y recopilación. El autor de la llamada puede usar este área de contexto para sus propios fines.

[in] Flags

Marcas NDIS que se pueden combinar con una operación OR. Para borrar todas las marcas, establezca este miembro en cero. Esta función admite la marca NDIS_SG_LIST_WRITE_TO_DEVICE que; si se establece, indica que la dirección de la transferencia DMA es del NET_BUFFER al dispositivo. Si NDIS_SG_LIST_WRITE_TO_DEVICE está claro, la transferencia procede del dispositivo. Los controladores de miniport deben establecer esta marca en la ruta de acceso de envío cuando la operación DMA transfiere datos de un NET_BUFFER al dispositivo. Los controladores de miniporte que realizan operaciones DMA desde el dispositivo a un NET_BUFFER asignado previamente, por ejemplo, las NIC compatibles con la descarga de chimenea durante las operaciones de recepción, deben borrar esta marca.

[in, optional] ScatterGatherListBuffer

Si no NULL , scatterGatherListBuffer especifica un puntero al almacenamiento que el autor de la llamada asigna para contener la lista de dispersión y recopilación. Si NULL, NDIS asigna almacenamiento para la lista de dispersión y recopilación.

[in] ScatterGatherListBufferSize

Si el parámetro scatterGatherListBuffer no es null, scatterGatherListBufferSize especifica el tamaño del búfer que contiene la lista de dispersión y recopilación. Si este tamaño es demasiado pequeño, NDIS asigna almacenamiento para la lista de dispersión y recopilación. Si el parámetro ScatterGatherListBuffer es NULL, no se usa este parámetro.

Valor devuelto

NdisMAllocateNetBufferSGList devuelve una de las siguientes opciones:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList compilar correctamente la lista de dispersión y recopilación para la estructura de NET_BUFFER especificada.
NDIS_STATUS_RESOURCES	NdisMAllocateNetBufferSGList no se pudo realizar debido a recursos insuficientes.

Observaciones

Un controlador de miniporte NDIS bus-master llama a NdisMAllocateNetBufferSGList desde su función MiniportSendNetBufferLists. El controlador de miniporta llama a NdisMAllocateNetBufferSGList una vez por cada estructura de NET_BUFFER para la que debe obtener una lista de dispersión y recopilación.

Cuando un controlador de miniporta llama a NdisMAllocateNetBufferSGList, NDIS llama a HAL para crear la lista de dispersión y recopilación. Una vez que HAL compila la lista de dispersión y recopilación, llama a la función miniportProcessSGList que el controlador de miniporte registró llamando a NdisMRegisterScatterGatherDma.

HAL puede llamar a miniportProcessSGList antes o después de que NDIS devuelva de NdisMAllocateNetBufferSGList. Los controladores de miniport no deben intentar acceder a la lista de dispersión o recopilación hasta después de llamar a HAL MiniportProcessSGList.

Para mejorar el rendimiento del sistema, los controladores de miniport deben preasignar búferes para su uso en el parámetro ScatterGatherListBuffer de NdisMAllocateNetBufferSGList. NDIS proporciona el tamaño recomendado para los búferes del miembro ScatterGatherListSize del parámetro DmaDescription cuando el controlador de miniporta llama a NdisMRegisterScatterGatherDma. Los controladores de miniport especifican el tamaño del búfer en el parámetro ScatterGatherListBufferSize cuando llaman a NdisMAllocateNetBufferSGList.

NDIS puede asignar un búfer incluso si el controlador de miniporte especifica un búfer en el parámetro ScatterGatherListBuffer. Esto puede ocurrir si el búfer especificado es demasiado pequeño para contener la lista de dispersión y recopilación. Por lo tanto, los escritores de controladores no deben suponer que el búfer especificado en el parámetro ScatterGatherListBuffer contiene la lista de dispersión y recopilación. HAL pasa el puntero de lista de dispersión y recopilación correcto al función del controlador de miniporte.

Para mejorar el rendimiento del sistema, la lista de dispersión y recopilación se genera a partir de los datos de red a partir del principio de la MDL que se especifica en el miembro CurrentMdl de la estructura de NET_BUFFER_DATA asociada. El inicio de los datos de red de la lista SG se desplaza desde el principio de la lista SG por el valor especificado en el currentMdlOffset miembro de la estructura de NET_BUFFER_DATA asociada.

Los controladores de miniport deben llamar a la función NdisMFreeNetBufferSGList para liberar una lista de dispersión y recopilación.

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)
biblioteca de	Ndis.lib
irQL	DISPATCH_LEVEL
reglas de cumplimiento de DDI	Irql_Gather_DMA_Function(ndis)