Udostępnij przez

Samouczek: pisanie uniwersalnego sterownika systemu Windows (KMDF) na podstawie szablonu

W tym artykule opisano sposób pisania sterownika uniwersalnego systemu Windows przy użyciu Kernel-Mode Driver Framework (KMDF). Zaczynasz od szablonu programu Microsoft Visual Studio, a następnie wdrażasz i instalujesz sterownik na osobnym komputerze.

Warunki wstępne

  • Postępuj zgodnie z instrukcjami, aby zainstalować zestaw Windows Driver Kit (WDK). Narzędzia debugowania dla systemu Windows są uwzględniane podczas instalowania zestawu WDK.

  • Zainstaluj program Visual Studio 2022. Po zainstalowaniu programu Visual Studio 2022 wybierz pakiet roboczy Rozwój aplikacji desktopowych z C++, a następnie w sekcji Poszczególne składniki dodaj:

    • MSVC v143 — VS 2022 C++ ARM64/ARM64EC Biblioteki z zabezpieczeniem przed Spectre (najnowsze)
    • Biblioteki MSVC w wersji 143 - VS 2022 C++ x64/x86 zabezpieczone przed Spectre (najnowsze)
    • C++ ATL dla najnowszych narzędzi kompilacyjnych wersji v143 z zabezpieczeniami Spectre (ARM64/ARM64EC)
    • C++ ATL dla najbardziej aktualnych narzędzi kompilacyjnych wersji v143 z zabezpieczeniami Spectre (x86 & x64)
    • C++ MFC dla najnowszych narzędzi kompilacji w wersji v143 z mitygacją Spectre (ARM64/ARM64EC)
    • C++ MFC dla najnowszych narzędzi kompilacji w wersji 143 z zabezpieczeniami Spectre (x86 & x64)
    • Zestaw sterowników systemu Windows

Tworzenie i budowanie sterownika

  1. Otwórz program Microsoft Visual Studio. W menu Plik wybierz pozycję Nowy > Projekt.

  2. W oknie dialogowym tworzenie nowego projektu wybierz pozycję C++ na liście rozwijanej po lewej stronie, wybierz pozycję Windows na środkowej liście rozwijanej, a następnie wybierz pozycję Driver na prawej liście rozwijanej.

  3. Wybierz sterownik trybu jądra (KMDF) z listy typów projektów. Wybierz pozycję Dalej.

    Zrzut ekranu okna dialogowego nowego projektu przedstawiający wybrany sterownik trybu jądra.

    Napiwek

    Jeśli nie możesz znaleźć szablonów projektów sterowników w programie Visual Studio, rozszerzenie programu Visual Studio WDK nie zostało poprawnie zainstalowane. Aby rozwiązać ten problem, uruchom Instalator programu Visual Studio, wybierz pozycję Modyfikuj, dodaj Zestawy sterowników systemu Windows na karcie Składniki indywidualne, a następnie wybierz pozycję Modyfikuj.

  4. W oknie dialogowym Konfigurowanie nowego projektu wprowadź "KmdfDriver" w polu Nazwa projektu.

    Notatka

    Podczas tworzenia nowego sterownika KMDF lub UMDF należy wybrać nazwę sterownika, która ma maksymalnie 32 znaki. Ten limit długości jest zdefiniowany w pliku wdfglobals.h.  

  5. W polu Lokalizacja wprowadź katalog, w którym chcesz utworzyć nowy projekt.

  6. Sprawdź Umieść rozwiązanie i projekt w tym samym katalogu i wybierz pozycję Utwórz.

    Zrzut ekranu okna dialogowego konfiguracji projektu.

    Program Visual Studio tworzy jeden projekt i rozwiązanie. Można je wyświetlić w oknie eksploratora rozwiązań . (Jeśli okno Eksplorator rozwiązań nie jest widoczne, wybierz pozycję Eksplorator rozwiązań z menu Widok ). Rozwiązanie ma projekt sterownika o nazwie KmdfDriver. Aby wyświetlić kod źródłowy sterownika, otwórz dowolne pliki w obszarze Pliki źródłowe. Driver.c i Device.c to dobre miejsca do rozpoczęcia.

    Zrzut ekranu eksploratora rozwiązań przedstawiający pliki w projekcie sterownika.

  7. W oknie Eksplorator rozwiązań wybierz i przytrzymaj (lub kliknij prawym przyciskiem myszy) KmdfDriver, a następnie wybierz pozycję Właściwości . Przejdź do Właściwości konfiguracji > Ustawienia sterownika > Ogólnei zwróć uwagę, że Platforma docelowa ma wartość domyślną Universal.

  8. Aby zbudować sterownik, wybierz pozycję Buduj rozwiązanie z menu Buduj. Program Microsoft Visual Studio wyświetla postęp budowania w oknie wyjściowym. (Jeśli okno Dane wyjściowe nie jest widoczne, wybierz pozycję Dane wyjściowe z menu Widok ).

    Sprawdź, czy dane wyjściowe kompilacji obejmują:

    >    Driver is 'Universal'.

    Po upewnieniu się, że rozwiązanie utworzono pomyślnie, możesz zamknąć program Visual Studio.

  9. Aby wyświetlić wbudowany sterownik, w Eksploratorze plików przejdź do folderu kmdfDriver, a następnie do x64\Debug\KmdfDriver. Katalog zawiera następujące pliki:

    • KmdfDriver.sys--plik sterownika trybu jądra
    • KmdfDriver.inf — plik informacyjny używany przez system Windows podczas instalowania sterownika

Wdróż sterownik

Zazwyczaj podczas testowania i debugowania sterownika debuger i sterownik są uruchamiane na oddzielnych komputerach. Komputer z uruchomionym debugerem jest nazywany komputerem hosta , a komputer z uruchomionym sterownikiem jest nazywany komputerem docelowym . Komputer docelowy jest również nazywany komputerem testowym . Aby uzyskać więcej informacji na temat debugowania sterowników, zobacz Narzędzia debugowania dla systemu Windows.

Do tej pory użyto programu Visual Studio do skompilowania sterownika na komputerze hosta. Teraz należy skonfigurować komputer docelowy.

  1. Postępuj zgodnie z instrukcjami w Przygotuj komputer na potrzeby wdrażania i testowania sterowników (WDK 10).

    Napiwek

    Podczas wykonywania kroków w celu automatycznego konfigurowania komputera docelowego przy użyciu kabla sieciowego, zwróć uwagę na port i klucz. Będą one używane w dalszej części kroku debugowania. W tym przykładzie używamy portu 50000 jako portu i 1.2.3.4 jako klucza.

    W rzeczywistych scenariuszach debugowania sterowników zalecamy użycie klucza wygenerowanego przez KDNET. Aby uzyskać więcej informacji na temat używania sieci KDNET do generowania klucza losowego, zobacz artykuł Debug Drivers - Step by Step Lab (Sysvad Kernel Mode) (Debugowanie sterowników — krok po kroku — tryb jądra systemu).

  2. Na komputerze-hoście otwórz rozwiązanie w programie Visual Studio. Możesz kliknąć dwukrotnie plik rozwiązania, KmdfDriver.sln, w folderze KmdfDriver.

  3. W oknie Eksploratora rozwiązań wybierz i przytrzymaj (lub kliknij prawym przyciskiem myszy) projekt KmdfDriver, a następnie wybierz pozycję Właściwości .

  4. W oknie właściwości pakietu KmdfDriver w okienku po lewej stronie przejdź do Właściwości konfiguracji > Instalowanie sterownika > Rozmieszczanie.

  5. Sprawdź , usuń poprzednie wersje sterowników przed wdrożeniem.

  6. Dla Nazwa komputera zdalnegowybierz nazwę komputera, który skonfigurowałeś do testowania i debugowania. W tym ćwiczeniu użyjemy komputera o nazwie MyTestComputer.

  7. Wybierz Aktualizacja sterownika według identyfikatora sprzętu, a następnie wprowadź identyfikator sprzętu dla swojego sterownika. W tym ćwiczeniu identyfikator sprzętu to Root\KmdfDriver. Wybierz pozycję OK.

    zrzut ekranu przedstawiający okno stron właściwości pakietu kmdfdriver pokazujące wybraną instalację sterownika wdrożenia

    Notatka

    W tym ćwiczeniu identyfikator sprzętu nie identyfikuje rzeczywistego elementu sprzętu. Identyfikuje wyimaginowane urządzenie, które jest umieszczone w drzewie urządzeń jako dziecko węzła głównego. W przypadku rzeczywistego sprzętu nie wybieraj aktualizacji sterownika dla identyfikatora sprzętu; zamiast tego wybierz pozycję Zainstaluj i zweryfikuj. Identyfikator sprzętu jest widoczny w pliku informacji o sterowniku (INF). W oknie Eksploratora rozwiązań przejdź do Plików sterowników KmdfDriver > i kliknij dwukrotnie plik KmdfDriver.inf. Identyfikator sprzętu znajduje się w obszarze [Standard.NT$ARCH$].

    [Standard.NT$ARCH$]
%KmdfDriver.DeviceDesc%=KmdfDriver_Device, Root\KmdfDriver

  8. Na menu Kompiluj wybierz opcję Wdróż rozwiązanie. Program Visual Studio automatycznie kopiuje pliki wymagane do zainstalowania i uruchomienia sterownika na komputerze docelowym.

    Podczas wdrażania sterownika pliki sterowników są kopiowane do folderu %Systemdrive%\drivertest\drivers na komputerze testowym. Jeśli coś pójdzie nie tak podczas wdrażania, możesz sprawdzić, czy pliki są kopiowane na komputer testowy. Sprawdź, czy pliki .inf, cat, test cert i .sys oraz inne niezbędne pliki znajdują się w folderze %systemdrive%\drivertest\drivers.

    Aby uzyskać więcej informacji na temat wdrażania sterowników, zobacz Wdrażanie sterownika na komputerze testowym.

Instalowanie sterownika

Po wdrożeniu sterownika KMDF na komputerze docelowym należy zainstalować sterownik. Poprzednio, kiedy skonfigurowałeś komputer docelowy w programie Visual Studio, przy użyciu automatycznej opcji , Visual Studio skonfigurował komputer docelowy do uruchamiania podpisywanych sterowników testowych w ramach procesu konfiguracji. Teraz wystarczy zainstalować sterownik przy użyciu narzędzia DevCon.

  1. Na komputerze-hoście przejdź do folderu Narzędzia w instalacji zestawu WDK i znajdź narzędzie DevCon. Na przykład poszukaj w następującym folderze:

    C:\Program Files (x86)\Windows Kits\10\Tools\x64\devcon.exe

    Skopiuj narzędzie DevCon do komputera zdalnego.

  2. Na komputerze docelowym zainstaluj sterownik, przechodząc do folderu zawierającego pliki sterowników, a następnie uruchamiając narzędzie DevCon.

    1. Poniżej przedstawiono ogólną składnię narzędzia devcon używanego do instalowania sterownika:

      devcon install <plik INF><identyfikator urządzenia>

      Plik INF wymagany do zainstalowania tego sterownika to KmdfDriver.inf. Plik INF zawiera identyfikator sprzętu do instalowania pliku binarnego sterownika KmdfDriver.sys. Pamiętaj, że identyfikator sprzętu znajdujący się w pliku INF jest root\KmdfDriver.

    2. Otwórz okno wiersza polecenia jako administrator. Przejdź do folderu pakietu sterowników, a następnie wprowadź następujące polecenie:

      devcon install kmdfdriver.inf root\kmdfdriver

      Jeśli zostanie wyświetlony komunikat o błędzie, że devcon nie został rozpoznany, spróbuj dodać ścieżkę do narzędzia devcon. Jeśli na przykład skopiowano go do folderu na komputerze docelowym o nazwie C:\Tools, spróbuj użyć następującego polecenia:

      c:\tools\devcon install kmdfdriver.inf root\kmdfdriver

      Zostanie wyświetlone okno dialogowe wskazujące, że sterownik testowy jest niepodpisanym sterownikiem. Wybierz opcję Zainstaluj ten sterownik mimo to, aby kontynuować.

      zrzut ekranu przedstawiający ostrzeżenie instalacji sterownika.

Debugowanie sterownika

Teraz, po zainstalowaniu sterownika KMDF na komputerze docelowym, dołącz debuger zdalnie z komputera hosta.

  1. Na komputerze hosta otwórz okno wiersza polecenia jako administrator. Przejdź do katalogu WinDbg.exe. Użyj wersji x64 WinDbg.exe z zestawu sterowników Windows (WDK), który został zainstalowany w ramach instalacji zestawu Windows. Oto domyślna ścieżka do WinDbg.exe:

    C:\Program Files (x86)\Windows Kits\10\Debuggers\x64

  2. Uruchom narzędzie WinDbg, aby nawiązać połączenie z sesją debugowania jądra na komputerze docelowym, używając następującego polecenia. Wartość portu i klucza powinna być taka sama jak wartość użyta do aprowizacji komputera docelowego. Używamy wartości 50000 dla portu i 1.2.3.4 dla klucza, które zostały użyte podczas kroku wdrażania. Flaga k wskazuje, że jest to sesja debugowania jądra.

    WinDbg -k net:port=50000,key=1.2.3.4

  3. Na menu Debug wybierz Break. Debuger na komputerze hosta inicjuje interwencję na komputerze docelowym. W oknie poleceń debugera można zobaczyć wiersz polecenia debugowania jądra: kd>.

  4. W tym momencie możesz eksperymentować z debugerem, wprowadzając polecenia w wierszu polecenia kd-> . Możesz na przykład wypróbować następujące polecenia:

  5. Aby umożliwić ponowne uruchomienie komputera docelowego, wybierz Przejdź z menu Debug lub naciśnij "g", a następnie "enter".

  6. Aby zatrzymać sesję debugowania, wybierz Odłącz debugowany program z menu Debug.

    Ważny

    Upewnij się, że używasz polecenia "go", aby wznowić działanie komputera docelowego przed wyjściem z debugera, w przeciwnym razie pozostanie on nieodpowiadający na dane wejściowe myszy i klawiatury, ponieważ nadal komunikuje się z debugerem.

Aby uzyskać szczegółowy przewodnik krok po kroku procesu debugowania sterowników, zobacz Debugowanie uniwersalnych sterowników — Step by Step Lab (Echo Kernel-Mode).

Aby uzyskać więcej informacji na temat zdalnego debugowania za pomocą WinDbg, zobacz Debugowanie zdalne przy użyciu WinDbg.

Korzystanie z struktury modułów sterowników (DMF)

Driver Module Framework (DMF) to rozszerzenie frameworku WDF, które zapewnia dodatkową funkcjonalność dla deweloperów sterowników WDF. Ułatwia to deweloperom pisanie dowolnego typu sterownika WDF lepiej i szybciej.

Program DMF jako struktura umożliwia tworzenie obiektów WDF nazywanych modułami DMF. Kod tych modułów DMF może być współużytkowany między różnymi sterownikami. Ponadto DMF dołącza bibliotekę modułów DMF, które opracowaliśmy dla naszych sterowników i które mogą stanowić wartość dla innych deweloperów sterowników.

DMF nie zastępuje WDF. DMF to druga platforma używana z platformą WDF. Deweloper korzystający z DMF nadal używa funkcji WDF i wszystkich jego elementów pierwotnych do pisania sterowników urządzeń.

Aby uzyskać więcej informacji, zobacz Driver Module Framework (DMF).

  • Last updated on