EVT_ACX_CIRCUIT_PREPARE_HARDWARE回调函数 （acxcircuit.h）

当 ACXCIRCUIT 处于准备硬件阶段时，驱动程序使用 EVT_ACX_CIRCUIT_PREPARE_HARDWARE 回调来添加功能。

语法

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 回调函数，则 ACX 框架在 WDF 框架调用驱动程序的 EvtDevicePrepareHardware 回调函数后调用该函数。

EvtAcxCircuitPrepareHardware 回调函数使用接收的 ResourcesRaw 和 ResourcesTranslated 句柄访问设备的原始和已转换的硬件资源。 回调函数可以调用 WdfCmResourceListGetCount，WdfCmResourceListGetDescriptor 遍历资源列表。 此回调函数无法修改资源列表。

有关资源列表以及资源显示顺序的详细信息，请参阅 原始和已翻译的资源。

通常，驱动程序的 EvtAcxCircuitPrepareHardware 回调函数会根据需要执行以下作：

• 将物理内存地址映射到 ACXCIRCUIT 的虚拟地址，以便驱动程序可以访问分配给设备的内存。
• （可选）驱动程序的 EvtAcxCircuitPrepareHardware 回调函数可能会将工作项排队以完成任何其他时间密集型配置任务。 对此类作使用工作项有助于确保设备的启动时间不会增加系统启动时间。 有关详细信息，请参阅“使用框架工作项”。
• 通常，所有其他硬件初始化作（包括加载固件）应在设备进入其工作状态（D0）时进行，因此应在驱动程序的 EvtDeviceD0Entry 回调函数中发生。

在驱动程序的 EvtDeviceReleaseHardware 回调函数返回之前，EvtAcxCircuitPrepareHardware/EvtDevicePrepareHardware 回调函数接收的 ResourcesRaw 和 ResourcesTranslated 句柄保持有效。

如果驱动程序失败，EvtAcxCircuitPrepareHardware 回调，ACXCIRCUIT 对象将置于删除挂起状态，并且关联的 ACXSTREAMS 将关闭。

有关硬件资源的详细信息，请参阅 硬件资源简介。

有关 ACX 和 WDF 框架何时调用这些回调函数的详细信息，请参阅 PnP 和电源管理方案。

有关提供此回调函数的驱动程序的详细信息，请参阅函数驱动程序 支持 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 标头