EVT_WDF_DEVICE_PREPARE_HARDWARE fonction de rappel (wdfdevice.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La fonction de rappel d’événement EvtDevicePrepareHardware d’un pilote effectue toutes les opérations nécessaires pour rendre un appareil accessible au pilote.

Syntaxe

EVT_WDF_DEVICE_PREPARE_HARDWARE EvtWdfDevicePrepareHardware;

NTSTATUS EvtWdfDevicePrepareHardware(
  [in] WDFDEVICE Device,
  [in] WDFCMRESLIST ResourcesRaw,
  [in] WDFCMRESLIST ResourcesTranslated
)
{...}

Paramètres

[in] Device

Handle d’un objet d’appareil framework.

[in] ResourcesRaw

Handle d’un objet de liste de ressources d’infrastructure qui identifie les ressources matérielles brutes que le gestionnaire de Plug-and-Play a attribuées à l’appareil.

[in] ResourcesTranslated

Handle d’un objet de liste de ressources d’infrastructure qui identifie les ressources matérielles traduites que le gestionnaire de Plug-and-Play a attribuées à l’appareil.

Valeur retournée

Si la fonction de rappel EvtDevicePrepareHardware ne rencontre aucune erreur, elle doit retourner STATUS_SUCCESS ou une autre valeur status pour laquelle NT_SUCCESS(status) est égal à TRUE. Sinon, il doit retourner une valeur status pour laquelle NT_SUCCESS(status) est false. Ne retournez pas STATUS_NOT_SUPPORTED.

Si NT_SUCCESS(status) est égal à FALSE, l’infrastructure appelle la fonction de rappel EvtDeviceReleaseHardware du pilote.

Pour plus d’informations sur les valeurs de retour de cette fonction de rappel, consultez Signalement des échecs d’appareil.

Remarques

Pour inscrire une fonction de rappel EvtDevicePrepareHardware , un pilote doit appeler WdfDeviceInitSetPnpPowerEventCallbacks.

Si le pilote a inscrit une fonction de rappel EvtDevicePrepareHardware pour un appareil, l’infrastructure appelle la fonction après que le gestionnaire de Plug-and-Play a affecté des ressources matérielles à l’appareil et que l’appareil a entré son état D0 non initialisé. (Le gestionnaire de Plug-and-Play démarre toujours un appareil parent avant de démarrer les appareils enfants de cet appareil.)

Le framework appelle la fonction de rappel EvtDevicePrepareHardware du pilote avant d’appeler la fonction de rappel EvtDeviceD0Entry du pilote.

La fonction de rappel EvtDevicePrepareHardware accède aux ressources matérielles brutes et traduites de l’appareil à l’aide des handles ResourcesRaw et ResourcesTranslated qu’elle reçoit. La fonction de rappel peut appeler WdfCmResourceListGetCount et WdfCmResourceListGetDescriptor pour parcourir les listes de ressources. Cette fonction de rappel ne peut pas modifier les listes de ressources.

Pour plus d’informations sur les listes de ressources et l’ordre dans lequel les ressources apparaissent, consultez Ressources matérielles brutes et traduites.

En règle générale, la fonction de rappel EvtDevicePrepareHardware de votre pilote effectue les opérations suivantes, si nécessaire :

Mappe les adresses de mémoire physique aux adresses virtuelles afin que le pilote puisse accéder à la mémoire affectée à l’appareil
Détermine le numéro de révision de l’appareil
Configure les périphériques USB
Obtient des interfaces définies par le pilote à partir d’autres pilotes

Si vous le souhaitez, la fonction de rappel EvtDevicePrepareHardware de votre pilote peut mettre en file d’attente un élément de travail pour effectuer d’autres tâches de configuration nécessitant beaucoup de temps. L’utilisation d’un élément de travail pour de telles opérations peut vous assurer que le temps de démarrage de votre appareil n’augmente pas le temps de démarrage du système. Pour plus d’informations, consultez Utilisation d’éléments de travail d’infrastructure.

En règle générale, toutes les autres opérations d’initialisation matérielle, y compris le chargement du microprogramme, doivent avoir lieu chaque fois que l’appareil entre dans son état de fonctionnement (D0) et doivent donc avoir lieu dans la fonction de rappel EvtDeviceD0Entry du pilote.

Les handles ResourcesRaw et ResourcesTranslated que la fonction de rappel EvtDevicePrepareHardware reçoit restent valides jusqu’à ce que la fonction de rappel EvtDeviceReleaseHardware du pilote retourne.

Pour plus d’informations sur les ressources matérielles, consultez Ressources matérielles pour les pilotes Framework-Based.

Pour plus d’informations sur le moment où l’infrastructure appelle cette fonction de rappel, consultez Scénarios pnP et de gestion de l’alimentation.

Pour plus d’informations sur les pilotes qui fournissent cette fonction de rappel, consultez Prise en charge du PnP et de la gestion de l’alimentation dans les pilotes de fonction.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfdevice.h (include Wdf.h)
IRQL	PASSIVE_LEVEL

Voir aussi

EvtDeviceReleaseHardware

Partager via