WdfInterruptCreate, fonction (wdfinterrupt.h)
[S’applique à KMDF et UMDF]
La méthode WdfInterruptCreate crée un objet d’interruption de framework.
Syntaxe
NTSTATUS WdfInterruptCreate(
[in] WDFDEVICE Device,
[in] PWDF_INTERRUPT_CONFIG Configuration,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFINTERRUPT *Interrupt
);
Paramètres
[in] Device
Handle pour un objet d’appareil d’infrastructure.
[in] Configuration
Pointeur vers une structure WDF_INTERRUPT_CONFIG initialisée par un appel à WDF_INTERRUPT_CONFIG_INIT.
[in, optional] Attributes
Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui spécifie des attributs d’objet pour l’objet d’interruption du framework. (Pour plus d’informations, voir Notes.) Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.
[out] Interrupt
Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet d’interruption.
Valeur retournée
WdfInterruptCreate retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes.
| Code de retour | Description |
|---|---|
|
La taille de la structure WDF_INTERRUPT_CONFIG est incorrecte. |
|
Un paramètre non valide a été spécifié. |
|
WdfInterruptCreate a été appelé après le démarrage de l’appareil. WdfInterruptCreate retourne également cette valeur si la routine de rappel EVT_WDF_DEVICE_PREPARE_HARDWARE du pilote appelle WdfInterruptCreate avec les membres InterruptRaw et InterruptTranslated de la structure WDF_INTERRUPT_CONFIG définis sur NULL. |
|
La mémoire était insuffisante. |
|
Dans KMDF version 1.9 ou antérieure, le pilote a spécifié une valeur non NULL pour le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES .
Dans KMDF version 1.11 ou ultérieure, le pilote a spécifié une valeur autre qu’un périphérique d’infrastructure ou une file d’attente pour le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES . |
|
Le membre AutomaticSerialization de la structure WDF_INTERRUPT_CONFIG est défini sur TRUE et :
|
|
Le pilote a demandé la gestion des interruptions au niveau passif sur une plateforme avant Windows 8. |
Pour obtenir la liste des autres valeurs de retour que la méthode WdfInterruptCreate peut retourner, consultez Erreurs de création d’objets framework.
Cette méthode peut également retourner d’autres valeurs NTSTATUS.
Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.
Remarques
Les pilotes appellent généralement la méthode WdfInterruptCreate à partir d’une fonction de rappel EvtDriverDeviceAdd . À partir de KMDF version 1.11 et UMDF version 2.0, les pilotes peuvent appeler WdfInterruptCreate à partir d’EvtDevicePrepareHardware. Si le pilote appelle WdfInterruptCreate à partir d’EvtDriverDeviceAdd, les membres InterruptRaw et InterruptTranslated de la structure WDF_INTERRUPT_CONFIG doivent avoir la valeur NULL. Si le pilote appelle WdfInterruptCreate à partir d’EvtDevicePrepareHardware, ces membres doivent tous deux être valides.
Si vous créez un objet d’interruption compatible avec la veille, comme décrit dans Utilisation d’une interruption pour réveiller un appareil, vous devez appeler WdfInterruptCreate à partir d’EvtDevicePrepareHardware.
Votre pilote doit appeler WdfInterruptCreate une fois pour chaque vecteur d’interruption requis par son appareil. Si l’appareil prend en charge les interruptions avec signal de message (MSI), le pilote doit créer un objet d’interruption pour chaque message que l’appareil peut prendre en charge.
Une fois que le gestionnaire PnP a affecté des ressources système à l’appareil, le framework stocke des informations sur les ressources d’interruption affectées à l’appareil dans les objets d’interruption que le pilote a créés. (Les pilotes qui ne prennent pas en charge Plug-and-Play ne peuvent pas utiliser d’objets d’interruption.)
Le système peut ne pas affecter toutes les ressources d’interruption qu’un appareil peut prendre en charge. Par exemple, un pilote crée huit objets d’interruption pour un appareil capable de prendre en charge huit messages MSI. Toutefois, le système ne peut affecter qu’un seul message à l’appareil. Dans ce cas, sept des objets d’interruption ne sont pas utilisés.
En règle générale, votre pilote doit stocker des informations spécifiques aux interruptions, telles que le contenu copié des registres d’interruption de périphérique, dans l’espace contextuel de l’objet d’interruption. La structure WDF_OBJECT_ATTRIBUTES que le pilote transmet à WdfInterruptCreate doit décrire l’espace de contexte.
Pour les pilotes utilisant le framework version 1.9 et antérieure, le parent de chaque objet d’interruption est l’objet de périphérique auquel appartient l’interruption. Le pilote ne peut pas modifier ce parent, et le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES doit avoir la valeur NULL. À compter de la version 1.11, ParentObject peut être un objet d’appareil d’infrastructure ou un objet de file d’attente. Si le pilote spécifie un parent, le pilote doit définir le membre AutomaticSerialization de la structure de configuration sur TRUE. Le pilote peut spécifier un parent pour les interruptions au niveau DIRQL et les interruptions passives.
Si votre pilote fournit des fonctions de rappel EvtCleanupCallback ou EvtDestroyCallback pour l’objet d’interruption du framework, notez que l’infrastructure appelle ces fonctions de rappel à l’adresse IRQL = PASSIVE_LEVEL.
Pour plus d’informations sur la gestion des interruptions dans les pilotes basés sur l’infrastructure, consultez Gestion des interruptions matérielles.
Exemples
L’exemple de code suivant initialise une structure WDF_INTERRUPT_CONFIG et une structure WDF_OBJECT_ATTRIBUTES, puis appelle WdfInterruptCreate.
NTSTATUS status;
WDF_INTERRUPT_CONFIG interruptConfig;
WDF_OBJECT_ATTRIBUTES interruptAttributes;
WDF_INTERRUPT_CONFIG_INIT(
&interruptConfig,
MyEvtInterruptIsr,
MyEvtInterruptDpc
);
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
&interruptAttributes,
INTERRUPT_DATA
);
status = WdfInterruptCreate(
device,
&interruptConfig,
&interruptAttributes,
&devExt->WdfInterrupt
);
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| Version KMDF minimale | 1.0 |
| Version UMDF minimale | 2.0 |
| En-tête | wdfinterrupt.h (inclure Wdf.h) |
| Bibliothèque | Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Règles de conformité DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |