Función IoGetDmaAdapter (wdm.h)
La rutina IoGetDmaAdapter devuelve un puntero a la estructura del adaptador DMA para un objeto de dispositivo físico.
Sintaxis
_DMA_ADAPTER * IoGetDmaAdapter(
[in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
[in] _DEVICE_DESCRIPTION *DeviceDescription,
[out] PULONG NumberOfMapRegisters
);
Parámetros
[in, optional] PhysicalDeviceObject
Puntero al objeto de dispositivo físico para el dispositivo que solicita la estructura del adaptador DMA.
[in] DeviceDescription
Puntero a una estructura DEVICE_DESCRIPTION , que describe los atributos del dispositivo físico. Independientemente de la versión establecida en la estructura DEVICE_DESCRIPTION, esta función siempre devuelve DMA_ADAPTER->Version == 1.
[out] NumberOfMapRegisters
Puntero a, en la salida, el número máximo de registros de mapa que el controlador puede asignar para cualquier operación de transferencia de DMA.
Valor devuelto
IoGetDmaAdapter devuelve un puntero a una estructura de DMA_ADAPTER , que contiene punteros a funciones que admiten operaciones DMA definidas por el sistema. Si no se puede asignar la estructura, la rutina devuelve NULL. Consulte el comentario de versión anterior en descripción del parámetro DeviceDescription .
Comentarios
Antes de llamar a esta rutina, un controlador debe inicializar sin cero la estructura de DEVICE_DESCRIPTION a la que apunta DeviceDescription y, a continuación, agregar la información pertinente para su dispositivo a esta estructura.
Si se ejecuta correctamente, el valor devuelto de la rutina apunta a una estructura DMA_ADAPTER . Esta estructura contiene un puntero a una estructura de DMA_OPERATIONS , que es una tabla de punteros a funciones que el controlador puede usar posteriormente para realizar operaciones DMA. La versión de esta estructura que devuelve la rutina se determina de la siguiente manera:
Si el controlador establece el miembro Version de la estructura de DEVICE_DESCRIPTION en DEVICE_DESCRIPTION_VERSION o DEVICE_DESCRIPTION_VERSION1, la estructura de DMA_ADAPTER devuelta apunta a la versión 1 de la estructura de DMA_OPERATIONS .
Si el controlador establece Version = DEVICE_DESCRIPTION_VERSION2, la estructura de DMA_ADAPTER devuelta apunta a la versión 2 de la estructura de DMA_OPERATIONS si se admite la versión 2; de lo contrario, la rutina devuelve NULL. Los controladores deben comprobar si se admite la versión 2 antes de intentar usar cualquier función de la versión 2.
Si el controlador establece Version = DEVICE_DESCRIPTION_VERSION3, la estructura de DMA_ADAPTER devuelta apunta a la versión 3 de la estructura de DMA_OPERATIONS si se admite la versión 3; de lo contrario, la rutina devuelve NULL. Los controladores deben comprobar si se admite la versión 3 antes de intentar usar cualquier función de la versión 3. La versión 3 se admite a partir de Windows 8.
Un controlador PnP llama a IoGetDmaAdapter cuando se llama a su rutina AddDevice o cuando controla una solicitud de IRP_MN_START_DEVICE PnP para un dispositivo. Este IRP incluye información sobre los recursos de hardware del dispositivo que el controlador debe proporcionar en la estructura DeviceDescription .
El llamador usa el miembro MaximumLength en la estructura DeviceDescription para indicar el número óptimo de registros de mapa que puede usar. El administrador de E/S intentará asignar suficientes registros de mapa para dar cabida a una operación de transferencia de DMA de este tamaño máximo. En la salida, el administrador de E/S devuelve, en el parámetro NumberOfMapRegisters , el número de registros de mapa que asigna. Los controladores deben comprobar el valor devuelto; no hay ninguna garantía de que un controlador recibirá el mismo número de registros de mapa que solicitó.
Para liberar el objeto de adaptador, el controlador debe llamar a PutDmaAdapter a través del puntero devuelto en la estructura DMA_ADAPTER .
Como se ha descrito anteriormente, IoGetDmaAdapter devuelve NULL si no admite la versión de la estructura de DMA_ADAPTER especificada por DeviceDescription-Version>. Los autores de llamadas deben basarse en este comportamiento para determinar si la rutina devuelve un puntero a la versión solicitada de la estructura DMA_ADAPTER . Cuando IoGetDmaAdapter devuelve un puntero a la versión 1 o la versión 2 o la versión 3 de la estructura DMA_ADAPTER , el miembro Version de esta estructura siempre se establece en 1. Por lo tanto, el autor de la llamada no puede usar el miembro Version de la estructura de DMA_ADAPTER devuelta para distinguir entre las versiones 1, 2 y 3 de esta estructura.
Requisitos
| Requisito | Value |
|---|---|
| Plataforma de destino | Universal |
| Encabezado | wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Reglas de cumplimiento de DDI | HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |