GPIO_CLIENT_PREPARE_CONTROLLER fonction de rappel (gpioclx.h)

Article
02/07/2025

La fonction de rappel d’événement CLIENT_PrepareController effectue toutes les opérations nécessaires pour rendre le contrôleur d’E/S universel (GPIO) prêt à être accessible par le pilote du contrôleur GPIO.

Syntaxe

GPIO_CLIENT_PREPARE_CONTROLLER GpioClientPrepareController;

NTSTATUS GpioClientPrepareController(
  [in] WDFDEVICE Device,
  [in] PVOID Context,
  [in] WDFCMRESLIST ResourcesRaw,
  [in] WDFCMRESLIST ResourcesTranslated
)
{...}

Paramètres

[in] Device

Handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur GPIO.

[in] Context

Pointeur vers le contexte de périphérique du pilote de contrôleur GPIO.

[in] ResourcesRaw

Handle WDFCMRESLIST vers une collection d’objets de ressource framework. Cette collection identifie les ressources matérielles brutes (relatives aux bus) affectées par le gestionnaire Plug-and-Play (PnP) à l’appareil du contrôleur GPIO.

[in] ResourcesTranslated

Handle WDFCMRESLIST vers une collection d’objets de ressource framework. Cette collection identifie les ressources matérielles traduites (physiques système) affectées par le gestionnaire PnP à l’appareil du contrôleur GPIO.

Valeur de retour

La fonction CLIENT_PrepareController retourne STATUS_SUCCESS si l’appel réussit. Sinon, elle retourne un code d’erreur approprié.

Remarques

Cette fonction de rappel est implémentée par le pilote du contrôleur GPIO. L’extension d’infrastructure GPIO (GpioClx) appelle cette fonction pour initialiser les ressources matérielles dont le pilote du contrôleur GPIO a besoin pour pouvoir accéder au périphérique du contrôleur GPIO.

Les paramètres ResourcesRaw et ResourcesTranslated sont gérés sur des listes de ressources brutes et traduites. Ces listes décrivent les ressources matérielles que le gestionnaire PnP a attribuées à l’appareil du contrôleur GPIO spécifié par le paramètre Appareil. Pour plus d’informations, consultez ressources brutes et traduites.

Pendant le rappel CLIENT_PrepareController, le pilote du contrôleur GPIO peut acquérir les ressources matérielles requises à partir de la liste ResourcesRaw ou ResourcesTranslated. Si le périphérique du contrôleur GPIO est mappé en mémoire, le pilote doit mapper la plage d’adresses mémoire relative au bus ou les plages affectées aux registres matériels de l’appareil aux adresses virtuelles système. Pour plus d’informations, consultez Mappage des adresses Bus-Relative aux adresses virtuelles.

Si le contrôleur GPIO n’est pas mappé en mémoire, les ressources matérielles du pilote contiennent un ID de connexion au lieu d’une plage de mémoire. Le pilote utilise cet ID pour ouvrir une connexion logique au contrôleur GPIO et envoie des demandes d’E/S via cette connexion pour accéder aux registres du contrôleur.

GpioClx se connecte à (et se déconnecte ultérieurement de) toute ressource d’interruption affectée par le gestionnaire PnP au contrôleur GPIO. Si GpioClx reçoit une telle ressource d’interruption, elle ne supprime pas cette ressource d’interruption des listes de ressources qu’elle transmet à la fonction de rappel CLIENT_PrepareController. Toutefois, le pilote du contrôleur GPIO ne doit pas essayer de se connecter à une ressource d’interruption (ou ultérieure) qu’il trouve dans ces listes.

La fonction de rappel d’événement CLIENT_ReleaseController effectue des opérations nécessaires lorsque l’appareil du contrôleur GPIO n’est plus accessible. Pendant ce rappel, le pilote du contrôleur GPIO doit libérer toutes les ressources matérielles qu’il a acquises au cours du rappel CLIENT_PrepareController précédent.

Pour inscrire la fonction de rappel CLIENT_PrepareController de votre pilote, appelez la méthode GPIO_CLX_RegisterClient. Cette méthode accepte, en tant que paramètre d’entrée, un pointeur vers une structure GPIO_CLIENT_REGISTRATION_PACKET qui contient un pointeur de fonction CLIENT_PrepareController.

Bien que la fonction de rappel CLIENT_PrepareController soit appelée à IRQL = PASSIVE_LEVEL, vous ne devez pas rendre cette fonction paginable. Le rappel CLIENT_PrepareController est dans le chemin de minutage critique pour restaurer la puissance sur les appareils de la plateforme matérielle et, pour des raisons de performances, il ne doit pas être retardé par les erreurs de page.

Exemples

Pour définir une fonction de rappel CLIENT_PrepareController, vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction de rappel CLIENT_PrepareController nommée MyEvtGpioPrepareController, utilisez le type de fonction GPIO_CLIENT_PREPARE_CONTROLLER, comme illustré dans cet exemple de code :

GPIO_CLIENT_PREPARE_CONTROLLER MyEvtGpioPrepareController;

Ensuite, implémentez votre fonction de rappel comme suit :

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioPrepareController(
    WDFDEVICE Device,
    PVOID Context,
    WDFCMRESLIST ResourcesRaw,
    WDFCMRESLIST ResourcesTranslated
)
{ ... }

Le type de fonction GPIO_CLIENT_PREPARE_CONTROLLER est défini dans le fichier d’en-tête Gpioclx.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction GPIO_CLIENT_PREPARE_CONTROLLER dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes KMDF. Pour plus d’informations sur Use_decl_annotations, consultez annoter le comportement de la fonction.