Delen via

Ondersteuning voor Kernel-Mode-clients in UMDF 1.x-stuurprogramma's

  • Artikel

Waarschuwing

UMDF 2 is de nieuwste versie van UMDF en vervangt UMDF 1. Alle nieuwe UMDF-stuurprogramma's moeten worden geschreven met UMDF 2. Er worden geen nieuwe functies toegevoegd aan UMDF 1 en er is beperkte ondersteuning voor UMDF 1 op nieuwere versies van Windows 10. Universele Windows-stuurprogramma's moeten UMDF 2 gebruiken.

De gearchiveerde UMDF 1-voorbeelden vindt u in de Windows 11 versie 22H2 - update van stuurprogrammavoorbeelden van mei 2022.

Zie Aan de slag met UMDF-voor meer informatie.

Waarschuwing

Zie ook Ondersteuning voor Kernel-Mode clients in UMDF 2.x.

Met UMDF-versies 1.9 en hoger kunnen UMDF-stuurprogramma's ondersteuning bieden voor kernelmodusclients. Een kernelmodusclient kan een van de volgende zijn:

  • Een kernelmodusstuurprogramma dat boven een UMDF-stuurprogramma in de stuurprogrammastack van een apparaat bestaat.

  • Een kernelmodusstuurprogramma voor één apparaatstack, dat het ene apparaat ondersteunt, opent een ingang naar een ander apparaat en de stuurprogrammastack van het laatste apparaat bevat een UMDF-stuurprogramma.

Met andere woorden, een UMDF-stuurprogramma dat ondersteuning biedt voor kernelmodusclients, kan I/O-aanvragen ontvangen van een kernelmodusstuurprogramma. Het stuurprogramma voor de kernelmodus kan I/O-aanvragen doorsturen die het heeft ontvangen van een toepassing in de gebruikersmodus, of kan nieuwe I/O-aanvragen maken en verzenden naar het stuurprogramma voor de gebruikersmodus.

Om te bepalen of uw UMDF-stuurprogramma kernelmodusclients moet ondersteunen, moet u de stuurprogrammastack begrijpen waarnaar uw stuurprogramma wordt toegevoegd en waar in die stack uw stuurprogramma zich bevindt. U moet ook bepalen of een stuurprogramma van een andere stack I/O-aanvragen naar het apparaat van uw stuurprogramma kan verzenden.

Uw stuurprogramma moet kernelmodusclients ondersteunen als:

  • Een kernelmodusstuurprogramma kan zich direct boven uw UMDF-stuurprogramma in een stuurprogrammastack bevinden. Een filterstuurprogramma in de kernelmodus bevindt zich bijvoorbeeld direct boven een functiestuurprogramma op basis van UMDF.

  • Een kernelmodusstuurprogramma van een andere stack kan I/O-aanvragen verzenden naar het apparaat van uw stuurprogramma. Uw stuurprogramma kan bijvoorbeeld een symbolische koppeling maken die een kernelmodusstuurprogramma in een andere stack kan gebruiken om een ingang te openen op het apparaat van uw stuurprogramma. Het stuurprogramma voor de kernelmodus kan vervolgens I/O-aanvragen naar het apparaat verzenden.

Hoe kernelmodus-clients te ondersteunen in een UMDF-stuurprogramma

Een UMDF-stuurprogramma kan alleen I/O-aanvragen ontvangen van een kernelmodusstuurprogramma als het UMDF-stuurprogramma ondersteuning heeft ingeschakeld voor kernelmodusclients. Bovendien, als een apparaatinstallatie probeert kernelmodusstuurprogramma's te laden boven een UMDF-stuurprogramma in de stuurprogrammastack van het apparaat, kunnen de stuurprogramma's alleen worden geladen als het UMDF-stuurprogramma ondersteuning heeft ingeschakeld voor kernelmodusclients.

Als u de ondersteuning van een UMDF-stuurprogramma voor kernelmodusclients wilt inschakelen, moet het INF-bestand van het UMDF-stuurprogramma een UmdfKernelModeClientPolicy- instructie bevatten in de INF-DDInstall-.sectie WDF-. Als het INF-bestand van het UMDF-stuurprogramma deze instructie niet bevat, staat UMDF geen kernelmodusstuurprogramma toe dat boven het UMDF-stuurprogramma is geïnstalleerd.

Het framework biedt twee methoden die nuttig zijn voor stuurprogramma's die ondersteuning bieden voor kernelmodusclients. Een stuurprogramma kan de IWDFIoRequest2::GetRequestorMode methode aanroepen om te bepalen of een I/O-aanvraag afkomstig is van de kernelmodus of de gebruikersmodus. Als de I/O-aanvraag afkomstig is van de gebruikersmodus, kan het stuurprogramma IWDFIoRequest2::IsFromUserModeDriver aanroepen om te bepalen of de aanvraag afkomstig is van een toepassing of een ander stuurprogramma voor de gebruikersmodus.

Beperkingen voor kernelmodusstuurprogramma's

Een UMDF-stuurprogramma kan I/O-aanvragen van een kernelmodusstuurprogramma alleen verwerken als het stuurprogramma voor de kernelmodus voldoet aan de volgende vereisten:

  • Het stuurprogramma voor de kernelmodus moet worden uitgevoerd op IRQL = PASSIVE_LEVEL wanneer de I/O-aanvraag wordt verzonden.

  • Tenzij het stuurprogramma de UmdfFileObjectPolicy INF-instructie heeft ingesteld op AllowNullAndUnknownFileObjects, moet elke I/O-aanvraag die een kernelmodusstuurprogramma naar een stuurprogramma in de gebruikersmodus verzendt, een gekoppeld bestandsobject hebben. Het framework moet van tevoren zijn geïnformeerd dat de I/O-manager het bestandsobject heeft gemaakt. (Deze melding zorgt ervoor dat het framework de callback-functie IQueueCallbackCreate::OnCreateFile van het stuurprogramma in de gebruikersmodus aanroept, maar die callback-functie is optioneel.)

  • De I/O-aanvraag kan geen IRP_MJ_INTERNAL_DEVICE_CONTROL functiecode bevatten.

  • De buffers van het I/O-verzoek mogen geen aanwijzers naar aanvullende informatie bevatten, omdat het stuurprogramma voor de gebruikersmodus de aanwijzers niet kan derefereren.

  • Als de I/O-aanvraag een I/O-besturingscode bevat die de 'geen' buffertoegangsmethode aangeeft, moet het stuurprogramma voor kernelmodus de I/O-aanvraag verzenden in de procescontext van de toepassing die de I/O-aanvraag heeft gemaakt. Zie voor meer informatie over het ondersteunen van de methode 'geen van beide' in een UMDF-basisstuurprogramma Geen gebufferde I/O of Directe I/O gebruiken in UMDF-stuurprogramma's.

  • Het UMDF-stuurprogramma kan de uitvoergegevens van een I/O-aanvraag wijzigen in de gebruikersmodus. Daarom moet het stuurprogramma voor de kernelmodus alle uitvoergegevens valideren die het ontvangt van het stuurprogramma voor de gebruikersmodus.

  • De kernelmodus-client moet typisch de Information-waarde valideren die een UMDF-stuurprogramma doorgeeft aan IWDFIoRequest::CompleteWithInformation. Als de client een KMDF-stuurprogramma is, kan deze WdfRequestGetCompletionParams aanroepen om deze informatie te verkrijgen in een IO_STATUS_BLOCK structuur.

    Over het algemeen valideert het framework niet de waarde van de informatie die een UMDF-stuurprogramma doorgeeft aan IWDFIoRequest::CompleteWithInformation. (Met deze parameter wordt meestal het aantal overgedragen bytes opgegeven.) Het framework valideert de informatiewaarde alleen voor uitvoerbuffers en alleen voor de gebufferde I/O- methode voor gegevenstoegang. (Het framework controleert bijvoorbeeld of het aantal overgedragen bytes niet groter is dan de uitvoerbuffergrootte van een leesbewerking, als de toegangsmethode is gebufferd I/O.)

Retourstatuswaarden verwerken in een UMDF 1.x-stuurprogramma

Voor het doorgeven van retourstatuswaarden van de gebruikersmodus aan kernelmodus is als volgt speciale aandacht vereist:

  • UMDF-versie 1-stuurprogramma's ontvangen doorgaans retourwaarden van HRESULT-type, terwijl KMDF- en WDM-stuurprogramma's op basis van kernelmodus doorgaans NTSTATUS-getypte waarden ontvangen. Als een UMDF 1.x stuurprogramma een I/O-aanvraag voltooit en als het stuurprogramma een kernelmodusclient heeft, moet de aanroep van het stuurprogramma naar IWDFIoRequest::Complete of IWDFIoRequest::CompleteWithInformation een HRESULT-waarde opgeven die het stuurprogramma genereert op basis van een NTSTATUS-waarde. Over het algemeen, UMDF 1.x stuurprogramma's moeten de HRESULT_FROM_NT macro gebruiken (gedefinieerd in Winerror.h) om de status terug te keren naar een kernelmodusclient. In het volgende voorbeeld ziet u hoe u deze macro gebruikt bij het voltooien van een aanvraag.

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

    Als u een specifieke HRESULT-waarde wilt retourneren aan een kernelmodusclient, moeten de volgende callbacks de HRESULT_FROM_NT macro gebruiken:

    Als u de NTSTATUS-waarden wilt gebruiken die zijn gedefinieerd in ntstatus.h, een UMDF 1.x stuurprogramma moet deze twee regels bevatten voordat u extra headers opneemt.

    #define UMDF_USING_NTSTATUS
#include <ntstatus.h>

    Gebruik de macro HRESULT_FROM_NT niet om STATUS_SUCCESS van een NTSTATUS-waarde te converteren naar een HRESULT-waarde. Retourneer S_OK, zoals wordt weergegeven in het volgende voorbeeld.

    request->Complete(S_OK);

  • Het framework voltooit enkele I/O-aanvragen namens UMDF-stuurprogramma's. Soms converteert het framework geen geretourneerde HRESULT-waarden naar gelijkwaardige NTSTATUS-waarden, waardoor het framework mogelijk een HRESULT-getypeerde voltooiingsstatus doorgeeft aan een kernel-modus-client.

    Vanwege deze situatie mogen clients in de kernelmodus de NT_ERROR macro niet gebruiken bij het testen van de voltooiingsstatus van een I/O-aanvraag, omdat de NT_ERROR macro niet TRUE- retourneert voor HRESULT-foutwaarden. Stuurprogramma's in de kernelmodus moeten de NT_SUCCESS macro gebruiken bij het testen van de voltooiingsstatus van een I/O-aanvraag.

clientondersteuning voor kernelmodus in eerdere UMDF-versies

Voor UMDF-versies ouder dan versie 1.9 kan het INF-bestand van een stuurprogramma een INF AddReg-directive bevatten om een REG_DWORD-grootte UpperDriverOk registerwaarde te creëren onder de WUDF-subsleutel van de hardwaresleutel van het apparaat.

Als de registerwaarde UpperDriverOk is ingesteld op een niet-nulnummer, kunnen stuurprogramma's in de kernelmodus boven het stuurprogramma voor de gebruikersmodus worden geladen. De stuurprogramma's in de kernelmodus kunnen I/O-aanvragen van toepassingen in de gebruikersmodus doorsturen naar het UMDF-stuurprogramma, maar kernelmodusstuurprogramma's kunnen geen I/O-aanvragen verzenden die in de kernelmodus zijn gemaakt naar het UMDF-stuurprogramma.

Voor UMDF-versies 1.9 en hoger is de registerwaarde UpperDriverOk verouderd en alleen ondersteund voor bestaande stuurprogramma's. Nieuwe stuurprogramma's moeten de instructie UmdfKernelModeClientPolicy gebruiken.