PBUILD_SCATTER_GATHER_LIST función de devolución de llamada (wdm.h)
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) |