estructura DEVICE_DESCRIPTION (wdm.h)
La estructura de DEVICE_DESCRIPTION describe los atributos del dispositivo físico para el que un controlador solicita un adaptador DMA.
Sintaxis
typedef struct _DEVICE_DESCRIPTION {
ULONG Version;
BOOLEAN Master;
BOOLEAN ScatterGather;
BOOLEAN DemandMode;
BOOLEAN AutoInitialize;
BOOLEAN Dma32BitAddresses;
BOOLEAN IgnoreCount;
BOOLEAN Reserved1;
BOOLEAN Dma64BitAddresses;
ULONG BusNumber;
ULONG DmaChannel;
INTERFACE_TYPE InterfaceType;
DMA_WIDTH DmaWidth;
DMA_SPEED DmaSpeed;
ULONG MaximumLength;
ULONG DmaPort;
ULONG DmaAddressWidth;
ULONG DmaControllerInstance;
ULONG DmaRequestLine;
PHYSICAL_ADDRESS DeviceAddress;
} DEVICE_DESCRIPTION, *PDEVICE_DESCRIPTION;
Miembros
Version
Versión de esta estructura. El miembro Version de la estructura DEVICE_DESCRIPTION que se pasa a la rutina IoGetDmaAdapter determina qué versión de la estructura de DMA_ADAPTER devuelve esta rutina. A continuación se muestra una lista de los posibles valores del miembro Version y las versiones de DMA_ADAPTER correspondientes:
DEVICE_DESCRIPTION_VERSION
Si Version = DEVICE_DESCRIPTION_VERSION, IoGetDmaAdapter omite el miembro IgnoreCount y devuelve la versión 1 de la estructura de DMA_ADAPTER .
DEVICE_DESCRIPTION_VERSION1
Si Version = DEVICE_DESCRIPTION_VERSION1, IoGetDmaAdapter usa el miembro IgnoreCount y devuelve la versión 1 de la estructura de DMA_ADAPTER .
DEVICE_DESCRIPTION_VERSION2
Si Version = DEVICE_DESCRIPTION_VERSION2, IoGetDmaAdapter usa el miembro IgnoreCount y devuelve la versión 2 de la estructura de DMA_ADAPTER . La versión 2 está disponible a partir de Windows XP.
DEVICE_DESCRIPTION_VERSION3
Si Version = DEVICE_DESCRIPTION_VERSION3, IoGetDmaAdapter usa el miembro IgnoreCount y devuelve la versión 3 de la estructura de DMA_ADAPTER . La versión 3 está disponible a partir de Windows 8.
Master
Si el dispositivo es un dispositivo DMA maestro de bus. Se establece en TRUE si el dispositivo es un dispositivo DMA maestro de bus. Se establece en FALSE si es un dispositivo DMA subordinado.
ScatterGather
En el caso de un dispositivo DMA de bus-master, este miembro indica si el dispositivo admite dispersión o recopilación de DMA. Establézcalo en TRUE si el dispositivo puede realizar la dispersión o recopilación de DMA. De lo contrario, establezca este miembro en FALSE.
En el caso de un dispositivo DMA subordinado, no se usa el valor de ScatterGather . En su lugar, IoGetDmaAdapter asume que la funcionalidad de dispersión y recopilación de un dispositivo DMA subordinado es la misma que la del controlador DMA del sistema subyacente al que está conectado el dispositivo.
DemandMode
Este miembro solo se usa si version es DEVICE_DESCRIPTION_VERSION2.
En el caso de un dispositivo DMA subordinado, este miembro indica si se debe usar el modo de demanda del controlador DMA del sistema. Establézcalo en TRUE para usar el modo de demanda. De lo contrario, establezca este miembro en FALSE.
En el caso de un dispositivo DMA maestro de bus, no se usa el valor DemandMode .
Si Version es DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 o DEVICE_DESCRIPTION_VERSION3, no se usa el valor DemandMode .
AutoInitialize
En el caso de un dispositivo DMA subordinado, este miembro indica si se debe usar el modo de inicialización automática del controlador DMA del sistema. Establezca en TRUE para usar el modo autoinicializar. De lo contrario, establezca este miembro en FALSE.
En el caso de un dispositivo DMA maestro de bus, no se usa el valor AutoInitialize .
Dma32BitAddresses
Este miembro solo se usa si Version es DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 o DEVICE_DESCRIPTION_VERSION2.
Dma32BitAddresses especifica si el dispositivo puede usar direcciones completas de 32 bits para las operaciones DMA. Se establece en TRUE si el dispositivo admite direcciones de 32 bits. De lo contrario, establezca este miembro en FALSE.
Si Version = DEVICE_DESCRIPTION_VERSION3, no se usa el valor Dma32BitAddresses .
IgnoreCount
Si se omite el contador de transferencia del controlador DMA. Se establece en TRUE si el controlador DMA de esta plataforma no mantiene un contador de transferencia preciso y, por tanto, requiere una solución alternativa. De lo contrario, establezca este miembro en FALSE.
Si Version = DEVICE_DESCRIPTION_VERSION, no se usa el valor IgnoreCount .
Para obtener más información, vea la sección Comentarios.
Reserved1
Reservado para uso del sistema. Debe ser FALSE.
Dma64BitAddresses
Este miembro solo se usa si Version es DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 o DEVICE_DESCRIPTION_VERSION2.
Dma64BitAddresses especifica si el dispositivo puede usar direcciones completas de 64 bits para las operaciones DMA. Se establece en TRUE si el dispositivo admite direcciones de 64 bits. De lo contrario, establezca este miembro en FALSE.
Si Version = DEVICE_DESCRIPTION_VERSION3, no se usa el valor Dma64BitAddresses .
BusNumber
Número de bus asignado por el sistema para el bus de E/S. Los controladores WDM no usan este miembro.
DmaChannel
Número del canal DMA al que se asigna un dispositivo subordinado. El controlador de dispositivo obtiene este número de canal de la lista de recursos que recibe en la solicitud de IRP_MN_START_DEVICE que inicia el dispositivo. Para obtener más información sobre este número, vea la descripción del miembro Dma.Channel en CM_PARTIAL_RESOURCE_DESCRIPTOR.
InterfaceType
Tipo de interfaz del bus de E/S que se va a usar para DMA. Establezca este miembro en el valor de enumeración INTERFACE_TYPE que indica el tipo de interfaz. Para obtener más información, vea la sección Comentarios.
DmaWidth
Para un dispositivo DMA subordinado, este miembro especifica el ancho de datos DMA para las transferencias por parte del controlador DMA del sistema. Los valores posibles son Width8Bits, Width16Bits, Width32Bits y Width64Bits.
En el caso de un dispositivo DMA maestro de bus, no se usa el valor DmaWidth .
DmaSpeed
Este miembro solo se usa si Version es DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 o DEVICE_DESCRIPTION_VERSION2.
Para un dispositivo DMA subordinado, este miembro especifica una de las siguientes velocidades para el sistema DMA: Compatible, TypeA, TypeB, TypeC o TypeF.
En el caso de un dispositivo DMA maestro de bus, no se usa el valor DmaSpeed .
Si Version = DEVICE_DESCRIPTION_VERSION3, no se usa el valor DmaSpeed .
MaximumLength
El número máximo de bytes que el dispositivo puede transferir en una operación DMA que usa el objeto de adaptador asignado.
DmaPort
Número de puerto de bus de tipo Microchannel. Este parámetro está obsoleto, pero se conserva en la estructura para la compatibilidad con los controladores heredados.
DmaAddressWidth
Este miembro solo se usa si Version = DEVICE_DESCRIPTION_VERSION3.
Para un dispositivo DMA de bus-master, DmaAddressWidth especifica el ancho, en bits, de una dirección DMA. El valor DmaAddressWidth debe ser distinto de cero y no debe superar los 64. Si el ancho de la dirección de memoria es mayor que el ancho de la dirección DMA, se requieren registros de asignación para acceder a una región de memoria que está fuera del alcance de la dirección del controlador DMA.
En el caso de un dispositivo DMA subordinado, no se usa el valor DmaAddressWidth . En su lugar, IoGetDmaAdapter asume que el ancho de dirección de un dispositivo DMA subordinado es el mismo que el del controlador DMA del sistema subyacente al que está conectado el dispositivo.
DmaControllerInstance
No se usa.
DmaRequestLine
Este miembro solo se usa si Version = DEVICE_DESCRIPTION_VERSION3.
Para un dispositivo DMA subordinado, DmaRequestLine especifica la línea de solicitud en el controlador DMA al que está conectado el dispositivo. El controlador de dispositivo obtiene el número de esta línea de solicitud de la lista de recursos que recibe en la solicitud IRP_MN_START_DEVICE que inicia el dispositivo. Para obtener más información sobre el número de línea de solicitud, vea la descripción del miembro u.DmaV3.RequestLine en CM_PARTIAL_RESOURCE_DESCRIPTOR.
En el caso de un dispositivo DMA maestro de bus, no se usa el valor DmaRequestLine .
DeviceAddress
Este miembro solo se usa si Version = DEVICE_DESCRIPTION_VERSION3.
En el caso de un dispositivo DMA subordinado, DeviceAddress es la dirección asignada a la memoria del registro de datos en el dispositivo que se usa como origen o destino para una transferencia DMA. Este registro de datos se encuentra en un desplazamiento conocido específico del dispositivo desde la dirección de inicio del dispositivo. El miembro DmaWidth especifica el ancho de este registro. El controlador de dispositivo obtiene la dirección de inicio del dispositivo de la lista de recursos que recibe en la solicitud IRP_MN_START_DEVICE que inicia el dispositivo. Para obtener más información sobre esta dirección, vea la descripción del miembro u.Memory.Start en CM_PARTIAL_RESOURCE_DESCRIPTOR.
En el caso de un dispositivo DMA maestro de bus, no se usa el miembro DeviceAddress .
Comentarios
El controlador de un dispositivo que usa DMA para transferir datos usa la estructura DEVICE_DESCRIPTION para pasar información sobre el dispositivo a la rutina IoGetDmaAdapter . El controlador llama a esta rutina para solicitar un objeto de adaptador para un objeto de dispositivo físico (PDO). Este PDO representa la conexión física del dispositivo al bus de E/S que se va a usar para DMA. Para obtener más información, vea Obtener un objeto de adaptador.
Para asignar recursos para un controlador DMA, el administrador de E/S necesita información sobre el controlador, pero solo puede obtener parte de esta información de un controlador. Por ejemplo, el controlador de un dispositivo bus-master sabe si el dispositivo admite DMA de dispersión o recopilación o usa direcciones completas de 32 bits. O bien, el controlador de un dispositivo subordinado puede determinar el número de canal DMA de la lista de recursos que recibe el controlador en la solicitud de IRP_MN_START_DEVICE que inicia el dispositivo. El controlador usa la estructura DEVICE_DESCRIPTION para pasar esta información al administrador de E/S.
Antes de llamar a IoGetDmaAdapter, el controlador debe inicializar primero la estructura de DEVICE_DESCRIPTION completa y, a continuación, rellenar los miembros seleccionados para describir el dispositivo.
El miembro InterfaceType especifica el tipo de interfaz de bus que se usará para DMA. Si establece InterfaceType en InterfaceTypeUndefined, IoGetDmaAdapter consulta el PDO para determinar el tipo de interfaz correcto para el dispositivo. O bien, puede especificar un tipo de interfaz explícito, como Internal, Isa, Eisa o PCIBus. Para obtener más información, consulte la lista de tipos de interfaz admitidos en INTERFACE_TYPE.
Si el miembro ScatterGather se establece en TRUE y el miembro InterfaceType se establece en PCIBus, el miembro Dma32BitAddresses se omite y IoGetDmaAdapter asume que el dispositivo admite direcciones DMA de 32 bits.
Si el miembro Dma64BitAddresses se establece en TRUE, el miembro Dma32BitAddresses se omite y IoGetDmaAdapter asume que el dispositivo admite direcciones DMA de 64 bits.
Para indicar que el hardware del controlador DMA no puede mantener de forma confiable un recuento de transferencia preciso, establezca IgnoreCount en TRUE y establezca Version en un valor distinto de DEVICE_DESCRIPTION_VERSION. En una plataforma que tiene un controlador DMA de este tipo, el sistema operativo omite el contador de transferencia de DMA, pero debe tomar precauciones especiales para mantener la integridad de los datos durante las operaciones de DMA. Normalmente, el uso de una solución alternativa para compensar un controlador DMA deficiente degrada la velocidad de las transferencias DMA.
Un controlador debe especificar TypeF como el valor DmaSpeed solo si el firmware ACPI del equipo lo admite.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Se admite a partir de Windows 2000. |
| Encabezado | wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h) |