Énumération dynamique

L’énumération dynamique est la capacité d’un pilote à détecter et à signaler les modifications apportées au nombre et au type d’appareils connectés au système pendant l’exécution du système.

Les pilotes de bus doivent utiliser l’énumération dynamique si le nombre ou les types d’appareils connectés à l’appareil parent dépendent de la configuration d’un système. Certains de ces appareils peuvent toujours être connectés au système, et certains peuvent être branchés et déconnectés pendant l’exécution du système.

Par exemple, le nombre et le type d’appareils branchés dans le bus PCI d’un système dépendent du système, mais ils sont permanents, sauf si un utilisateur désactive l’alimentation, ouvre le cas et ajoute ou supprime un appareil à l’aide d’un tournevis. En revanche, un utilisateur peut ajouter ou supprimer des périphériques USB en branchant ou en débranchant un câble pendant l’exécution du système.

Listes enfants dynamiques

Le cadre permet aux pilotes de prendre en charge l’énumération dynamique en fournissant des objets de liste enfant du cadre. Chaque objet de liste enfant représente une liste d’appareils enfants connectés à un appareil parent. Le pilote de bus de l'appareil parent doit identifier les appareils enfants associés au parent, les ajouter à la liste des enfants de l'appareil parent, et créer un objet d'appareil physique (PDO) pour chaque enfant.

Chaque fois qu’un pilote crée un objet périphérique de framework qui représente un FDO pour un périphérique, le framework crée une liste enfant vide et par défaut pour le périphérique. Votre pilote peut obtenir un handle à la liste enfant par défaut d'un appareil en appelant WdfFdoGetDefaultChildList. En règle générale, si vous écrivez un pilote de bus qui énumère les enfants d’un appareil, votre pilote peut ajouter des enfants à la liste enfant par défaut. Si vous devez créer des listes enfants supplémentaires, votre pilote peut appeler WdfChildListCreate.

Pour qu’un pilote puisse utiliser une liste enfant, il doit configurer l’objet de liste enfant en initialisant une structure WDF_CHILD_LIST_CONFIG et en passant la structure à WdfFdoInitSetDefaultChildListConfig, pour la liste enfant par défaut ou à WdfChildListCreate, pour des listes enfants supplémentaires.

Descriptions d'enfants dynamiques

Chaque fois qu’un pilote de bus identifie un appareil enfant, il doit ajouter la description de l’appareil enfant à une liste enfant. Une description enfant se compose d’une description d’identification requise et d’une description d’adresse facultative.

Description de l’identification Une description d’identification est une structure qui contient des informations qui identifient de manière unique chaque périphérique énuméré par le pilote. Le pilote définit cette structure, mais son premier membre doit être une structure WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER .

En règle générale, une description d’identification contient les chaînes d’identification d’appareil d’un appareil, éventuellement un numéro de série et des informations sur l’emplacement de l’appareil sur le bus, telles qu’un numéro d’emplacement.

Le pilote peut fournir l’ensemble suivant de fonctions de rappel, ce qui permet au framework de manipuler les informations dans une description d’identification :

• EvtChildListIdentificationDescriptionCompare, qui compare le contenu de deux structures de description d’identification.

• EvtChildListIdentificationDescriptionCopy, qui copie le contenu d’une structure de description d’identification vers une autre.

• EvtChildListIdentificationDescriptionDuplicate, qui crée une nouvelle description d’identification en dupliquant une structure de description d’identification existante et, si nécessaire, en allouant des mémoires tampons supplémentaires.

• EvtChildListIdentificationDescriptionCleanup, qui libère les mémoires tampons allouées par la fonction de rappel EvtChildListIdentificationDescriptionDuplicate .

En règle générale, vous devez fournir ces fonctions de rappel si les structures de description d’identification de votre pilote contiennent des pointeurs vers des mémoires tampons allouées dynamiquement. Pour plus d’informations sur l’objectif de ces fonctions de rappel, consultez leurs pages de référence.

Description de l’adresse Une description d’adresse est une structure qui contient des informations dont le pilote a besoin pour accéder à l’appareil sur son bus, si les informations peuvent changer pendant que l’appareil est branché. Le pilote définit cette structure, mais son premier membre doit être une structure WDF_CHILD_ADDRESS_DESCRIPTION_HEADER .

Les descriptions d’adresses sont facultatives. Si les informations d’adresse d’un appareil ne peuvent pas changer entre le moment où l’appareil est branché et le moment où il est déconnecté, toutes les informations d’adresse de l’appareil peuvent être stockées dans une description d’identification. Par exemple, les contrôleurs USB attribuent des adresses à des appareils lorsque les appareils sont branchés, et ces adresses ne changent pas.

D’autre part, certains bus utilisent des informations d'adressage qui peuvent changer. Par exemple, le bus IEEE 1394 utilise un « nombre de génération », qui correspond au nombre de réinitialisations de bus qui se sont produites. Chaque requête d’E/S asynchrone adressée à un appareil IEEE 1394 doit inclure le nombre de génération. Étant donné que ces informations d’adresse peuvent changer, votre pilote doit le stocker dans une description d’adresse.

Pour manipuler les informations dans une description d’adresse, le pilote peut fournir l’ensemble suivant de fonctions de rappel :

• EvtChildListAddressDescriptionCopy, qui copie le contenu d’une structure de description d’adresse vers une autre.

• EvtChildListAddressDescriptionDuplicate, qui crée une description d’adresse en dupliquant une structure de description d’adresse existante et, si nécessaire, en allouant des mémoires tampons supplémentaires.

• EvtChildListAddressDescriptionCleanup, qui libère les mémoires tampons que la fonction de rappel EvtChildListAddressDescriptionDuplicate a allouées.

En règle générale, vous devez fournir ces fonctions de rappel si les structures de description d’adresse de votre pilote contiennent des pointeurs vers des mémoires tampons allouées dynamiquement. Pour plus d’informations sur l’objectif de ces fonctions de rappel, consultez leurs pages de référence.

Ajout d’appareils à une liste enfant dynamique

Lorsque l’infrastructure appelle la fonction de rappel EvtDriverDeviceAdd d’un pilote bus, la fonction de rappel doit appeler WdfDeviceCreate pour créer une FDO pour l’appareil parent, qui est généralement un adaptateur de bus. Pour plus d’informations sur la création d’un FDO, consultez Création d’objets d’appareil dans un pilote de fonction. Le pilote doit ensuite énumérer les enfants du périphérique parent et ajouter les enfants à une liste enfant.

Si vous le souhaitez, le pilote peut appeler WdfDeviceSetBusInformationForChildren pour fournir au framework des informations sur le bus. Nous vous recommandons de le faire, car il facilite l’identification du bus pour les appareils et applications enfants.

Pour ajouter des enfants à une liste enfant, le pilote doit appeler WdfChildListAddOrUpdateChildDescriptionAsPresent pour chaque appareil enfant qu’il trouve. Cet appel informe le framework qu’un pilote a découvert un dispositif enfant connecté à un dispositif parent. Lorsque votre pilote appelle WdfChildListAddOrUpdateChildDescriptionAsPresent, il fournit une description d’identification et, éventuellement, une description d’adresse.

Une fois que le pilote appelle WdfChildListAddOrUpdateChildDescriptionAsPresent pour signaler un nouvel appareil, l’infrastructure informe le gestionnaire PnP que le nouvel appareil existe. Le gestionnaire PnP génère une pile d’appareils et une pile de pilotes pour le nouvel appareil. Dans le cadre de ce processus, le cadre appelle la fonction de rappel EvtChildListCreateDevice du pilote de bus. Cette fonction de rappel doit appeler WdfDeviceCreate pour créer une PDO pour le nouvel appareil.

En règle générale, plusieurs périphériques enfants sont connectés à un parent. Le pilote de bus doit donc appeler WdfChildListAddOrUpdateChildDescriptionAsPresent plusieurs fois. La méthode la plus efficace pour effectuer ce processus est la suivante :

1. Appelez WdfChildListBeginScan.

2. Appelez WdfChildListAddOrUpdateChildDescriptionAsPresent pour chaque périphérique enfant.

3. Appelez WdfChildListEndScan.

Si vous entourez l’énumération dynamique de votre pilote avec des appels à WdfChildListBeginScan et WdfChildListEndScan, le framework stocke toutes les modifications de la liste des enfants. Il avertit le gestionnaire PnP des modifications lorsque le pilote appelle WdfChildListEndScan. À un moment donné, le framework appelle la fonction de rappel EvtChildListCreateDevice du pilote bus pour chaque périphérique de la liste de périphériques enfants. Cette fonction de rappel appelle WdfDeviceCreate pour créer un PDO pour chaque nouvel appareil.

Lorsque votre pilote appelle WdfChildListBeginScan, l’infrastructure marque tous les appareils signalés précédemment comme n’étant plus présents. Par conséquent, le pilote doit appeler WdfChildListAddOrUpdateChildDescriptionAsPresent pour tous les enfants que le pilote peut détecter, pas seulement les enfants nouvellement découverts. Pour ajouter un enfant unique à une liste enfant, le pilote peut effectuer un seul appel à WdfChildListUpdateAllChildDescriptionsAsPresent sans appeler WdfChildListBeginScan.

Mise à jour d’une liste enfant dynamique

Pour mettre à jour les informations d’une liste enfant dynamique, utilisez l’une des méthodes suivantes :

1. Lorsqu’un appareil parent reçoit une interruption qui indique l’arrivée ou la suppression d’un enfant, la fonction de rappel EvtInterruptDpc du pilote appelle WdfChildListAddOrUpdateChildDescriptionAsPresent si un appareil est branché ou WdfChildListUpdateChildDescriptionAsMissing si un appareil est déconnecté.

2. Le pilote peut fournir une fonction de rappel EvtChildListScanForChildren , que l’infrastructure appelle chaque fois que l’appareil parent entre dans son état de travail (D0). Cette fonction de rappel doit énumérer tous les appareils enfants en appelant WdfChildListBeginScan, WdfChildListAddOrUpdateChildDescriptionAsPresent (ou WdfChildListUpdateAllChildDescriptionsAsPresent) et WdfChildListEndScan.

Vous pouvez utiliser une ou ces deux techniques dans votre pilote.

Parcourir une liste enfant dynamique

Pour examiner le contenu d’une liste enfant, votre pilote peut parcourir la liste à l’aide de l’une des techniques suivantes :

• Pour obtenir le contenu de chaque description de périphérique enfant, un par un, le pilote peut :

  1. Appelez WdfChildListBeginIteration.
  2. Appelez WdfChildListRetrieveNextDevice, autant de fois que nécessaire.
  3. Appelez WdfChildListEndIteration.

  Lors de l’appel de WdfChildListBeginIteration, le pilote spécifie un drapeau de type WDF_RETRIEVE_CHILD_FLAGS qui indique si le framework doit récupérer toutes les descriptions d’appareil ou uniquement un sous-ensemble. Lorsque WdfChildListRetrieveNextDevice trouve une correspondance, il récupère les descriptions d’identification et d’adresse du périphérique enfant, ainsi qu’un handle pour son objet périphérique.

• Pour obtenir la description de l’adresse actuellement contenue dans une description de périphérique enfant, votre pilote peut appeler WdfChildListRetrieveAddressDescription, en spécifiant une description d’identification. Le framework traverse la liste enfant jusqu’à ce qu’il trouve un appareil enfant avec une description d’identification correspondante. Il récupère ensuite la description de l’adresse.

• Si vous devez obtenir un handle pour l’objet d’appareil framework associé à un périphérique enfant particulier, votre pilote peut appeler WdfChildListRetrievePdo. Le framework traverse la liste des enfants jusqu'à ce qu'il trouve un périphérique enfant avec une description d'identification correspondante, puis retourne un descripteur d'objet de périphérique. Pour protéger l’appelant contre la suppression soudaine de PnP du PDO sur un autre thread, encapsulez l’appel avec WdfChildListBeginIteration et WdfChildListEndIteration.

Accès aux descriptions d’identification et d’adresse d’un PDO

Votre pilote peut appeler les méthodes suivantes pour accéder à la description d'identification ou à la description d'adresse d'un PDO :

• WdfPdoRetrieveIdentificationDescription, qui récupère la description d’identification associée à une PDO.

• WdfPdoRetrieveAddressDescription, qui récupère la description de l’adresse associée à un PDO.

• WdfPdoUpdateAddressDescription, qui met à jour la description de l’adresse associée à une PDO.

Gestion des demandes de réénumération

Les pilotes de bus basés sur l’infrastructure qui prennent en charge l’énumération dynamique peuvent recevoir une demande de réenumérer un appareil enfant particulier via l’interface REENUMERATE_SELF_INTERFACE_STANDARD. Pour plus d’informations, consultez Gestion des demandes d’énumération.