Jak napisać pierwszy sterownik klienta USB (KMDF)

W tym artykule użyjesz szablonu USB Kernel-Mode Driver dostarczonego z programem Microsoft Visual Studio, aby napisać prosty sterownik trybu jądra oparty na frameworku KMDF. Po utworzeniu i zainstalowaniu sterownika klienta zobaczysz sterownik klienta w Menedżerze urządzeń i wyświetlisz dane wyjściowe sterownika w debugerze.

Aby uzyskać wyjaśnienie kodu źródłowego wygenerowanego przez szablon, zobacz Understanding the KMDF template code for a USB client driver (Opis kodu szablonu usługi KMDF dla sterownika klienta USB).

Wymagania wstępne

Do opracowywania, debugowania i instalowania sterownika trybu jądra potrzebne są dwa komputery:

• Komputer-host z systemem Windows 7 lub nowszą wersją systemu operacyjnego Windows. Komputer-host to środowisko programistyczne, w którym piszesz i debugujesz sterownik.
• Komputer docelowy z systemem Windows Vista lub nowszą wersją systemu Windows. Komputer docelowy ma sterownik trybu jądra, który chcesz debugować.

Przed rozpoczęciem upewnij się, że spełniasz następujące wymagania:

Wymagania dotyczące oprogramowania

• Komputer-host hostuje środowisko programistyczne i ma program Visual Studio.
• Na komputerze-hoście jest najnowszy zestaw sterowników systemu Windows (WDK). Zestaw zawiera nagłówki, biblioteki, narzędzia, dokumentację oraz narzędzia debugowania wymagane do opracowywania, kompilowania i debugowania sterownika KMDF. Aby uzyskać najnowszą wersję zestawu WDK, zobacz Pobieranie zestawu sterowników systemu Windows (WDK).
• Komputer-host ma najnowszą wersję narzędzi do debugowania dla systemu Windows. Najnowszą wersję można pobrać z zestawu WDK lub pobrać i zainstalować narzędzia debugowania dla systemu Windows.
• Na komputerze docelowym jest uruchomiony system Windows Vista lub nowsza wersja systemu Windows.
• Twój komputer hosta i komputer docelowy są skonfigurowane do debugowania jądra. Aby uzyskać więcej informacji, zobacz Konfigurowanie połączenia sieciowego w programie Visual Studio.

Wymagania sprzętowe

Pobierz urządzenie USB, dla którego będziesz zapisywać sterownik klienta. W większości przypadków zapewnione jest urządzenie USB i jego specyfikacja sprzętowa. W specyfikacji opisano możliwości urządzenia i obsługiwane polecenia dostawcy. Użyj specyfikacji, aby określić funkcjonalność sterownika USB i powiązane decyzje projektowe.

Jeśli dopiero zaczynasz pracować nad sterownikami USB, skorzystaj z zestawu szkoleniowego OSR USB FX2, aby zbadać próbki USB dołączone do zestawu WDK. Zestaw szkoleniowy można pobrać z usługi OSR Online. Zawiera urządzenie USB FX2 i wszystkie wymagane specyfikacje sprzętowe do zaimplementowania sterownika klienta.

Możesz również uzyskać urządzenia Microsoft USB Test Tool (MUTT). Sprzęt MUTT można kupić od JJG Technologies. Na urządzeniu nie zainstalowano zainstalowanego oprogramowania układowego. Aby zainstalować oprogramowanie układowe, pobierz pakiet oprogramowania MUTT z tej witryny sieci Web i uruchom MUTTUtil.exe. Aby uzyskać więcej informacji, zobacz dokumentację zawartą w pakiecie.

Zalecane tematy

• Ogólne pojęcia dla wszystkich programistów sterowników
• Węzły urządzeń i stosy urządzeń
• Rozpocznij pracę ze sterownikami w systemie Windows
• Kernel-Mode Platforma Sterowników
• Opracowywanie sterowników za pomocą windows Driver Foundation, napisane przez Penny Orwick i Guy Smith. Aby uzyskać więcej informacji, zobacz Tworzenie sterowników za pomocą usługi WDF.

Krok 1. Generowanie kodu sterownika KMDF przy użyciu szablonu sterownika USB programu Visual Studio

Aby uzyskać instrukcje dotyczące generowania kodu sterownika KMDF, zobacz kroki opisane w artykule Pisanie sterownika KMDF na podstawie szablonu.

W przypadku kodu specyficznego dla portu USB wybierz następujące opcje w programie Visual Studio:

1. W oknie dialogowym Nowy projekt w polu wyszukiwania u góry wpisz USB.
2. W środkowym okienku wybierz pozycję Sterownik trybu jądra, USB (KMDF).
3. Wybierz Dalej.
4. Wprowadź nazwę projektu, wybierz lokalizację zapisywania i wybierz pozycję Utwórz.

Na poniższych zrzutach ekranu przedstawiono okno dialogowe Nowy projekt dla szablonu sterownik Kernel-Mode USB .

W tym artykule przyjęto założenie, że nazwa projektu programu Visual Studio to "MyUSBDriver_". Zawiera on następujące pliki:

Krok 2. Modyfikowanie pliku INF w celu dodania informacji o urządzeniu

Przed utworzeniem sterownika należy zmodyfikować szablon pliku INF z informacjami o urządzeniu, w szczególności ciąg identyfikatora sprzętu.

W Eksploratorze rozwiązań w obszarze Pliki sterowników kliknij dwukrotnie plik INF.

W pliku INF można podać informacje, takie jak nazwa producenta i dostawcy, klasa konfiguracji urządzenia itd. Jednym z informacji, które należy podać, jest identyfikator sprzętu urządzenia.

Aby podać ciąg identyfikatora sprzętu:

1. Dołącz urządzenie USB do komputera hosta i pozwól systemowi Windows wyliczyć urządzenie.

2. Otwórz Menedżera urządzeń i otwórz właściwości urządzenia.

3. Na karcie Szczegóły wybierz pozycję Identyfikatory twarde w obszarze Właściwość.

   Identyfikator sprzętu urządzenia jest wyświetlany w polu listy. Wybierz i przytrzymaj (lub kliknij prawym przyciskiem myszy) i skopiuj ciąg identyfikatora sprzętu.

4. Zastąp ciąg USB\VID_vvvv&PID_pppp w poniższym wierszu ciągiem identyfikatora sprzętu.

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

Krok 3. Kompilowanie kodu sterownika klienta USB

Aby skompilować sterownik:

1. Otwieranie projektu lub rozwiązania sterownika w programie Visual Studio
2. Wybierz i przytrzymaj (lub kliknij prawym przyciskiem myszy) rozwiązanie w Eksploratorze rozwiązań i wybierz pozycję Configuration Manager.
3. W programie Configuration Manager wybierz konfigurację aktywnego rozwiązania (na przykład debugowanie lub wydanie) i aktywną platformę rozwiązania (na przykład Win32), która odpowiada typowi kompilacji, którą interesujesz.
4. W menu Kompilacja wybierz pozycję Kompiluj rozwiązanie.

Aby uzyskać więcej informacji, zobacz Tworzenie sterownika.

Krok 4. Konfigurowanie komputera na potrzeby testowania i debugowania

Aby przetestować i debugować sterownik, należy uruchomić debuger na komputerze hosta i sterownik na komputerze docelowym. Do tej pory na komputerze hosta użyto programu Visual Studio do skompilowania sterownika. Następnie należy skonfigurować komputer docelowy. Aby skonfigurować komputer docelowy, postępuj zgodnie z instrukcjami w Instrukcjach aprowizowania komputera na potrzeby wdrażania i testowania sterowników.

Krok 5. Włączanie śledzenia na potrzeby debugowania jądra

Kod szablonu zawiera kilka komunikatów śledzenia (TraceEvents), które mogą ułatwić śledzenie wywołań funkcji. Wszystkie funkcje w kodzie źródłowym zawierają komunikaty śledzenia, które oznaczają wpis i zakończenie procedury. W przypadku błędów komunikat śledzenia zawiera kod błędu i znaczący ciąg. Ponieważ śledzenie WPP jest włączone dla projektu sterownika, plik symbolu PDB utworzony podczas procesu kompilacji zawiera instrukcje formatowania komunikatów śledzenia. Jeśli skonfigurujesz komputer-host i komputer docelowy do śledzenia WPP, sterownik może wysyłać komunikaty śledzenia do pliku lub debuggera.

Aby skonfigurować komputer hosta na potrzeby śledzenia programu WPP:

1. Utwórz pliki formatu komunikatu śledzenia (TMF), wyodrębniając instrukcje dotyczące formatowania komunikatów śledzenia z pliku symboli PDB.

   Za pomocą Tracepdb.exe można tworzyć pliki TMF. Narzędzie znajduje się w folderze> instalacyjnym<Windows Kits\10.0\bin\<architecture> zestawu WDK. Następujące polecenie tworzy pliki TMF dla projektu sterownika.

   tracepdb -f <PDBFiles> -p <TMFDirectory>

   Opcja -f określa lokalizację i nazwę pliku symboli PDB. Opcja -p określa lokalizację plików TMF tworzonych przez bazę danych Tracepdb. Aby uzyskać więcej informacji, zobacz Tracepdb Commands (Polecenia usługi Tracepdb).

   W określonej lokalizacji zobaczysz trzy pliki (jeden na plik .c w projekcie). Otrzymują nazwy plików GUID.

2. W debugerze wpisz następujące polecenia:

   1. .load Wmitrace

      Ładuje rozszerzenie Wmitrace.dll.

   2. .łańcuch

      Sprawdź, czy rozszerzenie debugera zostało załadowane.

   3. !wmitrace.searchpath +<lokalizacja pliku TMF>

      Dodaj lokalizację plików TMF do ścieżki wyszukiwania rozszerzenia debugera.

      Dane wyjściowe będą wyglądać mniej więcej tak:

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

Aby skonfigurować komputer docelowy na potrzeby śledzenia programu WPP:

1. Upewnij się, że masz narzędzie Tracelog na komputerze docelowym. Narzędzie znajduje się w folderze <install_folder>Windows Kits\8.0\Tools\<arch> w katalogu WDK. Aby uzyskać więcej informacji, zobacz Tracelog Command Syntax (Składnia poleceń tracelog).

2. Otwórz okno polecenia i uruchom go jako administrator.

3. Wpisz następujące polecenie:

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

   Polecenie uruchamia sesję śledzenia o nazwie MyTrace.

   Argument guid określa GUID dostawcy śledzenia, którym jest sterownik klienta. GUID można uzyskać z pliku Trace.h w projekcie Visual Studio Professional 2019. Alternatywnie, możesz wpisać następujące polecenie i określić identyfikator GUID w pliku .guid. Plik zawiera identyfikator GUID w formacie łącznika:

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

   Sesję śledzenia można zatrzymać, wpisując następujące polecenie:

   tracelog -stop MyTrace

Krok 6. Wdrażanie sterownika na komputerze docelowym

1. W oknie Eksplorator rozwiązań wybierz i przytrzymaj (lub kliknij prawym przyciskiem myszy) *<nazwę> projektu*Pakiet , a następnie wybierz pozycję Właściwości.
2. W okienku po lewej stronie przejdź do sekcji Configuration Properties > Driver Install > Deployment.
3. Zaznacz pole wyboru Włącz wdrożenie i zaznacz pole wyboru Importuj do magazynu sterowników.
4. W polu Nazwa komputera zdalnego określ nazwę komputera docelowego.
5. Wybierz pozycję Zainstaluj i zweryfikuj.
6. Wybierz OK
7. W menu Debugowanie wybierz pozycję Rozpocznij debugowanielub naciśnij F5 na klawiaturze.

Aby uzyskać więcej informacji na temat wdrażania sterownika w systemie docelowym w programie Visual Studio, zobacz Wdrażanie sterownika na komputerze testowym.

Sterownik można również zainstalować ręcznie na komputerze docelowym przy użyciu Menedżera urządzeń. Jeśli chcesz zainstalować sterownik z poziomu wiersza polecenia, dostępne są następujące narzędzia:

• PnPUtil

  To narzędzie jest dostarczane z systemem Windows. Jest w systemie Windows\System32. To narzędzie służy do dodawania sterownika do magazynu sterowników.

  C:\>pnputil /a m:\MyDriver_.inf
  Microsoft PnP Utility
  
  Processing inf : MyDriver_.inf
  Driver package added successfully.
  Published name : oem22.inf
  

  Aby uzyskać więcej informacji, zobacz PnPUtil Examples (Przykłady narzędzia PnPUtil).

• Aktualizacja usługi DevCon

  To narzędzie jest dostarczane z zestawem WDK. Można go użyć do instalowania i aktualizowania sterowników.

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

Krok 7. Wyświetlanie sterownika w Menedżerze urządzeń

1. Wprowadź następujące polecenie, aby otworzyć Menedżera urządzeń:

   devmgmt
   

2. Sprawdź, czy w Menedżerze urządzeń jest wyświetlany węzeł dla następującego elementu:

   Próbki

   MyUSBDriver_Device

Krok 8. Wyświetlanie danych wyjściowych w debugerze

Program Visual Studio najpierw wyświetla postęp w oknie Dane wyjściowe . Następnie zostanie otwarte okno natychmiastowe debugera. Sprawdź, czy komunikaty śledzenia są wyświetlane w debugerze na komputerze hosta. Dane wyjściowe powinny wyglądać następująco: "MyUSBDriver_" to nazwa modułu sterownika:

[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

Tematy pokrewne

• Opis kodu szablonu usługi KMDF dla sterownika klienta USB
• Wprowadzenie do programowania sterowników klienta USB