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

Artículo
03/08/2023

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

Precaución

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

Sintaxis

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [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, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *ScatterGatherList
)
{...}

Parámetros

[in] DmaAdapter

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

[in] DeviceObject

Puntero a una estructura de 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 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 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 los parámetros Offset y Length . Para obtener más información sobre las cadenas MDL, consulte Uso de MDL.

[in] Offset

Desplazamiento inicial de la transferencia DMA de dispersión o recopilación. 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 se encuentran en el intervalo de 0 a N-1.

[in] Length

Longitud, en bytes, de la transferencia DMA. Si la cadena MDL especifica un total de N bytes de espacio en búfer, los valores válidos de Length se encuentran en el intervalo de 1 a N-Offset.

[in] Flags

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

Marca	Significado
DMA_SYNCHRONOUS_CALLBACK	La rutina GetScatterGatherListEx 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 puede ser NULL. Si no se establece esta marca, ExecutionRoutine debe ser un puntero válido que no sea NULL . Para obtener más información sobre esta marca, vea la sección Comentarios.

[in, optional] ExecutionRoutine

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

Si se establece la marca DMA_SYNCHRONOUS_CALLBACK , el parámetro ExecutionRoutine es opcional y puede ser NULL. Si este parámetro es NULL, el autor de la llamada puede usar los recursos asignados por GetScatterGatherListEx para realizar la transferencia DMA después de que GetScatterGatherListEx devuelva. 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 como parámetro Context .

[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, optional] DmaCompletionRoutine

No se usa. Se establece en NULL.

[in, optional] CompletionContext

No se usa. Se establece en NULL.

[out, optional] ScatterGatherList

Puntero a una variable en la que la rutina escribe un puntero en la lista de dispersión o recopilación asignada. Este parámetro apunta a una estructura de SCATTER_GATHER_LIST . La rutina asigna esta estructura y la matriz SCATTER_GATHER_ELEMENT a la que apunta.

El parámetro ScatterGatherList es opcional y puede ser NULL si el parámetro ExecutionRoutine no es NULL.

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

Valor devuelto

GetScatterGatherListEx devuelve STATUS_SUCCESS si la llamada es correcta. 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_INSUFFICIENT_RESOURCES	La rutina no pudo asignar los recursos necesarios para la transferencia DMA.

Comentarios

GetScatterGatherListEx no es una rutina del sistema que se puede llamar directamente por su 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_VERSION3. Si IoGetDmaAdapter devuelve NULL, la rutina no está disponible en la plataforma.

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

El controlador de un dispositivo bus-master puede usar GetScatterGatherListEx para combinar las operaciones realizadas por las rutinas AllocateAdapterChannelEx y MapTransferEx en una sola llamada. GetScatterGatherListEx realiza las siguientes operaciones:

Asigna los recursos necesarios para la transferencia DMA.
Crea una lista de dispersión o recopilación basada en los valores de los parámetros Mdl, Offset y Length .
Llama a la rutina AdapterListControl proporcionada por el controlador y proporciona la lista de dispersión y recopilación a esta rutina como parámetro.

Los recursos asignados se liberan automáticamente después de que se devuelva la rutina AdapterListControl . Si Se llama a GetScatterGatherListEx de forma sincrónica (es decir, si se establece la marca DMA_SYNCHRONOUS_CALLBACK ), se puede omitir la rutina AdapterListControl . En este caso, el autor de la llamada usa los recursos asignados para iniciar la transferencia DMA después de que GetScatterGatherListEx devuelva. El autor de la llamada debe liberar explícitamente estos recursos.

De forma predeterminada, GetScatterGatherListEx 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 GetScatterGatherListEx se comporta de la siguiente manera:

Si los recursos solicitados no están disponibles inmediatamente, GetScatterGatherListEx no espera recursos, no crea una lista de dispersión o recopilación y no llama a la rutina AdapterListControl . En su lugar, GetScatterGatherListEx produce un error 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 AdapterListControl , la marca DMA_SYNCHRONOUS_CALLBACK indica que se va a llamar a esta rutina en el contexto del subproceso de llamada, antes de que GetScatterGatherListEx devuelva.
Si el controlador no proporciona una rutina AdapterListControl , el controlador puede usar los recursos asignados y la lista de dispersión y recopilación después de que GetScatterGatherListEx devuelva. En este caso, el controlador debe proporcionar un puntero ScatterGatherList válido que no sea NULL. Además, después de que el controlador inicie la transferencia DMA, el controlador debe llamar a la rutina FreeAdapterObject para liberar los recursos que GetScatterGatherListEx asignó para el objeto de adaptador.

GetScatterGatherListEx es una versión extendida de la rutina GetScatterGatherList . Las siguientes características solo están disponibles en la versión extendida:

GetScatterGatherListEx es similar a la rutina BuildScatterGatherListEx , excepto que GetScatterGatherListEx asigna automáticamente el búfer para la lista de dispersión y recopilación.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 8.
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL