Sdílet prostřednictvím

Podpora klientů Kernel-Mode v ovladačích UMDF 1.x

  • Článek

Výstraha

UMDF 2 je nejnovější verze UMDF a nahrazuje UMDF 1. Všechny nové ovladače UMDF by měly být zapsány pomocí UMDF 2. Do UMDF 1 se nepřidávají žádné nové funkce a v novějších verzích Windows 10 je omezená podpora UMDF 1. Univerzální ovladače systému Windows musí používat UMDF 2.

Archivované ukázky UMDF 1 najdete v aktualizaci ovladačů pro Windows 11, verze 22H2 z května 2022 – .

Další informace najdete v tématu Začínáme s UMDF.

Výstraha

Viz také Podpora klientů Kernel-Mode v UMDF 2.x.

UmDF verze 1.9 a novější umožňují ovladačům UMDF podporovat klienty režimu jádra. Klient v režimu jádra může mít jednu z následujících možností:

  • Ovladač režimu jádra, který existuje nad ovladačem UMDF v zásobníku ovladačů daného zařízení.

  • Ovladač režimu jádra pro jeden zásobník zařízení, který podporuje jedno zařízení, otevře popisovač na jiné zařízení a zásobník ovladačů druhého zařízení obsahuje ovladač UMDF.

Jinými slovy, ovladač UMDF, který podporuje klienty režimu jádra, může přijímat vstupně-výstupní požadavky z ovladače režimu jádra. Ovladač režimu jádra může předávat vstupně-výstupní požadavky, které přijal z aplikace v uživatelském režimu, nebo může vytvořit nové vstupně-výstupní požadavky a odeslat je ovladači uživatelského režimu.

Pokud chcete zjistit, jestli ovladač UMDF musí podporovat klienty v režimu jádra, musíte porozumět zásobníku ovladačů, ke kterému bude ovladač přidán a kde se bude ovladač nacházet. Musíte také určit, jestli ovladač z jiné vrstvy může odesílat vstupně-výstupní požadavky na vaše zařízení ovladače.

Ovladač musí podporovat klienty v režimu jádra, pokud:

  • Ovladač režimu jádra se může nacházet přímo nad ovladačem UMDF v zásobníku ovladačů. Například ovladač filtru režimu jádra se může nacházet přímo nad ovladačem funkce založeného na UMDF.

  • Ovladač v režimu jádra z jiného stohu může odesílat vstupně-výstupní požadavky do zařízení vašeho ovladače. Ovladač může například vytvořit symbolický odkaz, který ovladač režimu jádra v jiném zásobníku může použít k otevření popisovače zařízení vašeho ovladače. Ovladač režimu jádra pak může do zařízení odesílat vstupně-výstupní požadavky.

Jak podporovat klienty jádového režimu v ovladači UMDF

Ovladač UMDF může přijímat vstupně-výstupní požadavky z ovladače režimu jádra pouze v případě, že ovladač UMDF povolil podporu pro klienty režimu jádra. Dále, pokud se instalace zařízení pokusí načíst ovladače režimu jádra nad ovladačem UMDF v zásobníku ovladačů zařízení, rozhraní umožňuje jejich načtení pouze tehdy, když ovladač UMDF povolil podporu klientů režimu jádra.

Chcete-li povolit podporu ovladače UMDF pro klienty režimu jádra, musí soubor INF ovladače UMDF obsahovat direktivu UmdfKernelModeClientPolicy v oddílu INF DDInstall.WDF. Pokud soubor INF ovladače UMDF neobsahuje tuto direktivu, umDF neumožňuje spuštění ovladače režimu jádra nainstalovaného nad ovladačem UMDF.

Architektura poskytuje dvě metody, které jsou užitečné pro ovladače, které podporují klienty režimu jádra. Ovladač může volat metodu IWDFIoRequest2::GetRequestorMode , která určuje, jestli vstupně-výstupní požadavek pochází z režimu jádra nebo uživatelského režimu. Pokud vstupně-výstupní požadavek pochází z uživatelského režimu, ovladač může volat IWDFIoRequest2::IsFromUserModeDriver určit, zda požadavek pochází z aplikace nebo jiného ovladače uživatelského režimu.

Omezení ovladačů v režimu jádra

Ovladač UMDF může zpracovávat vstupně-výstupní požadavky z ovladače režimu jádra pouze v případě, že ovladač režimu jádra splňuje následující požadavky:

  • Ovladač v režimu jádra musí být spuštěný v IRQL = PASSIVE_LEVEL, když odešle vstupně-výstupní požadavek.

  • Pokud ovladač nenastavil direktivu UmdfFileObjectPolicy INF na AllowNullAndUnknownFileObjects, musí mít každý vstupně-výstupní požadavek, který ovladač režimu jádra odesílá ovladači uživatelského režimu, přidružený souborový objekt. Rámec musí již být upozorněn, že správce vstupně-výstupních operací vytvořil objekt souboru. (Takové oznámení způsobí, že framework vyvolá zpětnou volací funkci IQueueCallbackCreate::OnCreateFile, ale tato funkce je volitelná.)

  • Požadavek V/V nemůže obsahovat funkční kód IRP_MJ_INTERNAL_DEVICE_CONTROL.

  • Buffery požadavku V/V nesmí obsahovat ukazatele na další informace, protože ovladač uživatelského režimu ukazatele nemůže dereferencovat.

  • Pokud požadavek V/V obsahuje kód řízení V/V, který specifikuje metodu "žádný" přístup k vyrovnávací paměti, ovladač režimu jádra musí odeslat požadavek V/V v kontextu procesu aplikace, která vytvořila tento požadavek V/V. Další informace o tom, jak podporovat metodu "ani" v základním ovladači UMDF, naleznete v tématu Použití vstupně-výstupních operací vyrovnávací paměti ani přímé vstupně-výstupní operace v ovladačích UMDF.

  • Ovladač UMDF může upravit výstupní data V/V požadavku v uživatelském režimu. Ovladač režimu jádra proto musí ověřit všechna výstupní data, která přijímá z ovladače uživatelského režimu.

  • Klient režimu jádra by měl obvykle validovat hodnotu Informace, kterou ovladač UMDF předává IWDFIoRequest::CompleteWithInformation. Pokud je klient ovladačem KMDF, může volat WdfRequestGetCompletionParams aby získal tyto informace ve struktuře IO_STATUS_BLOCK.

    Architektura obvykle neověřuje informační hodnotu, kterou ovladač UMDF předává IWDFIoRequest::CompleteWithInformation. (Tento parametr obvykle určuje počet přenesených bajtů.) Rámec ověřuje hodnotu informace pouze pro výstupní vyrovnávací paměti a pouze pro vyrovnávací vstupně-výstupní metodu přístupu k datům. (Například architektura ověřuje, že počet přenesených bajtů nepřekračuje velikost výstupní vyrovnávací paměti operace čtení, pokud je metoda přístupu uložena do vyrovnávací paměti vstupně-výstupní operace.)

Zpracování návratových hodnot stavu v ovladači UMDF 1.x

Předání návratových hodnot stavu z uživatelského režimu do režimu jádra vyžaduje zvláštní pozornost, jak je znázorněno níže:

  • Ovladače UMDF verze 1 obvykle přijímají návratové hodnoty typu HRESULT, zatímco ovladače režimu jádra založené na KMDF a WDM obvykle přijímají hodnoty typu NTSTATUS. Pokud ovladač UMDF 1.X dokončí vstupně-výstupní požadavek a pokud má ovladač klienta v režimu jádra, volání ovladače na IWDFIoRequest::Complete nebo IWDFIoRequest::CompleteWithInformation by mělo zadat hodnotu HRESULT, kterou ovladač generuje z hodnoty NTSTATUS. Obecně platí, že ovladače UMDF 1.x by měly použít makro HRESULT_FROM_NT (definované v Winerror.h) k vrácení stavu klientovi v režimu jádra. Následující příklad ukazuje, jak toto makro použít při dokončování požadavku.

    hr = HRESULT_FROM_NT(STATUS_BUFFER_OVERFLOW)
request->Complete(HRESULT_FROM_NT(STATUS_BUFFER_OVERFLOW);
return hr;

    Chcete-li vrátit konkrétní hodnotu HRESULT klientovi v režimu jádra, musí následující zpětné volání použít makro HRESULT_FROM_NT:

    Chcete-li použít hodnoty NTSTATUS definované v ntstatus.h, UMDF 1. Ovladač x musí obsahovat tyto dva řádky před zahrnutím dalších hlaviček.

    #define UMDF_USING_NTSTATUS
#include <ntstatus.h>

    Nepoužívejte makro HRESULT_FROM_NT k převodu STATUS_SUCCESS z hodnoty NTSTATUS na hodnotu HRESULT. Stačí vrátit S_OK, jak je znázorněno v následujícím příkladu.

    request->Complete(S_OK);

  • Framework vyřizuje některé vstupně-výstupní požadavky jménem ovladačů UMDF. V některých případech architektura nepřevádí hodnoty typu HRESULT na ekvivalentní hodnoty NTSTATUS, takže rozhraní může předat stav dokončení typu HRESULT klientovi v režimu jádra.

    Kvůli této situaci by klienti v režimu jádra neměli při testování stavu dokončení V/V požadavku používat makro NT_ERROR, protože makro NT_ERROR nevrací hodnotu TRUE pro chybové hodnoty HRESULT. Ovladače režimu jádra by měly při testování stavu dokončení vstupně-výstupních požadavků používat makro NT_SUCCESS.

Podpora klientů v režimu jádra ve starších verzích UMDF

U verzí UMDF starších než 1.9 může soubor INF ovladače obsahovat direktivu INF AddReg , která vytvoří hodnotu registru REG_DWORD velikosti UpperDriverOk pod podklíčem WUDFhardwarového klíče zařízení.

Pokud je hodnota registru UpperDriverOk nastavená na nenulové číslo, architektura umožňuje ovladačům režimu jádra načíst nad ovladač uživatelského režimu. Ovladače režimu jádra můžou předávat vstupně-výstupní požadavky z aplikací uživatelského režimu na ovladač UMDF, ale ovladače režimu jádra nemůžou odesílat vstupně-výstupní požadavky vytvořené v režimu jádra do ovladače UMDF.

Pro UMDF verze 1.9 a novější je hodnota registru UpperDriverOk zastaralá a podporovaná pouze pro existující ovladače. Nové ovladače by měly používat direktivu UmdfKernelModeClientPolicy .