Partilhar via

Macro WdfDeviceStopIdle (wdfdevice.h)

  • Artigo

[aplica-se ao KMDF e ao UMDF]

O método WdfDeviceStopIdle informa à estrutura que o dispositivo especificado deve ser colocado em seu estado de energia de trabalho (D0).

Sintaxe

NTSTATUS WdfDeviceStopIdle(
   _In_ WDFDEVICE Device,
   _In_ BOOLEAN WaitForD0
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] WaitForD0

Um valor booliano que indica quando WdfDeviceStopIdle será retornado. Se verdadeiro, ele retornará somente depois que o dispositivo especificado tiver inserido o estado de energia do dispositivo D0. Se FALSE, o método retornará imediatamente.

Valor de retorno

Nenhum

Observações

Essa macro pode retornar os seguintes valores:

Valor de retorno Significado
STATUS_PENDING O dispositivo está sendo habilitado de forma assíncrona.
STATUS_INVALID_DEVICE_STATE O driver não é o proprietário da política de energia do dispositivo.
STATUS_POWER_STATE_INVALID Ocorreu uma falha no dispositivo e o dispositivo não pode inserir seu estado de energia D0.

O método pode retornar outros valores NTSTATUS.

Observação

Para dispositivos que especificam SystemManagedIdleTimeout ou SystemManagedIdleTimeoutWithHint na enumeração WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE, ao chamar WdfDeviceStopIdle com WaitForD0 definido como FALSE, se o dispositivo ainda estiver em D0 e o período de tempo limite ocioso ainda não tiver decorrido, começando nas versões 1.33/2.33 do WDF, WdfDeviceStopIdle retorna STATUS_SUCCESS (em versões anteriores isso resultou em um valor retornado de STATUS_PENDING).

Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.

Se o dispositivo puder entrar em um estado de baixa potência quando ficar ocioso, o driver poderá precisar chamar ocasionalmente WdfDeviceStopIdle para trazer o dispositivo de volta ao seu estado de trabalho (D0) ou impedir que ele entre em um estado de baixa potência.

WdfDeviceStopIdle não impede que a estrutura faça a transição do dispositivo para um estado de suspensão quando o sistema muda para um estado de suspensão Sx. Seu único efeito é impedir transições para estados de suspensão Dx enquanto o sistema está no estado de trabalho S0. Da mesma forma, se o dispositivo der suporte a de gerenciamento de energia direcionado, WdfDeviceStopIdle não impedirá que o dispositivo insira a energia direcionada para baixo.

Aviso

Não chame WdfDeviceStopIdle com WaitForD0 = TRUE durante a desligar, direta ou indiretamente. Por exemplo, se o EvtDeviceArmWakeFromS0 espera em outro thread que chama WdfDeviceStopIdle(TRUE), a transição de energia é bloqueada e o sistema falha.

O do driver não precisa chamar WdfDeviceStopIdle quando um dispositivo está ocioso e a estrutura coloca uma solicitação de E/S na fila de E/S gerenciada por energia do dispositivo. Além disso, o do driver não precisa chamar WdfDeviceStopIdle quando um dispositivo está ocioso e detecta um sinal de ativação. Em ambos os casos, a estrutura solicita que o motorista do ônibus restaure o estado de energia do dispositivo para D0.

Embora os drivers normalmente não precisem chamar WdfDeviceStopIdle ao lidar com solicitações de E/S obtidas de uma fila de E/S gerenciada por energia, a chamada é permitida. No entanto, os drivers não devem definir o parâmetro WaitForD0 para verdadeiro ao lidar com solicitações de E/S de uma fila de E/S gerenciada por energia.

O do driver precisa chamar WdfDeviceStopIdle se precisar acessar o dispositivo devido a uma solicitação que o driver recebeu fora de uma fila de E/S gerenciada por energia. Por exemplo, o driver pode dar suporte a uma interface definida pelo driver ou a uma solicitação WMI que exige o acesso ao dispositivo. Nesse caso, você deve garantir que o dispositivo esteja em seu estado de trabalho antes que o driver acesse o dispositivo e que o dispositivo permaneça em seu estado de trabalho até que o driver termine de acessar o dispositivo.

Chamar WdfDeviceStopIdle força o dispositivo a entrar em seu estado de trabalho (D0), se o sistema estiver em seu estado de trabalho (S0). O dispositivo permanece em seu estado de trabalho até que o driver chame WdfDeviceResumeIdle, momento em que a estrutura poderá colocar o dispositivo em um estado de baixa potência se ele permanecer ocioso.

Não chame WdfDeviceStopIdle antes que a estrutura tenha chamado a função de retorno de chamada EvtDeviceD0Ent ry do driver pela primeira vez.

Uma chamada para wdfDeviceStopIdle pode restaurar um dispositivo ocioso para seu estado de trabalho somente se o sistema estiver em seu estado de trabalho (S0). Se o sistema estiver fazendo a transição para um estado de baixa potência ou o dispositivo já tiver sido desligado em resposta ao Sx (em que x > 0) quando um driver chama WdfDeviceStopIdle com o parâmetro WaitForD0 definido como VERDADEIRO, a função não retornará até que o sistema retorne ao estado S0. Da mesma forma, se o dispositivo der suporte a de gerenciamento de energia direcionado e o subsistema de energia tiver iniciado uma desligar direcionada, uma chamada para WdfDeviceStopIdle com o parâmetro WaitForD0 definido como TRUE, não retornará até que o subsistema de energia tenha direcionado o dispositivo para fazer backup.

Cada chamada bem-sucedida para WdfDeviceStopIdle deve eventualmente ser seguida por uma chamada para WdfDeviceResumeIdle, ou então o dispositivo nunca retornará a um estado de baixa potência se ficar ocioso novamente. As chamadas para WdfDeviceStopIdle podem ser aninhadas, portanto, o número de chamadas para WdfDeviceResumeIdle deve ser igual ao número de chamadas para WdfDeviceStopIdle. Não chame WdfDeviceResumeIdle se uma chamada para WdfDeviceStopIdle falhar.

Se o sistema entrar em um estado de baixa potência após WdfDeviceStopIdle retornar, o dispositivo também entrará em um estado de baixa potência. Quando o sistema retorna ao seu estado de trabalho (S0), o dispositivo também retorna ao seu estado de trabalho (D0). A referência de energia da chamada para WdfDeviceStopIdle permanece ativa e impede que o dispositivo insira um estado de baixa potência até que haja uma chamada correspondente para WdfDeviceResumeIdle.

Para obter mais informações, consulte suporte aode power-down ocioso.

Se WaitForD0 for VERDADEIRO, WdfDeviceStopIdle deverá ser chamado em IRQL = PASSIVE_LEVEL. Se WaitForD0 for FALSE, esse método deverá ser chamado em IRQL <= DISPATCH_LEVEL.

Chamar WdfDeviceStopIdleWithTag em vez de WdfDeviceStopIdle fornece informações adicionais (valor da marca, número de linha e nome do arquivo) que você pode exibir nos depuradores da Microsoft.

Exemplos

No exemplo de código a seguir, WdfDeviceStopIdle retorna depois que o dispositivo especificado inseriu o estado de energia do dispositivo D0.

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

Requisitos

Requisito Valor
da Plataforma de Destino Universal
versão mínima do KMDF 1.0
versão mínima do UMDF 2.0
cabeçalho wdfdevice.h (inclua Wdf.h)
Biblioteca Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL Consulte a seção Comentários.
regras de conformidade de DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte também