Gestion de la durée de vie des pilotes WDF ou ACX

Article
05/27/2024

Cette rubrique propose un résumé de la gestion de la durée de vie du pilote ACX WDF et du nettoyage approprié de la mémoire. Pour une vue d’ensemble générale d’ACX, veuillez consulter la section vue d’ensemble des extensions audio de classe ACX.

Remarque

Les en-têtes et bibliothèques ACX ne sont pas inclus dans le WDK 10.0.22621.2428 (publié le 24 octobre 2023), mais sont disponibles dans les versions précédentes, ainsi que dans la dernière version de prévisualisation (séries 25000) du WDK. Pour plus d’informations sur les versions de prévisualisation du WDK, veuillez consulter la section Installation des versions de prévisualisation du Windows Driver Kit (WDK).

Initialisation et démarrage ACX WDF

Une initialisation correcte d’ACX doit se produire pour permettre un nettoyage approprié des ressources ACX, WDF et de la mémoire. Des détails supplémentaires sur les principales phases de l’énumération des appareils, résumées ici, sont disponibles dans la section Énumération des appareils ACX.

Entrée du pilote WDM
Ajout de périphérique WDF
Préparation du matériel WDF
Entrée du périphérique WDF D0
Processus de création de circuit ACX (les objets Pins et Jacks ACX sont associés au circuit)
Processus de création de flux ACX

Nettoyage des objets ACX WDF

Cette rubrique décrit le nettoyage des objets ACX WDF dans cet ordre.

Processus de fermeture de flux ACX
Processus de suppression de circuit ACX
Libération du matériel de l’appareil WDF
Déchargement du pilote WDF

Il existe plusieurs approches valides pour créer et nettoyer les objets WDF et ACX. Ce sujet couvre certains éléments clés de la gestion de la durée de vie des objets ACX/WDF.

Événements de puissance PnP et destruction d’objets

Les événements de puissance PnP peuvent provoquer la création et la destruction d’objets. Pour plus d’informations sur les événements de puissance PnP, veuillez consulter les sections Gestion de l’alimentation ACX et PNP et séquences de rappel de gestion de l’alimentation.

Gestion de la durée de vie des références d’objets WDF

WDF utilise des comptes de référence pour aider à suivre la durée de vie des objets. Il peut être approprié dans une fonction de rappel de nettoyage de déréférencer les références d’objet. Le framework appelle cette fonction de rappel de nettoyage pour que le pilote puisse appeler WdfObjectDereference s’il avait précédemment appelé WdfObjectReference pour l’objet en cours de suppression. Pour plus d’informations, veuillez consulter les sections WdfObjectReference et WdfObjectDereference.

Bonnes pratiques de développement de pilotes de l’équipe Surface

Pour une description des erreurs courantes dans le code des pilotes concernant la gestion de la mémoire et de la durée de vie des objets, consultez les sections correspondantes dans les bonnes pratiques de développement de pilotes de l’équipe Surface.

Processus de fermeture de flux ACX

Lorsque le client ferme le flux, le pilote doit travailler à fermer et nettoyer les ressources associées au flux. Pour plus de détails, consultez la section ACX Streaming - Processus de fermeture du flux. Il est important que le pilote ne nettoie pas les ressources qui soutiennent le flux et que le processus de nettoyage soit conscient des impacts sur le client.

Processus de suppression de circuit ACX

ACX peut créer un circuit dynamique à la demande. Pour ce faire, le pilote alloue une structure WDFDEVICE_INIT en appelant WdfPdoInitAllocate. Le pilote spécifie ensuite tous les rappels PnP/power qu’il souhaite recevoir et crée le périphérique. Le pilote invoque AcxDeviceRemoveCircuitDevice pour retirer le périphérique audio de la liste des périphériques.

Pour plus d’informations, veuillez consulter la section Suppression dynamique de circuit ACX dans Circuits ACX.

Libération du matériel de l’appareil WDF

La fonction de rappel EVT_WDF_DEVICE_RELEASE_HARDWARE est utilisée dans la fonction de rappel d’événement EvtDeviceReleaseHardware d’un pilote pour effectuer les opérations nécessaires lorsqu’un périphérique n’est plus accessible.

Nettoyage du contexte de périphérique WDF

Ce code de l’exemple AudioCodec montre l’utilisation d’une structure WDF_OBJECT_ATTRIBUTES pour définir un EvtCleanupCallback.

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, CODEC_DEVICE_CONTEXT);
    attributes.EvtCleanupCallback = Codec_EvtDeviceContextCleanup;

Cet exemple de rappel, donné à un WdfDevice, nettoie le contexte du périphérique.

VOID
Codec_EvtDeviceContextCleanup(
    _In_ WDFOBJECT      WdfDevice
)

{
    WDFDEVICE               device;
    PCODEC_DEVICE_CONTEXT   devCtx;

    device = (WDFDEVICE)WdfDevice;
    devCtx = GetCodecDeviceContext(device);
    ASSERT(devCtx != nullptr);

    if (devCtx->Capture)
    {
        CodecC_CircuitCleanup(devCtx->Capture);
    }
}

Déchargement du pilote WDF

Lorsque le pilote est déchargé, il doit libérer toutes les ressources restantes. Pour plus d’informations, veuillez consulter la section Libération des ressources allouées par le pilote.

Un pilote enregistre une fonction de rappel EvtDriverUnload lorsqu’il appelle WdfDriverCreate. La fonction de rappel EvtDriverUnload doit désallouer toutes les ressources système non spécifiques au périphérique que la routine DriverEntry du pilote a allouées. Pour plus d’informations, veuillez consulter la section Fonction de rappel EVT_WDF_DRIVER_UNLOAD.

Cet exemple de code AudioCodec montre la structure d’un rappel de déchargement de pilote.

EVT_WDF_DRIVER_UNLOAD               AudioCodecDriverUnload;

void AudioCodecDriverUnload(
    _In_ WDFDRIVER Driver
)
{
    PAGED_CODE();

    if (!Driver)
    {
        ASSERT(FALSE);
        return;
    }

    WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver));

// Here is where you would cleanup any allocated resources associated with the driver.

    return;
}