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

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, a través del 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 de AdapterListControl proporcionada por el controlador, a la que se llama en 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 al AdapterListControl del controlador rutina cuando se llama a él.

[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 suficiente memoria 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.

Observaciones

El GetScatterGatherList asigna dinámicamente un búfer para contener la lista de dispersión y recopilación. Para ver 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 a la que se puede llamar directamente por 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 el canal DMA adecuado y los registros de mapa necesarios estén disponibles, GetScatterGatherList crea una lista de dispersión y recopilación, inicializa los registros de mapa y, a continuación, llama a la rutina de AdapterListControl proporcionada por el controlador para llevar a cabo la operación de E/S.

getScatterGatherList combina las acciones de la AllocateAdapterChannel y MapTransfer rutinas 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 de 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 de AdapterListControl, el controlador debe realizar la E/S. A cambio 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 Valor
cliente mínimo admitido Disponible en Windows 2000 y versiones posteriores de Windows. No se admite en Windows 98 o Windows Me.
de la plataforma de destino de Escritorio
encabezado de wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
irQL DISPATCH_LEVEL
reglas de cumplimiento de DDI IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)

Consulte también

AllocateAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

IoGetDmaAdapter

PutScatterGatherList

SCATTER_GATHER_LIST