Запись первого драйвера USB-клиента (KMDF)

  • Статья

В этой статье вы будете использовать шаблон драйвера USB-Kernel-Mode , предоставляемый Вместе с Microsoft Visual Studio, для написания простого клиентского драйвера на основе платформы драйвера в режиме ядра (KMDF). После сборки и установки драйвера клиента вы увидите драйвер клиента в диспетчер устройств и просмотрите выходные данные драйвера в отладчике.

Описание исходного кода, созданного шаблоном, см. в статье Общие сведения о коде шаблона KMDF для драйвера USB-клиента.

Предварительные требования

Для разработки, отладки и установки драйвера в режиме ядра требуются два компьютера:

  • Главный компьютер под управлением Windows 7 или более поздней версии операционной системы Windows. Главный компьютер — это среда разработки, в которой вы пишете и отлаживать драйвер.
  • Целевой компьютер под управлением Windows Vista или более поздней версии Windows. На целевом компьютере есть драйвер в режиме ядра, который требуется отладить.

Перед началом работы убедитесь, что выполнены следующие требования:

Требования к программному обеспечению

  • На хост-компьютере размещается среда разработки и visual Studio.
  • На вашем хост-компьютере установлена последняя версия пакета драйверов Windows (WDK). Комплект включает заголовки, библиотеки, средства, документацию и средства отладки, необходимые для разработки, сборки и отладки драйвера KMDF. Сведения о том, как получить последнюю версию WDK, см. в разделе Скачивание пакета драйверов Windows (WDK).
  • На хост-компьютере установлена последняя версия средств отладки для Windows. Последнюю версию можно получить в WDK или скачать и установить средства отладки для Windows.
  • Целевой компьютер работает под управлением Windows Vista или более поздней версии Windows.
  • Главный и целевой компьютеры настроены для отладки ядра. Дополнительные сведения см. в статье Настройка сетевого подключения в Visual Studio.

Требования к оборудованию

Получите USB-устройство, для которого будет написан драйвер клиента. В большинстве случаев вам предоставляется USB-устройство и его спецификация оборудования. Спецификация описывает возможности устройства и поддерживаемые команды поставщика. Используйте спецификацию для определения функциональных возможностей USB-драйвера и связанных проектных решений.

Если вы не знакомы с разработкой драйверов USB, используйте комплект обучения OSR USB FX2 для изучения примеров USB, включенных в WDK. Комплект для обучения можно получить в OSR Online. Он содержит устройство USB FX2 и все необходимые аппаратные спецификации для реализации драйвера клиента.

Вы также можете получить устройства Microsoft USB Test Tool (MUTT). Оборудование MUTT можно приобрести у JJG Technologies. На устройстве не установлено встроенное ПО. Чтобы установить встроенное ПО, скачайте пакет программного обеспечения MUTT с этого веб-сайта и запустите MUTTUtil.exe. Дополнительные сведения см. в документации, включенной в пакет .

Шаг 1. Создание кода драйвера KMDF с помощью шаблона драйвера USB в Visual Studio

Инструкции по созданию кода драйвера KMDF см. в разделе Создание драйвера KMDF на основе шаблона.

Для конкретного кода USB выберите следующие параметры в Visual Studio:

  1. В диалоговом окне Новый проект в поле поиска вверху введите USB.
  2. В средней области выберите Драйвер режима ядра, USB (KMDF) .
  3. Выберите Далее.
  4. Введите имя проекта, выберите расположение для сохранения и нажмите кнопку Создать.

На следующих снимках экрана показано диалоговое окно Новый проект для шаблона Драйвера USB Kernel-Mode .

Параметры новых проектов в Visual Studio.

Второй экран параметров нового проекта в Visual Studio.

В этой статье предполагается, что проект Visual Studio имеет имя "MyUSBDriver_". Она содержит следующие файлы:

Файлы Описание
Public.h Предоставляет общие объявления, совместно используемые драйвером клиента и пользовательскими приложениями, которые взаимодействуют с USB-устройством.
<Имя> проекта.inf Содержит сведения, необходимые для установки драйвера клиента на целевом компьютере.
Trace.h Объявляет функции трассировки и макросы.
Driver.h; Driver.c Объявляет и определяет точки входа драйвера и подпрограммы обратного вызова событий.
Device.h; Device.c Объявляет и определяет подпрограмму обратного вызова события для события prepare-hardware.
Queue.h; Queue.c Объявляет и определяет подпрограмму обратного вызова события для события, вызванного объектом очереди платформы.

Шаг 2. Изменение INF-файла для добавления сведений об устройстве

Перед сборкой драйвера необходимо изменить INF-файл шаблона, указав сведения об устройстве, в частности строку идентификатора оборудования.

В Обозреватель решений в разделе Файлы драйверов дважды щелкните INF-файл.

В INF-файле можно указать такие сведения, как имя производителя и поставщика, класс настройки устройства и т. д. Одна из необходимых сведений — это идентификатор оборудования устройства.

Чтобы указать строку идентификатора оборудования, выполните следующие действия:

  1. Подключите USB-устройство к хост-компьютеру и разрешите Windows перечислить устройство.

  2. Откройте диспетчер устройств и откройте свойства устройства.

  3. На вкладке Сведения выберите Hardward Ids (Жесткие идентификаторы ) в разделе Свойство.

    Идентификатор оборудования для устройства отображается в списке. Выберите и удерживайте (или щелкните правой кнопкой мыши) и скопируйте строку идентификатора оборудования.

  4. Замените USB\VID_vvvv&PID_pppp в следующей строке строке строкой идентификатора оборудования.

    [Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp

Шаг 3. Создание кода драйвера USB-клиента

Чтобы создать драйвер, выполните приведенные далее действия.

  1. Открытие проекта драйвера или решения в Visual Studio
  2. Выберите и удерживайте (или щелкните правой кнопкой мыши) решение в Обозреватель решений и выберите Configuration Manager.
  3. В Configuration Manager выберите Активную конфигурацию решения (например, Отладка или Выпуск) и Активную платформу решения (например, Win32), соответствующие интересующему типу сборки.
  4. В меню Построение выберите пункт Построить решение.

Дополнительные сведения см. в разделе Создание драйвера.

Шаг 4. Настройка компьютера для тестирования и отладки

Для тестирования и отладки драйвера запустите отладчик на хост-компьютере и драйвер на целевом компьютере. До сих пор вы использовали Visual Studio на хост-компьютере для сборки драйвера. Далее необходимо настроить целевой компьютер. Чтобы настроить целевой компьютер, следуйте инструкциям в статье Подготовка компьютера к развертыванию и тестированию драйверов.

Шаг 5. Включение трассировки для отладки ядра

Код шаблона содержит несколько сообщений трассировки (TraceEvents), которые могут помочь в отслеживании вызовов функций. Все функции в исходном коде содержат сообщения трассировки, которые помечают вход и выход подпрограммы. Для ошибок сообщение трассировки содержит код ошибки и осмысленную строку. Так как трассировка WPP включена для проекта драйвера, файл символов PDB, созданный в процессе сборки, содержит инструкции по форматированию сообщений трассировки. При настройке главного и целевого компьютеров для трассировки WPP драйвер может отправлять сообщения трассировки в файл или отладчик.

Чтобы настроить главный компьютер для трассировки WPP, выполните следующие действия.

  1. Создайте файлы формата сообщений трассировки (TMF), извлекая инструкции по форматированию сообщений трассировки из файла символов PDB.

    Для создания файлов TMF можно использовать Tracepdb.exe. Средство находится в папке<> установкиWindows Kits\10.0\bin\<architecture> в WDK. Следующая команда создает TMF-файлы для проекта драйвера.

    tracepdb -f <PDBFiles> -p <TMFDirectory>

    Параметр -f указывает расположение и имя файла символов PDB. Параметр -p указывает расположение файлов TMF, созданных Tracepdb. Дополнительные сведения см. в разделе Команды Tracepdb.

    В указанном расположении вы увидите три файла (по одному на C-файл в проекте). Им присваиваются имена файлов GUID.

  2. В отладчике введите следующие команды:

    1. .load Wmitrace

      Загружает расширение Wmitrace.dll.

    2. .Цепи

      Убедитесь, что расширение отладчика загружено.

    3. !wmitrace.searchpath +<расположение> файла TMF

      Добавьте расположение TMF-файлов в путь поиска расширения отладчика.

      Результат будет примерно таким:

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

Чтобы настроить целевой компьютер для трассировки WPP, выполните следующие действия.

  1. Убедитесь, что на целевом компьютере есть средство Tracelog. Средство находится в папке< install_folder>Windows Kits\8.0\Tools\<arch> в WDK. Дополнительные сведения см. в разделе Синтаксис команд Tracelog.

  2. Откройте командное окно и запустите от имени администратора.

  3. Введите следующую команду:

    tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

    Команда запускает сеанс трассировки с именем MyTrace.

    Аргумент GUID указывает GUID поставщика трассировки, который является драйвером клиента. Guid можно получить из Trace.h в проекте Visual Studio Professional 2019. В качестве другого варианта можно ввести следующую команду и указать GUID в guid-файле. Файл содержит GUID в формате дефиса:

    tracelog -start MyTrace -guid c:\drivers\Provider.guid -flag 0xFFFF -level 7-rt -kd

    Вы можете остановить сеанс трассировки, введя следующую команду:

    tracelog -stop MyTrace

Шаг 6. Развертывание драйвера на целевом компьютере

  1. В окне Обозреватель решений выберите и удерживайте (или щелкните правой кнопкой мыши) *<имя> проекта*Пакет и выберите свойства.
  2. В области слева перейдите к разделу Свойства > конфигурации Развертывание установки > драйвера.
  3. Установите флажок Включить развертывание и проверка Импорт в хранилище драйверов.
  4. В поле Имя удаленного компьютера укажите имя целевого компьютера.
  5. Выберите Установить и проверить.
  6. Щелкните ОК.
  7. В меню Отладка выберите Начать отладку или нажмите клавишу F5 на клавиатуре.

Примечание

Не указывайте идентификатор оборудования устройства в разделе Обновление драйвера идентификатора оборудования. Идентификатор оборудования должен быть указан только в файле сведений о драйвере (INF).

Дополнительные сведения о развертывании драйвера в целевой системе в Visual Studio см. в разделе Развертывание драйвера на тестовом компьютере.

Вы также можете вручную установить драйвер на целевом компьютере с помощью диспетчер устройств. Если вы хотите установить драйвер из командной строки, доступны следующие служебные программы:

  • PnPUtil

    Это средство поставляется вместе с Windows. Он находится в Windows\System32. Эту служебную программу можно использовать для добавления драйвера в хранилище драйверов.

    C:\>pnputil /a m:\MyDriver_.inf
Microsoft PnP Utility

Processing inf : MyDriver_.inf
Driver package added successfully.
Published name : oem22.inf

    Дополнительные сведения см. в разделе Примеры PnPUtil.

  • Обновление DevCon

    Это средство поставляется вместе с WDK. Его можно использовать для установки и обновления драйверов.

    devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6

Шаг 7. Просмотр драйвера в диспетчер устройств

  1. Введите следующую команду, чтобы открыть диспетчер устройств:

    devmgmt

  2. Убедитесь, что диспетчер устройств отображает узел для следующего узла:

    Примеры

    MyUSBDriver_Device

Шаг 8. Просмотр выходных данных в отладчике

Visual Studio сначала отображает ход выполнения в окне Вывода . Затем откроется окно интерпретации отладчика. Убедитесь, что сообщения трассировки отображаются в отладчике на хост-компьютере. Выходные данные должны выглядеть следующим образом, где "MyUSBDriver_" — это имя модуля драйвера:

[3]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverContextCleanup Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Exit
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Entry
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Exit