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

Artículo
02/27/2024

La rutina GetScatterGatherList prepara el sistema para una operación de dispersión y recopilación de DMA en nombre del objeto de dispositivo de destino, ya sea mediante el controlador DMA del sistema o un adaptador de bus-master.

Sintaxis

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [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
)
{...}

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 en MdlAddress en el 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, que se va a asignar.

[in] ExecutionRoutine

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

[in] Context

Puntero al contexto determinado por el controlador que se pasa a la rutina AdapterListControl del controlador 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.

Valor devuelto

Esta rutina puede devolver uno de los siguientes valores NTSTATUS.

Código devuelto	Descripción
STATUS_SUCCESS	La operación se realizó correctamente.
STATUS_INSUFFICIENT_RESOURCES	La rutina no pudo asignar memoria suficiente o el número de registros de mapa necesarios para la transferencia es mayor que el valor devuelto por IoGetDmaAdapter.
STATUS_BUFFER_TOO_SMALL	El búfer es demasiado pequeño para la transferencia solicitada.

Comentarios

La rutina GetScatterGatherList asigna dinámicamente un búfer para contener la lista de dispersión y recopilación. Para ver los posibles valores NTSTATUS si se produce un error en la asignación del búfer, consulte el valor devuelto.

GetScatterGatherList no es una rutina del sistema que se puede llamar directamente por su nombre. Esta rutina solo se puede llamar por puntero de la dirección devuelta en una estructura de DMA_OPERATIONS . Los controladores obtienen la dirección de esta rutina llamando a IoGetDmaAdapter.

Tan pronto como esté disponible el canal DMA adecuado y los registros de mapa necesarios, GetScatterGatherList crea una lista de dispersión y recopilación, inicializa los registros de mapa y, a continuación, llama a la rutina AdapterListControl proporcionada por el controlador para llevar a cabo la operación de E/S.

GetScatterGatherList combina las acciones de las rutinas AllocateAdapterChannel y MapTransfer para los controladores que realizan la dispersión y recopilan DMA. GetScatterGatherList determina cuántos registros de mapa son necesarios para la transferencia, asigna los registros de mapa, asigna los búferes de DMA y rellena la lista de dispersión y recopilación. A continuación, llama a la rutina AdapterListControl proporcionada, pasando un puntero a la lista de dispersión y recopilación en ScatterGather. El controlador debe conservar este puntero para su uso al llamar a PutScatterGatherList. Tenga en cuenta que GetScatterGatherList no tiene las restricciones de puesta en cola que se aplican a AllocateAdapterChannel.

En su rutina AdapterListControl , el controlador debe realizar la E/S. Al volver de la rutina proporcionada por el controlador, GetScatterGatherList mantiene los registros del mapa, pero libera la estructura del adaptador DMA. El controlador debe llamar a PutScatterGatherList (que vacía los búferes) para poder acceder a los datos del búfer.

Esta rutina puede controlar los MDL encadenados, siempre que el número total de registros de mapa requeridos por todas las MDL encadenadas no supere el número de registros de mapa disponibles.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows 2000 y versiones posteriores de Windows. No se admite en Windows 98 o Windows Me.
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL
Reglas de cumplimiento de DDI	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)