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

Artículo
07/16/2024

La rutina buildScatterGatherListEx de asigna los recursos necesarios para una transferencia DMA, crea una lista de dispersión o recopilación y llama a la rutina de AdapterList Control proporcionada por el controlador para iniciar la transferencia DMA.

Cautela

No llame a esta rutina para un dispositivo DMA del sistema.

Sintaxis

PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;

NTSTATUS PbuildScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in]            PVOID ScatterGatherBuffer,
  [in]            ULONG ScatterGatherLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PVOID ScatterGatherList
)
{...}

Parámetros

[in] DmaAdapter

Puntero a una estructura de DMA_ADAPTER. Esta estructura es el objeto de adaptador que representa el dispositivo DMA maestro de bus del controlador o el canal DMA del sistema. El autor de la llamada obtuvo este puntero de una llamada anterior a la rutina IoGetDmaAdapter.

[in] DeviceObject

Puntero a una estructura DEVICE_OBJECT. Esta estructura es el objeto de dispositivo físico (PDO) que representa el dispositivo de destino para la operación DMA solicitada.

[in] DmaTransferContext

Puntero a un contexto de transferencia de DMA inicializado. Este contexto se inicializó mediante una llamada anterior a la rutina de InitializeDmaTransferContext. Este contexto debe ser único en todas las solicitudes de asignación de adaptadores. Para cancelar una solicitud de asignación pendiente, el autor de la llamada debe proporcionar el contexto de transferencia de DMA para la solicitud a la rutina CancelAdapterChannel .

[in] Mdl

Puntero a una cadena MDL que describe el diseño de página físico para una colección de búferes bloqueados en memoria virtual. La lista de dispersión y recopilación de la transferencia DMA usará la región de esta memoria especificada por el offset de y parámetros length. Para obtener más información sobre las cadenas MDL, consulte Uso de MDLs.

[in] Offset

Desplazamiento inicial de la transferencia de dispersión/recopilación de DMA. Este parámetro es un desplazamiento de bytes desde el inicio del búfer en la primera MDL de la cadena MDL. Si las MDL de la cadena MDL especifican un total de N bytes de espacio en búfer, los valores válidos de offset están en el intervalo de 0 a N-1.

[in] Length

Tamaño, en bytes, de la transferencia DMA. Si la cadena MDL especifica un total de N bytes de espacio de búfer, los valores válidos de Longitud están en el intervalo de 1 a N–Offset.

[in] Flags

Marcas de asignación del canal del adaptador. Se admite la marca siguiente:

Bandera	Significado
DMA_SYNCHRONOUS_CALLBACK	La rutina BuildScatterGatherListEx se denomina sincrónicamente. Si se establece esta marca y los recursos DMA necesarios no están disponibles inmediatamente, se produce un error en la llamada y se devuelve STATUS_INSUFFICIENT_RESOURCES.

Si se establece la marca DMA_SYNCHRONOUS_CALLBACK, el parámetro ExecutionRoutine es opcional y se puede NULL. Si no se establece esta marca, ExecutionRoutine debe ser un puntero NULL válido que no seaNULL. Para obtener más información sobre esta marca, vea la sección Comentarios.

[in, optional] ExecutionRoutine

Puntero a la rutina de AdapterListControl proporcionada por el controlador que inicia la transferencia DMA para el controlador. El administrador de E/S llama a la rutina de AdapterListControl después de asignar los recursos necesarios para el objeto de adaptador. Después de que se devuelva la rutina AdapterListControl de , el administrador de E/S libera automáticamente el objeto de adaptador y los recursos asignados para este objeto.

Si se establece la marca de DMA_SYNCHRONOUS_CALLBACK, ExecutionRoutine es opcional y se puede null. Si ExecutionRoutine es NULL, el autor de la llamada puede usar los recursos asignados por BuildScatterGatherListEx. Para obtener más información, vea la sección Comentarios.

[in, optional] Context

Contexto de control de adaptador determinado por el controlador. Este contexto se pasa a la rutina adapterListControl de como parámetro Context de .

[in] WriteToDevice

Dirección de la transferencia DMA. Establezca este parámetro en TRUE para una operación de escritura, que transfiere datos de la memoria al dispositivo. Establezca este parámetro en FALSE para una operación de lectura, que transfiere datos del dispositivo a la memoria.

[in] ScatterGatherBuffer

Puntero a un búfer asignado por el autor de la llamada en el que la rutina escribe la lista de dispersión/recopilación para la transferencia DMA. Esta lista comienza con una estructura SCATTER_GATHER_LIST, seguida de una matriz de SCATTER_GATHER_ELEMENT.

[in] ScatterGatherLength

Tamaño, en bytes, del búfer pasado en el parámetro ScatterGatherBuffer. El tamaño del búfer asignado debe ser lo suficientemente grande como para contener la lista de dispersión y recopilación, además de los datos internos que almacena el sistema operativo en este búfer. Para calcular el tamaño de búfer necesario, llame a la rutina de GetDmaTransferInfo o CalculateScatterGatherList.

[in, optional] DmaCompletionRoutine

No se usa. Establezca en null.

[in, optional] CompletionContext

No se usa. Establezca en null.

[out, optional] ScatterGatherList

Puntero a una variable en la que la rutina escribe un puntero a la lista de dispersión y recopilación para la transferencia DMA. Esta lista comienza con una estructura SCATTER_GATHER_LIST, que contiene un puntero a una matriz de SCATTER_GATHER_ELEMENT. Este puntero de salida siempre coincide con el valor del parámetro ScatterGatherBuffer.

Si se establece la marca de DMA_SYNCHRONOUS_CALLBACK y el parámetro executionRoutine es NULL , scatterGatherList debe ser un puntero NULL válido y no. Si executionRoutine no esNULL, ScatterGatherList es opcional y puede ser NULL si el controlador de llamada no requiere la lista de dispersión y recopilación. Se produce un error en la llamada BuildScatterGatherListEx si se establece la marca de DMA_SYNCHRONOUS_CALLBACK y ScatterGatherList y ExecutionRoutine son NULL, o si la marca DMA_SYNCHRONOUS_CALLBACK no está establecida y ExecutionRoutine es NULL.

Valor devuelto

buildScatterGatherListEx devuelve STATUS_SUCCESS si la llamada se realiza correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes códigos de estado.

Código devuelto	Descripción
STATUS_INVALID_PARAMETERS	Error en la rutina debido a valores de parámetro no válidos pasados por el autor de la llamada.
STATUS_BUFFER_TOO_SMALL	El búfer proporcionado por el autor de la llamada en ScatterGatherBuffer es demasiado pequeño para contener la lista de dispersión y recopilación.
STATUS_INSUFFICIENT_RESOURCES	La rutina no pudo asignar recursos necesarios para la transferencia DMA.

Observaciones

BuildScatterGatherListEx* no es una rutina del sistema a la que se puede llamar directamente por su nombre. Solo se puede llamar a esta rutina por puntero desde la dirección devuelta en una estructura*DMA_OPERATIONS. Los controladores obtienen la dirección de esta rutina llamando a IoGetDmaAdapter con el miembro Version de del parámetro deviceDescription establecido en DEVICE_DESCRIPTION_VERSION3. Si IoGetDmaAdapter devuelve null, la rutina no está disponible en la plataforma.

Use BuildScatterGatherListEx solo para adaptadores de bus-master. No use esta rutina para un adaptador DMA del sistema.

rutina buildScatterGatherListEx es similar a la rutina GetScatterGatherListEx , salvo que requiere que el autor de la llamada asigne el búfer para la lista de dispersión y recopilación.

Por ejemplo, un controlador puede preasignar uno o varios búferes de dispersión o recopilación durante la inicialización del dispositivo. Más adelante, una llamada BuildScatterGatherListEx que usa dicho búfer puede tener éxito en condiciones de disponibilidad de memoria baja que podrían provocar un error en una llamada a GetScatterGatherListEx .

De forma predeterminada, buildScatterGatherListEx devuelve de forma asincrónica, sin esperar a que se complete la asignación de recursos solicitada. Después de esta devolución, el autor de la llamada puede, si es necesario, cancelar la solicitud de asignación pendiente llamando a la rutina CancelAdapterChannel.

Si el controlador de llamada establece la marca DMA_SYNCHRONOUS_CALLBACK, la rutina BuildScatterGatherListEx se comporta de la siguiente manera:

Si los recursos solicitados no están disponibles inmediatamente, buildScatterGatherListEx no espera recursos, no crea una lista de dispersión o recopilación y no llama a la rutina adapterListControl de . En su lugar, error buildScatterGatherListEx y devuelve STATUS_INSUFFICIENT_RESOURCES.
El controlador no es necesario para proporcionar una rutina AdapterListControl si se establece la marca DMA_SYNCHRONOUS_CALLBACK.
Si el controlador proporciona una rutina de AdapterListControl, la marca DMA_SYNCHRONOUS_CALLBACK indica que se debe llamar a esta rutina en el contexto del subproceso de llamada, antes de buildScatterGatherListEx.
Si el controlador no proporciona una rutina de AdapterListControl, el controlador puede usar los recursos asignados y la lista de dispersión o recopilación después de BuildScatterGatherListEx. En este caso, el controlador debe proporcionar un punteroNULL válidoScatterGatherList. Además, una vez completada la transferencia DMA iniciada por el controlador, el controlador debe llamar a la rutina FreeAdapterObject para liberar los recursos que BuildScatterGatherListEx asignados para el objeto de adaptador.

BuildScatterGatherListEx es una versión extendida de la rutina de BuildScatterGatherList. En la lista siguiente se resumen las características que solo están disponibles en la versión extendida:

Característica	Descripción
Desplazamiento inicial	El controlador de llamada puede especificar un desplazamiento inicial para una transferencia DMA de dispersión o recopilación en lugar de iniciar la transferencia en la primera dirección del búfer al principio de la cadena MDL.
Cancelación de solicitudes de asignación	El controlador puede llamar a CancelAdapterChannel para cancelar una solicitud de asignación pendiente cuando el adaptador DMA está en cola para esperar a recursos DMA.
Devolución de llamada sincrónica	El controlador puede establecer la marca de DMA_SYNCHRONOUS_CALLBACK para solicitar que se llame a la rutina AdapterListControl proporcionada por el controlador en el subproceso de llamada, antes de que buildScatterGatherListEx.

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible a partir de Windows 8.
de la plataforma de destino de	Escritorio
encabezado de	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
irQL	DISPATCH_LEVEL