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

Artículo
02/27/2024

La rutina GetDmaTransferInfo calcula los requisitos de asignación de una transferencia DMA de dispersión o recopilación.

Sintaxis

PGET_DMA_TRANSFER_INFO PgetDmaTransferInfo;

NTSTATUS PgetDmaTransferInfo(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      ULONGLONG Offset,
  [in]      ULONG Length,
  [in]      BOOLEAN WriteOnly,
  [in, out] PDMA_TRANSFER_INFO TransferInfo
)
{...}

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 .

[in] Mdl

Puntero a la cadena MDL que describe las páginas de memoria que se van a transferir. Para obtener más información, vea la sección Comentarios.

[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 de 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 de búfer, los valores válidos de Length se encuentran en el intervalo de 1 a N-Offset.

[in] WriteOnly

Indica si la transferencia es una operación de solo escritura (es decir, una transferencia al dispositivo desde la memoria). Si WriteOnly es TRUE, es posible que la información devuelta sobre la transferencia no sea válida para una transacción de lectura. Este parámetro puede indicar que se requieren operaciones de control de caché adicionales en los límites del búfer para aplicar la coherencia de caché.

[in, out] TransferInfo

Puntero a una estructura de DMA_TRANSFER_INFO asignada por el autor de la llamada. El llamador debe establecer el miembro Version de la estructura en DMA_TRANSFER_INFO_VERSION1 antes de llamar a GetDmaTransferInfo.

Valor devuelto

GetDmaTransferInfo 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_NOT_SUPPORTED	La rutina no admite la versión especificada de la estructura DMA_TRANSFER_INFO_XXX .

Comentarios

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

Use GetDmaTransferInfo para calcular el tamaño del búfer de dispersión y recopilación que se asignará a las rutinas BuildScatterGatherListEx y MapTransferEx .

GetDmaTransferInfo reemplaza la rutina CalculateScatterGatherList y es más conveniente usar con BuildScatterGatherListEx.

Los parámetros Mdl, Offset y Length especifican juntos una colección de regiones de memoria física que se usarán como búfer para una transferencia DMA de dispersión o recopilación. Cada región de memoria física suele ser una página o parte de una página. GetDmaTransferInfo determina los requisitos de asignación para esta transferencia. Entre estos requisitos se incluyen los siguientes:

Número de elementos de la lista de dispersión y recopilación. Cada elemento es una estructura SCATTER_GATHER_ELEMENT que describe un bloque de memoria físicamente contiguo.
Cantidad de memoria que se va a asignar para contener la lista de dispersión o recopilación especificada. (Esta asignación de memoria incluye el espacio necesario para la lista de dispersión y recopilación que describe el búfer de E/S, pero no para el propio búfer de E/S).
Número de registros de mapa necesarios para traducir las direcciones físicas de la lista de dispersión y recopilación a direcciones lógicas.

Para obtener información sobre la información de transferencia de DMA proporcionada por la versión 1 de la estructura DMA_TRANSFER_INFO_XXX , vea DMA_TRANSFER_INFO_V1.

Un MDL describe las páginas de memoria física que subyacen a un bloque contiguo bloqueado de memoria virtual. Normalmente, estas páginas de memoria física no son contiguas. Una cadena MDL es una colección ordenada de MDL que describe la memoria que se puede usar para almacenar en búfer los datos de E/S. Normalmente, las regiones de memoria virtual descritas por las MDL de la cadena no son contiguas. Para obtener más información sobre los MDL y las cadenas MDL, consulte Uso de MDL.

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