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

Artículo
02/07/2025

El CalculateScatterGatherList rutina 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 al 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

Ya sea 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	El de longitud especificado es demasiado grande para caber en el búfer.

Observaciones

CalculateScatterGatherList no es una rutina del sistema a la que se puede llamar directamente por nombre. Solo se puede llamar a esta rutina por puntero desde la dirección devuelta en una estructura de DMA_OPERATIONS. 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 y 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	Valor
cliente mínimo admitido	Disponible en Windows XP y versiones posteriores de Windows.
de la plataforma de destino de	Escritorio
encabezado de	wdm.h (incluya Wdm.h)
irQL	Cualquier nivel