通过

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

WDFDEVICE 对象 (WDF - 与指定 ACXCIRCUIT 关联的框架对象) 摘要中所述。

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 版本概述。

要求

要求 值
Header acxcircuit.h
IRQL PASSIVE_LEVEL

另请参阅