PCALCULATE_SCATTER_GATHER_LIST_SIZE función de devolución de llamada (wdm.h)

Artículo
08/08/2023

La rutina CalculateScatterGatherList calcula el tamaño, en bytes, de la lista de dispersión y recopilación necesaria para contener un búfer determinado.

Sintaxis

PCALCULATE_SCATTER_GATHER_LIST_SIZE PcalculateScatterGatherListSize;

NTSTATUS PcalculateScatterGatherListSize(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in, optional]  PMDL Mdl,
  [in]            PVOID CurrentVa,
  [in]            ULONG Length,
  [out]           PULONG ScatterGatherListSize,
  [out, optional] PULONG pNumberOfMapRegisters
)
{...}

Parámetros

[in] DmaAdapter

Puntero a la estructura DMA_ADAPTER devuelta por IoGetDmaAdapter que representa el adaptador de bus-master o el controlador DMA.

[in, optional] Mdl

NULL o un puntero a la MDL que contiene el búfer.

[in] CurrentVa

Puntero a la dirección virtual del principio del búfer.

[in] Length

Especifica la longitud del búfer, en bytes.

[out] ScatterGatherListSize

Puntero a la variable que usa la rutina para devolver el tamaño de la lista de dispersión y recopilación, en bytes.

[out, optional] pNumberOfMapRegisters

NULL o puntero a la variable que usa la rutina para devolver el número de registros de mapa necesarios para las operaciones DMA en el búfer.

Valor devuelto

CalculateScatterGatherList devuelve uno de los siguientes códigos de estado.

Código devuelto	Descripción
STATUS_SUCCESS	Los valores devueltos en ScatterGatherListSize y NumberOfMapRegisters son válidos .
STATUS_INSUFFICIENT_RESOURCES	El número de registros de mapa necesarios supera el número de registros de mapa disponibles.
STATUS_BUFFER_TOO_SMALL	La longitud especificada es demasiado grande para caber dentro del búfer.

Comentarios

CalculateScatterGatherList no es una rutina del sistema a la que se puede llamar directamente por nombre. Solo el puntero de la dirección devuelta en una estructura de DMA_OPERATIONS puede llamar a esta rutina. Los controladores obtienen la dirección de esta rutina llamando a IoGetDmaAdapter con el miembro Version del parámetro DeviceDescription establecido en DEVICE_DESCRIPTION_VERSION2. Si IoGetDmaAdapter devuelve NULL, la rutina no está disponible en la plataforma.

Si el autor de la llamada pasa NULL para el parámetro Mdl , la rutina calcula el tamaño máximo posible necesario para contener una lista de dispersión o recopilación para el búfer especificado. Si el autor de la llamada especifica la MDL que contiene el búfer en el parámetro Mdl , la rutina calcula el tamaño real necesario para contener la lista de dispersión y recopilación.

Un controlador usa CalculateScatterGatherList para asignar un búfer de lista de dispersión y recopilación para pasar a BuildScatterGatherList.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows XP y versiones posteriores de Windows.
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluya Wdm.h)
IRQL	Cualquier nivel