Función NdisMAllocateNetBufferSGList (ndis.h)

Artículo
02/29/2024

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 minipuerto de Bus-master 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 mediante una llamada a Función NdisMRegisterScatterGatherDma .

[in] NetBuffer

Puntero a una estructura de 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 miembro CurrentMdl 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 la dirección de la transferencia de DMA desde el NET_BUFFER al dispositivo. Si NDIS_SG_LIST_WRITE_TO_DEVICE está claro, la transferencia procede del dispositivo. Los controladores de minipuerto 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 una NET_BUFFER asignada 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 es 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 es 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, este parámetro no se usa.

Valor devuelto

NdisMAllocateNetBufferSGList devuelve una de las siguientes opciones:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList ha creado correctamente la lista de dispersión y recopilación para la estructura de NET_BUFFER especificada.
NDIS_STATUS_RESOURCES	Error de NdisMAllocateNetBufferSGList debido a recursos insuficientes.

Comentarios

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

Cuando un controlador de miniporte 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ó mediante una llamada a . NdisMRegisterScatterGatherDma.

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

Para mejorar el rendimiento del sistema, los controladores de minipuerto deben prealcalizar los 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 miniporte 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 minipuerto 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 asumir 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/recopilación correcto a la función MiniportProcessSGList del controlador de miniport.

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 miembro CurrentMdlOffset 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 o recopilación.

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	DISPATCH_LEVEL
Reglas de cumplimiento de DDI	Irql_Gather_DMA_Function(ndis)