Partager via


EVT_ACX_CIRCUIT_PREPARE_HARDWARE fonction de rappel (acxcircuit.h)

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

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 vers un objet de liste de ressources d’infrastructure qui identifie les ressources matérielles brutes affectées par le gestionnaire Plug-and-Play à l’appareil. Pour plus d’informations sur les ressources brutes, consultez ressources brutes et traduites.

ResourcesTranslated

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

Valeur de retour

Retourne STATUS_SUCCESS si l’appel a réussi. Sinon, elle retourne un code d’erreur approprié. Pour plus d’informations, consultez Using NTSTATUS Values.

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 appelle la fonction 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’il 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 de l’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 ces opérations peut vous aider à garantir 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 des éléments de travail framework.
  • 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 travail (D0) et doit donc avoir lieu dans la fonction de rappel EvtDeviceD0Entry du pilote.

Les handles ResourcesRaw et ResourcesTranslated que la fonction de rappel EvtAcxServicesPrepareHardware/EvtDevicePrepareHardware reçoit reste valide jusqu’à ce que la fonction de rappel EvtDeviceReleaseHardware du pilote retourne.

Si le pilote échoue le rappel EvtAcxCircuitPrepareHardware, l’objet ACXCIRCUIT est placé dans l’état de suppression en attente et acXSTREAMS associé 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 Power Management.

Pour plus d’informations sur les pilotes qui fournissent cette fonction de rappel, consultez Prise en charge de PnP et de 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 pour ACX

version minimale d’ACX : 1.0

Pour plus d’informations sur les versions ACX, consultez vue d’ensemble de la version ACX.

Exigences

Exigence Valeur
d’en-tête acxcircuit.h
IRQL PASSIVE_LEVEL

Voir aussi