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

Observaciones

Antes de llamar a esta rutina, un controlador debe inicializar 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 de 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. Se admite la versión 3 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 autor de la llamada 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 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 solicitados.

Para liberar el objeto de adaptador, el controlador debe llamar a PutDmaAdapter a través del puntero devuelto en la estructura DMA_ADAPTER .

Nota 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 confiar en este comportamiento para determinar si la rutina devuelve un puntero a la versión solicitada de la estructura de 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 de 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

   
Cliente mínimo compatible Disponible a partir de Windows 2000.
Plataforma de destino Universal
Encabezado wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL
Reglas de cumplimiento de DDI HwStorPortProhibitedDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)

Vea también

AddDevice

DEVICE_DESCRIPTION

DMA_ADAPTER

DMA_OPERATIONS

IRP_MN_START_DEVICE

PutDmaAdapter