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

Artículo
02/27/2024

La rutina InitializeDmaTransferContext inicializa un contexto de transferencia DMA opaco que se usa para realizar un seguimiento de las asignaciones pendientes de los recursos DMA.

Sintaxis

PINITIALIZE_DMA_TRANSFER_CONTEXT PinitializeDmaTransferContext;

NTSTATUS PinitializeDmaTransferContext(
  [in]  PDMA_ADAPTER DmaAdapter,
  [out] PVOID DmaTransferContext
)
{...}

Parámetros

[in] DmaAdapter

Puntero a una estructura 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 .

[out] DmaTransferContext

Puntero a un búfer asignado por el autor de la llamada en el que InitializeDmaTransferContext escribe los valores iniciales para el contexto de transferencia de DMA. Este contexto es opaco para el autor de la llamada. El autor de la llamada debe asignar un búfer lo suficientemente grande como para contener el contexto de transferencia de DMA. El tamaño, en bytes, de este contexto se especifica mediante la constante DMA_TRANSFER_CONTEXT_SIZE_V1 en el archivo de encabezado Wdm.h.

Valor devuelto

InitializeDmaTransferContext 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	No se pudo realizar esta rutina debido a valores de parámetros no válidos pasados por el autor de la llamada.

Comentarios

InitializeDmaTransferContext 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_VERSION3. Si IoGetDmaAdapter devuelve NULL, la rutina no está disponible en la plataforma.

Se debe proporcionar un contexto de transferencia DMA inicializado como parámetro a la rutina AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx . Cada una de estas rutinas escribe información sobre la asignación de recursos DMA solicitada en el contexto de transferencia de DMA. Esta información es opaca para el autor de la llamada. 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 .

El contexto de transferencia de DMA que se proporciona a AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx debe ser único en todas las solicitudes de asignación del adaptador.

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