IRP_MN_DEVICE_USAGE_NOTIFICATION
Os componentes do sistema enviam esse IRP para pedir aos drivers um dispositivo se o dispositivo pode dar suporte a um arquivo especial. Os arquivos especiais incluem arquivos de paginação, arquivos de despejo e arquivos de hibernação. Se todos os drivers do dispositivo tiverem êxito no IRP, o sistema criará o arquivo especial. O sistema também envia esse IRP para informar aos drivers que um arquivo especial foi removido do dispositivo.
Os drivers de função devem manipular esse IRP se o dispositivo puder conter um arquivo de paginação, um arquivo de despejo ou um arquivo de hibernação. Os drivers de filtro devem manipular esse IRP se o driver de função que eles estão filtrando manipular o IRP. Os motoristas de barramento devem lidar com esse IRP para o adaptador ou controlador (FDO do barramento) e para seus dispositivos filho (PDOs filho).
Valor
0x16
Código principal
Quando enviado
O sistema envia esse IRP quando está criando ou excluindo um arquivo de paginação, um arquivo de despejo ou um arquivo de hibernação. Se um dispositivo tiver uma relação de gerenciamento de energia fora da relação pai-filho convencional, o driver poderá enviar esse IRP para propagar informações de uso do dispositivo para outra pilha de dispositivos. Para obter mais informações, consulte a descrição da solicitação PowerRelations no IRP_MN_QUERY_DEVICE_RELATIONS.
Os componentes e drivers do sistema enviam esse IRP no IRQL PASSIVE_LEVEL em um contexto de thread arbitrário.
Parâmetros de Entrada
O membro Parameters.UsageNotification.InPath da estrutura IO_STACK_LOCATION é um BOOLEAN. Quando esse parâmetro é TRUE, o sistema está criando um arquivo de paginação, despejo de falha ou hibernação no dispositivo. Quando InPath for FALSE, esse arquivo será removido do dispositivo.
Parameters.UsageNotification.Type é uma enumeração que indica o tipo de arquivo. Esse parâmetro tem um dos seguintes valores: DeviceUsageTypePaging, DeviceUsageTypeDumpFile ou DeviceUsageTypeHibernation.
Parâmetros de saída
Nenhum
Bloco de Status de E/S
Os drivers definem Irp-IoStatus.Status> como STATUS_SUCCESS ou para um erro apropriado status.
Os drivers não modificam o campo Irp-IoStatus.Information>; ele permanece em zero, conforme definido pelo componente que envia o IRP.
Operação
Um driver manipula esse IRP no caminho do IRP para baixo na pilha do dispositivo e no caminho do IRP fazer backup da pilha.
Um driver responde a esse IRP com um procedimento semelhante ao seguinte:
Se Parameters.UsageNotification.InPath for TRUE, determine se o dispositivo dá suporte ao arquivo especial.
Um driver deve testar para os Parameters.UsageNotification.Type(s) específicos aos quais o driver pode dar suporte. Tipos de notificação adicionais podem ser adicionados no futuro.
Veja mais informações abaixo que descrevem as ações necessárias para dar suporte a cada tipo de notificação.
Se Parameters.UsageNotification.InPath for TRUE e o driver não puder dar suporte ao arquivo especial no dispositivo, o driver deverá concluir o IRP com uma falha status.
Se o dispositivo der suporte ao arquivo especial:
Execute as ações apropriadas para refletir que o dispositivo agora contém ou não contém mais um arquivo especial.
Um driver normalmente incrementa ou diminui um contador. Por exemplo, se Parameters.UsageNotification.Type for DeviceUsageTypePaging e Parameters.UsageNotification.InPath for TRUE, incremente uma contagem do número de arquivos de paginação no dispositivo. Determinadas rotinas de expedição de driver devem marcar os contadores.
Um dispositivo que contém um arquivo especial não deve ser desabilitado. Um driver pode chamar IoInvalidateDeviceState, solicitando que o gerenciador PnP consulte novamente as informações de estado do dispositivo PnP do dispositivo. Em resposta ao IRP IRP_MN_QUERY_PNP_DEVICE_STATE resultante, o driver deve definir o sinalizador PNP_DEVICE_NOT_DISABLEABLE.
Se InPath for FALSE, um driver definirá o DO_POWER_PAGABLE bit em seu objeto de dispositivo para o dispositivo.
Propagar as informações de uso do dispositivo para quaisquer dispositivos relacionados que exijam as informações.
Como parte de sua manipulação de um IRP IRP_MN_DEVICE_USAGE_NOTIFICATION , um driver pode ser necessário para passar as informações para uma ou mais pilhas de dispositivos. Esse driver cria um novo IRP_MN_DEVICE_USAGE_NOTIFICATION IRP (ou IRPs) e os envia para a pilha de dispositivos apropriada (ou pilhas). O driver deve aguardar a conclusão de qualquer IRP(s) de notificação de uso do dispositivo que ele envia antes que o driver termine de processar o IRP de uso do dispositivo que recebeu.
Como identificar os dispositivos relacionados é específico do dispositivo e do driver. Normalmente, um driver envia o IRP para outros drivers para os quais ele enviaria solicitações de E/S para o arquivo. Quando um driver de barramento lida com essa solicitação de um dispositivo filho, ele deve enviar uma notificação de uso IRP para a pilha de dispositivos para o pai do dispositivo.
Por exemplo, quando o ftdisk está executando um conjunto de distribuição de cinco discos, ele propaga notificações de paginação para cada um desses cinco discos, pois cada um desses dispositivos pode ser necessário para lidar com operações de arquivo de paginação.
Em uma função ou driver de filtro, defina uma rotina IoCompletion .
Em um driver de função ou filtro, defina Irp-IoStatus.Status> como STATUS_SUCCESS, configure o próximo local de pilha e passe o IRP para o próximo driver inferior com IoCallDriver. Não conclua o IRP.
Em um driver de ônibus que está tratando o IRP para um PDO filho: defina Irp-IoStatus.Status> e conclua o IRP (IoCompleteRequest).
Durante o processamento de conclusão do IRP:
Se uma rotina IoCompletion detectar que um driver inferior falhou no IRP, o driver de função ou filtro deverá desfazer todas as operações executadas em resposta ao IRP e propagar o erro. Se o driver de função ou filtro propagar as informações de uso para qualquer outra pilha de dispositivo, o driver deverá enviar outro IRP de uso para essas pilhas para notificá-las sobre a falha.
Se status for STATUS_SUCCESS e InPath for TRUE, desmarque o bit DO_POWER_PAGABLE.
Consulte Plug and Play para obter as regras gerais para lidar com Plug and Play IRPs menores.
Suporte a paginação, despejo de memória e arquivos de hibernação em um dispositivo
Quando qualquer uma das contagens de arquivos especiais de um driver é diferente de zero, o driver deve dar suporte à presença dos arquivos especiais em seu dispositivo (ou um dispositivo descendente).
Para um arquivo DeviceUsageTypePaging criado em seu dispositivo, um driver deve fazer o seguinte:
Bloqueie o código na memória para suas rotinas DispatchRead, DispatchWrite, DispatchDeviceControl e DispatchPower .
Limpe o bit DO_POWER_PAGABLE em seu objeto de dispositivo para o dispositivo (no caminho do IRP até a pilha do dispositivo).
Falha nas solicitações de IRP_MN_QUERY_STOP_DEVICE e IRP_MN_QUERY_REMOVE_DEVICE para o dispositivo.
Para um arquivo DeviceUsageTypeDumpFile em seu dispositivo, um driver deve fazer o seguinte:
Bloqueie o código na memória para suas rotinas DispatchRead, DispatchWrite, DispatchDeviceControl e DispatchPower .
Não tire o dispositivo do estado D0.
Não registre o dispositivo para detecção ociosa (PoRegisterDeviceForIdleDetection). Se o dispositivo já estiver registrado, cancele o registro. Se o driver executar sua própria detecção ociosa para o dispositivo, suspenda essa detecção.
Limpe o bit DO_POWER_PAGABLE em seu objeto de dispositivo para o dispositivo (no caminho do IRP até a pilha do dispositivo).
Falha nas solicitações de IRP_MN_QUERY_STOP_DEVICE e IRP_MN_QUERY_REMOVE_DEVICE para o dispositivo.
Para um arquivo DeviceUsageTypeHibernation em seu dispositivo, um driver deve fazer o seguinte:
Bloqueie o código na memória para suas rotinas DispatchRead, DispatchWrite, DispatchDeviceControl e DispatchPower .
Verifique se o dispositivo está no estado D0 quando o driver recebe um IRP de energia do sistema S4 indicando que o sistema está prestes a hibernar.
Não desligue o dispositivo em resposta a um IRP de set-power D3 que faça parte de uma ação de hibernação S4. Consulte System Power Actions para obter mais informações.
Após o recebimento desse IRP de set-power D3, execute todas as tarefas necessárias para colocar o dispositivo no estado D3, exceto para desligar o dispositivo e notificar o power manager (PoSetPowerState). O dispositivo deve manter a energia até que o arquivo de hibernação seja gravado.
Limpe o bit DO_POWER_PAGABLE em seu objeto de dispositivo para o dispositivo (no caminho do IRP até a pilha do dispositivo).
Falha nas solicitações de IRP_MN_QUERY_STOP_DEVICE e IRP_MN_QUERY_REMOVE_DEVICE para o dispositivo.
Confira Gerenciamento de Energia para obter mais informações sobre estados de energia do dispositivo, IRPs de energia e suporte ao gerenciamento de energia em drivers.
Enviando este IRP
Um driver pode enviar um IRP IRP_MN_DEVICE_USAGE_INFORMATION , mas apenas para propagar informações de uso do dispositivo para outra pilha de dispositivos. Um driver nunca é a origem inicial das informações de uso do dispositivo.
Requisitos
parâmetro |
Wdm.h (inclua Wdm.h, Ntddk.h ou Ntifs.h) |