структура DEVICE_DESCRIPTION (wdm.h)
Структура DEVICE_DESCRIPTION описывает атрибуты физического устройства, для которого драйвер запрашивает адаптер DMA.
Синтаксис
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;
Члены
Version
Версия этой структуры. Элемент Version структуры DEVICE_DESCRIPTION , передаваемой в подпрограмму IoGetDmaAdapter , определяет, какая версия структуры DMA_ADAPTER возвращается этой подпрограммой. Ниже приведен список возможных значений элемента Version и соответствующих версий DMA_ADAPTER :
DEVICE_DESCRIPTION_VERSION
Если версия = DEVICE_DESCRIPTION_VERSION, IoGetDmaAdapter игнорирует элемент IgnoreCount и возвращает версию 1 структуры DMA_ADAPTER .
DEVICE_DESCRIPTION_VERSION1
Если версия = DEVICE_DESCRIPTION_VERSION1, IoGetDmaAdapter использует элемент IgnoreCount и возвращает версию 1 структуры DMA_ADAPTER .
DEVICE_DESCRIPTION_VERSION2
Если версия = DEVICE_DESCRIPTION_VERSION2, IoGetDmaAdapter использует элемент IgnoreCount и возвращает версию 2 структуры DMA_ADAPTER . Версия 2 доступна начиная с Windows XP.
DEVICE_DESCRIPTION_VERSION3
Если версия = DEVICE_DESCRIPTION_VERSION3, IoGetDmaAdapter использует элемент IgnoreCount и возвращает версию 3 структуры DMA_ADAPTER . Версия 3 доступна начиная с Windows 8.
Master
Указывает, является ли устройство master шиной DMA. Задайте значение TRUE, если устройство является устройством DMA master шины. Установите значение FALSE , если это подчиненное устройство DMA.
ScatterGather
Для устройства DMA master шины этот элемент указывает, поддерживает ли устройство точечную и сборную DMA. Установите значение TRUE , если устройство может выполнять точечную или сборную DMA. В противном случае задайте для этого элемента значение FALSE.
Для подчиненного устройства DMA значение ScatterGather не используется. Вместо этого IoGetDmaAdapter предполагает, что возможности точечной и сборной подчиненного устройства DMA совпадают с возможностями базового контроллера DMA системы, к которому подключено устройство.
DemandMode
Этот элемент используется только в том случае , если версия DEVICE_DESCRIPTION_VERSION2.
Для подчиненного устройства DMA этот элемент указывает, следует ли использовать режим требований контроллера DMA системы. Установите значение TRUE , чтобы использовать режим спроса. В противном случае задайте для этого элемента значение FALSE.
Для устройства DMA master шины значение DemandMode не используется.
Если версия имеет значение DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 или DEVICE_DESCRIPTION_VERSION3, значение DemandMode не используется.
AutoInitialize
Для подчиненного устройства DMA этот элемент указывает, следует ли использовать режим автоматической инициализации контроллера DMA системы. Установите значение TRUE , чтобы использовать режим автоматической инициализации. В противном случае задайте для этого элемента значение FALSE.
Для устройства DMA master шины значение AutoInitialize не используется.
Dma32BitAddresses
Этот элемент используется, только если версия DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 или DEVICE_DESCRIPTION_VERSION2.
Dma32BitAddresses указывает, может ли устройство использовать полные 32-разрядные адреса для операций DMA. Установите значение TRUE , если устройство поддерживает 32-разрядные адреса. В противном случае задайте для этого элемента значение FALSE.
Если Version = DEVICE_DESCRIPTION_VERSION3, значение Dma32BitAddresses не используется.
IgnoreCount
Следует ли игнорировать счетчик передачи контроллера DMA. Установите значение TRUE , если контроллер DMA на этой платформе не поддерживает точный счетчик передачи и поэтому требует обходного решения. В противном случае задайте для этого элемента значение FALSE.
Если Version = DEVICE_DESCRIPTION_VERSION, значение IgnoreCount не используется.
Дополнительные сведения см. в разделе «Примечания».
Reserved1
Зарезервировано для системного использования. Должно иметь значение FALSE.
Dma64BitAddresses
Этот элемент используется, только если версия DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 или DEVICE_DESCRIPTION_VERSION2.
Dma64BitAddresses указывает, может ли устройство использовать полные 64-разрядные адреса для операций DMA. Установите значение TRUE , если устройство поддерживает 64-разрядные адреса. В противном случае задайте для этого элемента значение FALSE.
Если Version = DEVICE_DESCRIPTION_VERSION3, значение Dma64BitAddresses не используется.
BusNumber
Номер автобуса, назначаемого системой, для шины ввода-вывода. Этот элемент не используется драйверами WDM.
DmaChannel
Номер канала DMA, которому назначено подчиненное устройство. Драйвер устройства получает этот номер канала из списка ресурсов, полученного в запросе IRP_MN_START_DEVICE , который запускает устройство. Дополнительные сведения об этом номере см. в описании члена Dma.Channel в CM_PARTIAL_RESOURCE_DESCRIPTOR.
InterfaceType
Тип интерфейса шины ввода-вывода, используемой для DMA. Присвойте этому элементу значение перечисления INTERFACE_TYPE , указывающее тип интерфейса. Дополнительные сведения см. в разделе «Примечания».
DmaWidth
Для подчиненного устройства DMA этот элемент задает ширину данных DMA для передачи системным контроллером DMA. Возможные значения : Width8Bits, Width16Bits, Width32Bits и Width64Bits.
Для устройства DMA master шины значение DmaWidth не используется.
DmaSpeed
Этот элемент используется, только если версия DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 или DEVICE_DESCRIPTION_VERSION2.
Для подчиненного устройства DMA этот элемент определяет одну из следующих скоростей для системного DMA: Compatible, TypeA, TypeB, TypeC или TypeF.
Для устройства DMA master шины значение DmaSpeed не используется.
Если Version = DEVICE_DESCRIPTION_VERSION3, значение DmaSpeed не используется.
MaximumLength
Максимальное число байтов, которое устройство может передать в операции DMA, которая использует выделенный объект адаптера.
DmaPort
Номер порта шины типа Microchannel. Этот параметр устарел, но сохраняется в структуре для обеспечения совместимости с устаревшими драйверами.
DmaAddressWidth
Этот элемент используется только в том случае , если Version = DEVICE_DESCRIPTION_VERSION3.
Для устройства DMA с master шиной DMA DmaAddressWidth задает ширину адреса DMA в битах. Значение DmaAddressWidth должно быть ненулевым и не должно превышать 64. Если ширина адреса памяти больше ширины адреса DMA, регистры карт требуются для доступа к области памяти, которая находится за пределами адреса контроллера DMA.
Для подчиненного устройства DMA значение DmaAddressWidth не используется. Вместо этого IoGetDmaAdapter предполагает, что ширина адреса подчиненного устройства DMA совпадает с шириной адреса базового контроллера DMA системы, к которому подключено устройство.
DmaControllerInstance
Не используется.
DmaRequestLine
Этот элемент используется только в том случае , если Version = DEVICE_DESCRIPTION_VERSION3.
Для подчиненного устройства DMA DMA DmaRequestLine указывает строку запроса на контроллере DMA, к которому подключено устройство. Драйвер устройства получает номер строки запроса из списка ресурсов, который он получает в запросе IRP_MN_START_DEVICE , который запускает устройство. Дополнительные сведения о номере строки запроса см. в описании элемента u.DmaV3.RequestLine в CM_PARTIAL_RESOURCE_DESCRIPTOR.
Для устройства DMA с master шиной значение DmaRequestLine не используется.
DeviceAddress
Этот элемент используется только в том случае , если Version = DEVICE_DESCRIPTION_VERSION3.
Для подчиненного устройства DMA DeviceAddress — это сопоставленный в памяти адрес регистра данных на устройстве, который используется в качестве источника или назначения для передачи DMA. Этот регистр данных находится в известном смещении от начального адреса устройства. Ширина этого регистра определяется элементом DmaWidth . Драйвер устройства получает начальный адрес устройства из списка ресурсов, который он получает в запросе IRP_MN_START_DEVICE , который запускает устройство. Дополнительные сведения об этом адресе см. в описании элемента u.Memory.Start в CM_PARTIAL_RESOURCE_DESCRIPTOR.
Для устройства DMA master шины элемент DeviceAddress не используется.
Комментарии
Драйвер устройства, использующего DMA для передачи данных, использует структуру DEVICE_DESCRIPTION для передачи сведений об устройстве в подпрограмму IoGetDmaAdapter . Драйвер вызывает эту подпрограмму для запроса объекта адаптера для объекта физического устройства (PDO). Это PDO представляет физическое подключение устройства к шине ввода-вывода, используемой для DMA. Дополнительные сведения см. в разделе Получение объекта адаптера.
Чтобы выделить ресурсы для контроллера DMA, диспетчеру ввода-вывода требуются сведения о контроллере, но некоторые из этих сведений можно получить только из драйвера. Например, драйвер для устройства с master шиной знает, поддерживает ли устройство точечную и сборную DMA или использует полные 32-разрядные адреса. Кроме того, драйвер для подчиненного устройства может определить номер канала DMA из списка ресурсов, который драйвер получает в запросе IRP_MN_START_DEVICE , который запускает устройство. Драйвер использует структуру DEVICE_DESCRIPTION для передачи этих сведений диспетчеру ввода-вывода.
Перед вызовом IoGetDmaAdapter драйвер должен сначала инициализировать всю структуру DEVICE_DESCRIPTION , а затем заполнить выбранные элементы для описания устройства.
Член InterfaceType указывает тип интерфейса шины, который будет использоваться для DMA. Если для параметра InterfaceTypeзадано значение InterfaceTypeUndefined, IoGetDmaAdapter запрашивает PDO, чтобы определить правильный тип интерфейса для устройства. Можно также указать явный тип интерфейса, например Internal, Isa, Eisa или PCIBus. Дополнительные сведения см. в списке поддерживаемых типов интерфейсов в INTERFACE_TYPE.
Если для элемента ScatterGather задано значение TRUE , а для элемента InterfaceType задано значение PCIBus, элемент Dma32BitAddresses игнорируется, а IoGetDmaAdapter предполагает, что устройство поддерживает 32-разрядные адреса DMA.
Если член Dma64BitAddresses имеет значение TRUE, то элемент Dma32BitAddresses игнорируется и IoGetDmaAdapter предполагает, что устройство поддерживает 64-разрядные адреса DMA.
Чтобы указать, что аппаратное обеспечение контроллера DMA не может надежно поддерживать точное количество передач, задайте для ignoreCount значение TRUE, а для параметра Version — значение, отличное от DEVICE_DESCRIPTION_VERSION. На платформе с таким контроллером DMA операционная система игнорирует счетчик передачи DMA, но должна принимать особые меры предосторожности для обеспечения целостности данных во время операций DMA. Как правило, использование обходного решения для компенсации недостатка контроллера DMA снижает скорость передачи данных.
Драйвер должен указывать TypeF в качестве значения DmaSpeed , только если встроенное ПО ACPI компьютера поддерживает его.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Поддерживается начиная с Windows 2000. |
| Верхняя часть | wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h) |