次の方法で共有

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 と電源管理のシナリオ を参照してください。

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

例

使用例を次に示します。

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 バージョンの概要 参照してください。

必要条件

要件 価値
ヘッダー acxcircuit.h
IRQL PASSIVE_LEVEL

関連項目

  • acxcircuit.h ヘッダー を する