EVT_ACX_CIRCUIT_PREPARE_HARDWARE コールバック関数 (acxcircuit.h)

  • [アーティクル]

EVT_ACX_CIRCUIT_PREPARE_HARDWARE コールバックは、ACXCIRCUIT がハードウェア準備フェーズにあるときに機能を追加するためにドライバーによって使用されます。

構文

EVT_ACX_CIRCUIT_PREPARE_HARDWARE EvtAcxCircuitPrepareHardware;

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

パラメーター

Device

指定した ACXCIRCUIT に関連付けられた WDFDEVICE オブジェクト (WDF - フレームワーク オブジェクトの概要に関するページで説明)。

Circuit

準備ハードウェア フェーズの ACXCIRCUIT オブジェクト ( ACX オブジェクトの概要に関するページで説明)。

ResourcesRaw

プラグ アンド プレイ マネージャーがデバイスに割り当てた未加工のハードウェア リソースを識別するフレームワーク リソースリスト オブジェクトへのハンドル。 生のリソースの詳細については、「 生および翻訳されたリソース」を参照してください。

ResourcesTranslated

プラグ アンド プレイ マネージャーがデバイスに割り当てた変換されたハードウェア リソースを識別するフレームワーク リソースリスト オブジェクトへのハンドル。

戻り値

STATUS_SUCCESS呼び出しが成功した場合は を返します。 それ以外の場合は、適切なエラー コードを返します。 詳細については、「 NTSTATUS 値の使用」を参照してください。

注釈

EvtAcxCircuitPrepareHardware コールバック関数を登録するには、ドライバーが AcxCircuitInitSetAcxCircuitPnpPowerCallbacks メソッドを呼び出す必要があります。

ドライバーが ACXCIRCUIT の EvtAcxCircuitPrepareHardware コールバック関数を登録している場合、WDF フレームワークがドライバーの EvtDevicePrepareHardware コールバック関数を呼び出した後、ACX フレームワークは関数を呼び出します。

EvtAcxCircuitPrepareHardware コールバック関数は、受信した ResourcesRaw ハンドルと ResourcesTranslated ハンドルを使用して、デバイスの生および変換されたハードウェア リソースにアクセスします。 コールバック関数は 、WdfCmResourceListGetCount と WdfCmResourceListGetDescriptor を呼び出して、リソース リストを走査できます。 このコールバック関数は、リソース リストを変更できません。

リソース リストと、リソースが表示される順序の詳細については、「 生および翻訳されたリソース」を参照してください。

通常、ドライバーの EvtAcxCircuitPrepareHardware コールバック関数は、必要に応じて次の処理を行います。

  • ドライバーがデバイスに割り当てられているメモリにアクセスできるように、物理メモリ アドレスを ACXCIRCUIT の仮想アドレスにマップします。
  • 必要に応じて、ドライバーの EvtAcxCircuitPrepareHardware コールバック関数は、他の時間のかかる構成タスクを完了するために作業項目をキューに入れます。 このような操作に作業項目を使用すると、デバイスの起動時間がシステムの起動時間を増加させないようにするのに役立ちます。 詳細については、「フレームワーク作業項目の使用」を参照してください。
  • 通常、ファームウェアの読み込みを含む他のすべてのハードウェア初期化操作は、デバイスが動作 (D0) 状態に入るたびに行われる必要があるため、ドライバーの EvtDeviceD0Entry コールバック関数で実行する必要があります。

ResourcesRaw および ResourcesTranslated は、EvtAcxCircuitPrepareHardware/EvtDevicePrepareHardware コールバック関数がドライバーの EvtDeviceReleaseHardware コールバック関数が返されるまで有効なままであることを処理します。

ドライバーが EvtAcxCircuitPrepareHardware コールバックに失敗した場合、ACXCIRCUIT オブジェクトは削除保留状態になり、関連付けられている ACXSTREAMS はシャットダウンされます。

ハードウェア リソースの詳細については、「ハードウェア リソース の概要」を参照してください。

ACX および WDF フレームワークがこれらのコールバック関数を呼び出すタイミングの詳細については、「 PnP と Power Management のシナリオ」を参照してください。

このコールバック関数を提供するドライバーの詳細については、「 Function Driver での PnP と Power Management のサポート」を参照してください。

例

使用例を次に示します。

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;
}

ACX の要件

最小 ACX バージョン: 1.0

ACX バージョンの詳細については、「 ACX バージョンの概要」を参照してください。

要件

要件 値
Header acxcircuit.h
IRQL PASSIVE_LEVEL

こちらもご覧ください