Share via

EVT_ACX_CIRCUIT_PREPARE_HARDWARE função de retorno de chamada (acxcircuit.h)

  • Artigo

O retorno de chamada EVT_ACX_CIRCUIT_PREPARE_HARDWARE é usado pelo driver para adicionar funcionalidade quando um ACXCIRCUIT está na fase de preparação do hardware.

Sintaxe

EVT_ACX_CIRCUIT_PREPARE_HARDWARE EvtAcxCircuitPrepareHardware;

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

Parâmetros

Device

Um objeto WDFDEVICE (descrito em WDF – Resumo de Objetos de Estrutura) associado ao ACXCIRCUIT especificado.

Circuit

O objeto ACXCIRCUIT (descrito em Resumo de Objetos ACX) na fase de preparação do hardware.

ResourcesRaw

Um identificador para um objeto de lista de recursos de estrutura que identifica os recursos brutos de hardware que o gerenciador de Plug and Play atribuiu ao dispositivo. Para obter mais informações sobre recursos brutos, consulte Recursos brutos e traduzidos.

ResourcesTranslated

Um identificador para um objeto de lista de recursos de estrutura que identifica os recursos de hardware traduzidos que o gerenciador de Plug and Play atribuiu ao dispositivo.

Retornar valor

Retorna STATUS_SUCCESS se a chamada foi bem-sucedida. Caso contrário, ele retornará um código de erro apropriado. Para obter mais informações, consulte Usando valores NTSTATUS.

Comentários

Para registrar uma função de retorno de chamada EvtAcxCircuitPrepareHardware, um driver deve chamar o método AcxCircuitInitSetAcxCircuitPnpPowerCallbacks.

Se o driver tiver registrado uma função de retorno de chamada EvtAcxCircuitPrepareHardware para um ACXCIRCUIT, a estrutura ACX chamará a função depois que a estrutura do WDF chamar a função de retorno de chamada EvtDevicePrepareHardware do driver.

A função de retorno de chamada EvtAcxCircuitPrepareHardware acessa os recursos de hardware brutos e traduzidos do dispositivo usando os identificadores ResourcesRaw e ResourcesTranslated que ele recebe. A função de retorno de chamada pode chamar WdfCmResourceListGetCount e WdfCmResourceListGetDescriptor para percorrer as listas de recursos. Essa função de retorno de chamada não pode modificar as listas de recursos.

Para obter mais informações sobre listas de recursos e a ordem em que os recursos aparecem, consulte Recursos brutos e traduzidos.

Normalmente, a função de retorno de chamada EvtAcxCircuitPrepareHardware do driver faz o seguinte, se necessário:

  • Mapeia endereços de memória física para endereços virtuais do ACXCIRCUIT para que o driver possa acessar a memória atribuída ao dispositivo.
  • Opcionalmente, a função de retorno de chamada EvtAcxCircuitPrepareHardware do driver pode enfileirar um item de trabalho para concluir qualquer outra tarefa de configuração com uso intensivo de tempo. Usar um item de trabalho para essas operações pode ajudar a garantir que o tempo de inicialização do dispositivo não aumente o tempo de inicialização do sistema. Para obter mais informações, consulte Usando itens de trabalho da estrutura.
  • Normalmente, todas as outras operações de inicialização de hardware, incluindo o carregamento de firmware, devem ocorrer sempre que o dispositivo entra em seu estado de trabalho (D0) e, portanto, deve ocorrer na função de retorno de chamada EvtDeviceD0Entry do driver.

A função de retorno de chamada ResourcesRaw e ResourcesTranslated que a função de retorno de chamada EvtAcxCircuitPrepareHardware/EvtDevicePrepareHardware recebe permanece válida até que a função de retorno de chamada EvtDeviceReleaseHardware do driver retorne.

Se o driver falhar no retorno de chamada EvtAcxCircuitPrepareHardware, o objeto ACXCIRCUIT será colocado no estado de exclusão pendente e o ACXSTREAMS associado será desligado.

Para obter mais informações sobre recursos de hardware, consulte Introdução aos recursos de hardware.

Para obter mais informações sobre quando a estrutura ACX e WDF chamam essas funções de retorno de chamada, consulte Cenários de gerenciamento de energia e PnP.

Para obter mais informações sobre drivers que fornecem essa função de retorno de chamada, consulte Suporte a PnP e Gerenciamento de Energia no Driver de Funções.

Exemplo

O uso de exemplo é mostrado abaixo.

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;
}

Requisitos do ACX

Versão mínima do ACX: 1.0

Para obter mais informações sobre versões do ACX, consulte Visão geral da versão do ACX.

Requisitos

Requisito Valor
Cabeçalho acxcircuit.h
IRQL PASSIVE_LEVEL

Confira também