EVT_ACX_CIRCUIT_PREPARE_HARDWARE 콜백 함수(acxcircuit.h)

아티클
02/26/2024

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 핸들은 드라이버의 EvtDeviceReleaseHardware 콜백 함수가 반환될 때까지 EvtAcxCircuitPrepareHardware/EvtDevicePrepareHardware 콜백 함수가 수신하는 유효한 상태로 유지됩니다.

드라이버가 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 헤더

다음을 통해 공유