AddDevice-routines in functie- of filterstuurprogramma's

Een AddDevice-routine in een functie of filterstuurprogramma moet de volgende stappen uitvoeren:

1. Roep IoCreateDevice aan om een functioneel of filterapparaatobject (een FDO of filter DO) te maken voor het apparaat dat wordt toegevoegd.

   Geef geen DeviceName op voor het apparaatobject, omdat hierdoor de beveiliging van de PnP-manager wordt overgeslagen. Als een gebruikersmodusonderdeel een symbolische koppeling naar het apparaat nodig heeft, registreert u een apparaatinterface (zie de volgende stap hieronder). Als een kernelmodusonderdeel een verouderde apparaatnaam nodig heeft, moet het stuurprogramma het apparaatobject een naam geven, maar wordt de naamgeving niet aanbevolen.

   Neem FILE_DEVICE_SECURE_OPEN op in de parameter DeviceCharacteristics. Met deze eigenschap wordt de I/O-manager verzocht beveiligingscontroles uit te voeren op het apparaatobject voor alle openingsverzoeken, inclusief relatieve openingen en openingen met een volgnaam.

2. [optioneel] Maak een of meer symbolische koppelingen naar het apparaat.

   Roep IoRegisterDeviceInterface aan om apparaatfunctionaliteit te registreren en een symbolische koppeling te maken die toepassingen of systeemonderdelen kunnen gebruiken om het apparaat te openen. Het stuurprogramma moet de interface inschakelen door IoSetDeviceInterfaceState aan te roepen wanneer deze de IRP_MN_START_DEVICE aanvraag verwerkt. Zie Device Interface Classesvoor meer informatie.

3. Sla de aanwijzer op de PDO van het apparaat op in de apparaatextensie.

   De PnP-manager levert een aanwijzer naar de PDO als de parameter PhysicalDeviceObject aan AddDevice. Stuurprogramma's gebruiken de PDO-aanwijzer in aanroepen naar routines zoals IoGetDeviceProperty.

4. Definieer vlaggen in de apparaatextensie om bepaalde PnP-statussen van het apparaat bij te houden, zoals het apparaat gepauzeerd, verwijderd, en onverwacht verwijderd.

   Definieer bijvoorbeeld één vlag om aan te geven dat binnenkomende IRP's moeten worden bewaard terwijl het apparaat in een onderbroken toestand is. Maak een wachtrij voor het opslaan van IR's als het stuurprogramma nog geen mechanisme voor wachtrijen van IR's heeft. Zie IRP's in de wachtrij plaatsen en verwijderen uit de wachtrij voor meer informatie.

   Wijs ook een IO_REMOVE_LOCK structuur toe in de apparaatextensie en roep IoInitializeRemoveLock aan om deze structuur te initialiseren. Zie Vergrendelingen verwijderen gebruiken voor meer informatie.

5. Stel de DO_BUFFERED_IO of DO_DIRECT_IO vlag-bit in het apparaatobject in om het type buffer op te geven dat de I/O-manager moet gebruiken voor I/O-aanvragen die naar de apparaatstack worden verzonden. Stuurprogramma's op een hoger niveau OF deze parameter heeft dezelfde waarde als het volgende lagere stuurprogramma in de stack, met uitzondering van stuurprogramma's op het hoogste niveau. Zie Initialiseren van een apparaatobjectvoor meer informatie.

6. Stel indien nodig de vlag DO_POWER_INRUSH of DO_POWER_PAGABLE in voor energiebeheer. Stuurprogramma's die paginabaar zijn, moeten de vlag DO_POWER_PAGABLE instellen. De objectvlagken van het apparaat worden doorgaans ingesteld door het busstuurprogramma wanneer de PDO voor het apparaat wordt gemaakt. Stuurprogramma's op een hoger niveau moeten echter soms de waarden van deze vlaggen wijzigen in hun AddDevice routines wanneer ze de FDO of de filter DO aanmaken. Zie Apparaatobjectvlagmen instellen voor Energiebeheer voor meer informatie.

7. Maak en/of initialiseer andere softwarebronnen die het stuurprogramma gebruikt om dit apparaat te beheren, zoals gebeurtenissen, kringvergrendelingen of andere objecten. (Hardwareresources, zoals I/O-poorten, worden later geconfigureerd als reactie op een IRP_MN_START_DEVICE aanvraag.)

   Omdat een AddDevice-routine wordt uitgevoerd in een systeemthreadcontext op IRQL = PASSIVE_LEVEL, kan elk geheugen dat is toegewezen met ExAllocatePoolWithTag , exclusief worden gebruikt tijdens de initialisatie, afkomstig zijn van een gepaginade pool, zolang het stuurprogramma niet het apparaat beheert dat het systeempaginabestand bevat. Een dergelijke geheugentoewijzing moet worden vrijgegeven met ExFreePool voordat AddDevice de controle teruggeeft.

8. Koppel het apparaatobject aan de apparaatstack (IoAttachDeviceToDeviceStack).

   Geef een aanwijzer op naar de PDO van het apparaat in de parameter TargetDevice .

   Sla de aanwijzer op die is geretourneerd door IoAttachDeviceToDeviceStack. Deze aanwijzer, die verwijst naar het apparaatobject van het volgende lagere stuurprogramma voor het apparaat, is een vereiste parameter voor IoCallDriver en PoCallDriver bij het doorgeven van IRPs omlaag in de apparaatstack.

9. Wis de DO_DEVICE_INITIALIZING vlag in de FDO of filter DO met een instructie zoals hieronder:

   FunctionalDeviceObject->Flags &= ~DO_DEVICE_INITIALIZING;
   

10. Wees voorbereid op het verwerken van PnP-IR's voor het apparaat (zoals IRP_MN_QUERY_RESOURCE_REQUIREMENTS en IRP_MN_START_DEVICE).

Een stuurprogramma mag het apparaat pas beheren nadat het een IRP_MN_START_DEVICE ontvangt met de lijst met hardwarebronnen die door de PnP-manager aan het apparaat zijn toegewezen.