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

Artículo
03/05/2024

La rutina BuildScatterGatherList prepara el sistema para una operación DMA, mediante un búfer proporcionado por el controlador para compilar la lista de dispersión y recopilación.

Sintaxis

PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;

NTSTATUS PbuildScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice,
  [in] PVOID ScatterGatherBuffer,
  [in] ULONG ScatterGatherLength
)
{...}

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

Puntero al objeto de dispositivo que representa el dispositivo de destino para la operación DMA.

[in] Mdl

Puntero al MDL que describe el búfer especificado por el miembro MdlAddress del IRP actual.

[in] CurrentVa

Puntero a la dirección virtual actual de MDL para que el búfer se asigne para una operación de transferencia DMA.

[in] Length

Especifica la longitud, en bytes, del búfer que se va a asignar.

[in] ExecutionRoutine

Puntero a una rutina AdapterListControl proporcionada por el controlador, que se llama en IRQL = DISPATCH_LEVEL cuando el controlador DMA del sistema o el adaptador de bus-master está disponible.

[in] Context

Puntero al contexto determinado por el controlador pasado a ExecutionRoutine cuando se llama a .

[in] WriteToDevice

Indica la dirección de la transferencia DMA: TRUE para una transferencia desde el búfer al dispositivo y FALSE de lo contrario.

[in] ScatterGatherBuffer

Puntero al búfer proporcionado por el autor de la llamada que la rutina rellena con una estructura de SCATTER_GATHER_LIST .

[in] ScatterGatherLength

Especifica el tamaño, en bytes, del búfer pasado en el parámetro ScatterGatherBuffer .

Valor devuelto

BuildScatterGatherList devuelve uno de los siguientes valores:

Código devuelto	Descripción
STATUS_SUCCESS	La operación se ha completado correctamente.
STATUS_INSUFFICIENT_RESOURCES	El sistema no tiene suficientes registros de mapa disponibles para la transferencia.
STATUS_BUFFER_TOO_SMALL	La longitud especificada es demasiado grande para caber dentro del búfer.

Comentarios

BuildScatterGatherList 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.

BuildScatterGatherList realiza la misma operación que GetScatterGatherList, salvo que usa el búfer proporcionado en el parámetro ScatterGatherBuffer para contener la lista de dispersión y recopilación que crea. En cambio, GetScatterGatherList asigna dinámicamente un búfer para contener la lista de dispersión y recopilación. Si no hay suficiente memoria disponible para asignar el búfer, GetScatterGatherList puede producir un error de STATUS_INSUFFICIENT_RESOURCES. Los controladores que deben evitar este escenario pueden asignar previamente un búfer para contener la lista de dispersión y recopilación, y usar BuildScatterGatherList en su lugar.

Un controlador puede usar la rutina CalculateScatterGatherList para determinar el tamaño del búfer que se va a asignar para contener la lista de dispersión y recopilación.

El controlador debe conservar el puntero a la lista de dispersión y recopilación en ScatterGatherBuffer para su uso cuando el controlador llama a PutScatterGatherList. El controlador debe llamar a PutScatterGatherList (que vacía la lista) para poder acceder a los datos de la lista.

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	DISPATCH_LEVEL
Reglas de cumplimiento de DDI	IrqlDispatch(wdm)