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

Статья
02/22/2024

Обратный вызов 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 для ACXCIRCUIT, платформа ACX вызывает функцию после того, как платформа WDF вызывает функцию обратного вызова EvtDevicePrepareHardware драйвера.

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

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

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

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

Дескриптора 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