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

Artículo
03/08/2023

La rutina BuildScatterGatherListEx 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

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 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

Tamaño, 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 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 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 , ExecutionRoutine es opcional y puede ser 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 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] ScatterGatherBuffer

Puntero a un búfer asignado por el autor de la llamada en el que la rutina escribe la lista de dispersión y recopilación para la transferencia DMA. Esta lista comienza con una estructura de 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 GetDmaTransferInfo o CalculateScatterGatherList .

[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 y recopilación de la transferencia DMA. Esta lista comienza con una estructura de 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 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 BuildScatterGatherListEx 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

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 los recursos necesarios para la transferencia DMA.

Comentarios

BuildScatterGatherListEx* 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*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 BuildScatterGatherListEx solo para adaptadores de bus-master. No use esta rutina para un adaptador DMA del sistema.

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 o recopilación.

Por ejemplo, un controlador podría preasignar uno o varios búferes de dispersión o recopilación durante la inicialización del dispositivo. Más adelante, una llamada a BuildScatterGatherListEx que usa este búfer puede tener éxito en condiciones de baja disponibilidad de memoria 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 . En su lugar, BuildScatterGatherListEx 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 que realiza la llamada, antes de que BuildScatterGatherListEx 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 BuildScatterGatherListEx devuelva. En este caso, el controlador debe proporcionar un puntero ScatterGatherList válido que no sea NULL. 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 asignó para el objeto adaptador.

BuildScatterGatherListEx es una versión extendida de la rutina 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 los recursos de 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 devuelva.

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