EVT_ACX_CIRCUIT_PREPARE_HARDWARE fonction de rappel (acxcircuit.h)

  • Article

Le rappel EVT_ACX_CIRCUIT_PREPARE_HARDWARE est utilisé par le pilote pour ajouter des fonctionnalités lorsqu’un ACXCIRCUIT est en phase de préparation matérielle.

Syntaxe

EVT_ACX_CIRCUIT_PREPARE_HARDWARE EvtAcxCircuitPrepareHardware;

NTSTATUS EvtAcxCircuitPrepareHardware(
  WDFDEVICE Device,
  ACXCIRCUIT Circuit,
  WDFCMRESLIST ResourcesRaw,
  WDFCMRESLIST ResourcesTranslated
)
{...}

Paramètres

Device

Objet WDFDEVICE (décrit dans WDF - Résumé des objets Framework) associé à l’ACXCIRCUIT spécifié.

Circuit

Objet ACXCIRCUIT (décrit dans Résumé des objets ACX) dans la phase de préparation du matériel.

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. Pour plus d’informations sur les ressources brutes, consultez Ressources brutes et traduites.

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

Retourne STATUS_SUCCESS si l’appel a réussi. Sinon, il retourne un code d’erreur approprié. Pour plus d’informations, consultez Utilisation de valeurs NTSTATUS.

Remarques

Pour inscrire une fonction de rappel EvtAcxCircuitPrepareHardware, un pilote doit appeler la méthode AcxCircuitInitSetAcxCircuitPnpPowerCallbacks.

Si le pilote a inscrit une fonction de rappel EvtAcxCircuitPrepareHardware pour un ACXCIRCUIT, l’infrastructure ACX appelle la fonction après que l’infrastructure WDF a appelé la fonction de rappel EvtDevicePrepareHardware du pilote.

La fonction de rappel EvtAcxCircuitPrepareHardware 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 brutes et traduites.

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

  • Mappe les adresses de mémoire physique aux adresses virtuelles d’ACXCIRCUIT afin que le pilote puisse accéder à la mémoire affectée à l’appareil.
  • Si vous le souhaitez, la fonction de rappel EvtAcxCircuitPrepareHardware 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 EvtAcxCircuitPrepareHardware/EvtDevicePrepareHardware reçoit reste valide jusqu’à ce que la fonction de rappel EvtDeviceReleaseHardware du pilote retourne.

Si le pilote échoue au rappel EvtAcxCircuitPrepareHardware, l’objet ACXCIRCUIT est placé dans l’état en attente de suppression et les ACXSTREAMS associés sont arrêtés.

Pour plus d’informations sur les ressources matérielles, consultez Présentation des ressources matérielles.

Pour plus d’informations sur le moment où l’infrastructure ACX et WDF appellent ces fonctions 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 de PnP et gestion de l’alimentation dans le pilote de fonction.

Exemple

L’exemple d’utilisation est illustré ci-dessous.

NTSTATUS
EvtCircuitPrepareHardware(
    _In_ WDFDEVICE      Device,
    _In_ ACXCIRCUIT     Circuit,
    _In_ WDFCMRESLIST   ResourcesRaw,
    _In_ WDFCMRESLIST   ResourcesTranslated
    )
{
    NTSTATUS            status      = STATUS_SUCCESS;
    PCIRCUIT_CONTEXT    circuitCtx  = GetCircuitContext(Circuit);
    CIpcEventReader *   eventReader = circuitCtx->EventReader;

    PASSIVE_CODE();

    UNREFERENCED_PARAMETER(Device);
    UNREFERENCED_PARAMETER(ResourcesRaw);
    UNREFERENCED_PARAMETER(ResourcesTranslated);

    //
    // Enable 'remote' circuit notifications.
    //
    ASSERT(eventReader);
    status = eventReader->EnableEvents();
    if (!NT_SUCCESS(status))
    {
        DrvLogError(g_RecorderLog, FLAG_INIT,
                    "ACXCIRCUIT %p, CIpcEventReader::EnableEvents failed, %!STATUS!",
                    Circuit, status);
        goto exit;
    }

    status = STATUS_SUCCESS;

exit:
    return status;
}

Configuration requise d’ACX

Version minimale d’ACX : 1.0

Pour plus d’informations sur les versions d’ACX, consultez Vue d’ensemble des versions d’ACX.

Configuration requise

Condition requise Valeur
En-tête acxcircuit.h
IRQL PASSIVE_LEVEL

Voir aussi