функция обратного вызова EVT_ACX_CIRCUIT_PREPARE_HARDWARE (acxcircuit.h)

Статья
02/06/2025

Обратный вызов EVT_ACX_CIRCUIT_PREPARE_HARDWARE используется драйвером для добавления функциональных возможностей, когда ACXCIRCUIT находится на этапе подготовки оборудования.

Синтаксис

EVT_ACX_CIRCUIT_PREPARE_HARDWARE EvtAcxCircuitPrepareHardware;

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

Параметры

Device

Объект WDFDEVICE (описанный в WDF — сводка объектов платформы), связанный с указанным ACXCIRCUIT.

Circuit

Объект ACXCIRCUIT (описанный в сводкеобъектов ACX) на этапе подготовки оборудования.

ResourcesRaw

Дескриптор объекта списка ресурсов платформы, определяющий необработанные аппаратные ресурсы, назначенные диспетчеру Plug and Play устройству. Дополнительные сведения о необработанных ресурсах см. в необработанных и переведенных ресурсов.

ResourcesTranslated

Дескриптор объекта списка ресурсов платформы, определяющий переведенные аппаратные ресурсы, назначенные диспетчеру Plug and Play устройству.

Возвращаемое значение

Возвращает STATUS_SUCCESS, если вызов выполнен успешно. В противном случае возвращается соответствующий код ошибки. Дополнительные сведения см. в использовании значений NTSTATUS.

Замечания

Чтобы зарегистрировать функцию обратного вызова EvtAcxCircuitPrepareHardware, драйвер должен вызвать метод AcxCircuitInitSetAcxCircuitPnpPowerCallbacks.

Если драйвер зарегистрировал функцию обратного вызова EvtAcxCircuitPrepareHardware для ACXCIRCUIT, платформа ACX вызывает функцию после вызова платформы WDF вызывает функцию вызова EvtDevicePrepareHardware.

Функция обратного вызова EvtAcxCircuitPrepareHardware обращается к необработанным и преобразованным аппаратным ресурсам устройства с помощью дескрипторов ResourcesRaw и ResourcesTranslated, которые он получает. Функция обратного вызова может вызывать WdfCmResourceListGetCount и WdfCmResourceListListGetDescriptor для обхода списков ресурсов. Эта функция обратного вызова не может изменять списки ресурсов.

Дополнительные сведения о списках ресурсов и порядке отображения ресурсов см. в необработанных и переведенных ресурсов.

Как правило, функция обратного вызова EvtAcxCircuitPrepareHardware вашего драйвера выполняет следующие действия.

Сопоставляет адреса физической памяти с виртуальными адресами ACXCIRCUIT, чтобы драйвер может получить доступ к памяти, назначенной устройству.
При необходимости функция обратного вызова EvtAcxCircuitPrepareHardware может очередью рабочего элемента для выполнения любых других задач конфигурации с интенсивным временем. Использование рабочего элемента для таких операций может помочь убедиться, что время запуска устройства не увеличивает время загрузки системы. Дополнительные сведения см. в разделе Using Framework Work Items.
Как правило, все остальные операции инициализации оборудования, включая загрузку встроенного ПО, должны выполняться при каждом входе устройства в рабочее состояние (D0) и поэтому должны выполняться в функции обратного вызова EvtDeviceDeviceD0Entry.

Функция обратного вызова ResourcesRaw и ResourcesTranslated обрабатывает, что функция обратного вызова EvtAcxCircuitPrepareHardware/EvtDevicePrepareHardware остается допустимой до тех пор, пока функция обратного вызова EvtDeviceReleaseHardware драйвера не возвращается.

Если драйвер завершается сбоем обратного вызова 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
IRQL	PASSIVE_LEVEL

См. также

заголовка acxcircuit.h

Поделиться через