Compartilhar via

Suporte a operações BypassIO

  • Artigo

A partir do Windows 11, todos os minifiltros devem adicionar suporte para operações BypassIO. As operações BypassIO são solicitadas chamando FltFsControlFile ou ZwFsControlFile com:

Esta página fornece detalhes para cada operação BypassIO. A solicitação de operação é especificada como um valor FS_BPIO_OPERATIONS no membro Operation de FS_BPIO_INPUT.

Para obter mais informações sobre BypassIO, consulte BypassIO para filtros.

FS_BPIO_OP_ENABLE solicitação

Essa solicitação pode vir do modo de usuário ou kernel. No momento, não há suporte para BypassIO em gravações não armazenadas em cache.

FS_BPIO_OP_ENABLE solicita que o sistema habilite o BypassIO para o arquivo fornecido, o que significa que um driver pode não ver todas as leituras não armazenadas em cache para esse arquivo.

BypassIO é um conceito por abertura de arquivo; ou seja, uma solicitação FS_BPIO_OP_ENABLE afeta apenas o objeto de arquivo associado à solicitação de ativação e não altera o comportamento de outras aberturas no mesmo arquivo ou fluxo. Se várias solicitações de habilitação para o mesmo objeto de arquivo forem enviadas, somente a primeira solicitação será significativa e todas as solicitações subsequentes serão ignoradas.

No retorno de chamada de pré-operação do driver:

  • Se um driver puder dar suporte a BypassIO para o arquivo fornecido, ele deverá encaminhar a solicitação para baixo na pilha.

  • Se o driver não puder dar suporte a BypassIO para o arquivo fornecido, ele deverá chamar FltVetoBypassIo com as seguintes informações:

    • O nome do driver, que está na estrutura FLT_RELATED_OBJECTS para a qual o parâmetro FltObjects aponta.
    • Um código de erro NTSTATUS que descreve por que você está vetando a solicitação de habilitação no parâmetro OperationStatus .
    • Uma cadeia de caracteres exclusiva e descritiva com detalhes sobre por que você vetou a solicitação de habilitação no parâmetro FailureReason .

    FltVetoBypassIo grava o nome do driver, o código de erro e a cadeia de caracteres que descrevem por que o minifiltro vetou a solicitação de habilitação na estrutura FS_BPIO_OUTPUT e grava um evento ETW com o status, o motivo fornecido pelo filtro e o nome do filtro no log de eventos.

O minifiltro deve concluir FSCTL_MANAGE_BYPASS_IO com STATUS_SUCCESS se FltVetoBypassIo for bem-sucedido; caso contrário, ele deve retornar o erro que FltVetoBypassIo retornou.

Durante a pós-operação, o driver pode ver se todos os drivers abaixo dele são capazes de dar suporte ao BypassIO. Em caso afirmativo, o driver deve preservar qualquer estado necessário para o arquivo e continuar o processamento de conclusão. É responsabilidade do filtro e do sistema de arquivos manter o estado para lidar adequadamente com solicitações que podem não ser compatíveis com o estado habilitado para BypassIO.

Observação

Todos os filtros na pilha do sistema de arquivos têm a oportunidade de vetar a solicitação de habilitação BypassIO durante a pré-operação, mas são incentivados a mantê-la habilitada o máximo possível.

O sistema de arquivos veta automaticamente uma solicitação de habilitação BypassIO para os seguintes tipos de arquivos:

  • Diretórios (fluxos de dados alternativos em um diretório podem usar BypassIO)
  • Volumes (aberturas do DASD)
  • Arquivos compactados em NTFS
  • Arquivos criptografados por NTFS
  • Arquivos esparsos
  • Arquivos de paginação
  • Todos os arquivos em volumes DAX

A maioria dos filtros não precisa manter o estado em que o BypassIO foi habilitado em um fluxo específico. Em vez disso, essas informações podem ser consultadas chamando FsRtlGetBypassIoOpenCount.

FS_BPIO_OP_ENABLE exemplo: filtro de criptografia

Quando um filtro de criptografia recebe uma operação FS_BPIO_OP_ENABLE em um arquivo:

  • Se o arquivo já estiver criptografado, o filtro deverá chamar FltVetoBypassIo para vetar a operação BypassIO, fornecendo o status apropriado e uma mensagem de diagnóstico, como:

    • OpStatus = STATUS_NOT_SUPPORTED_WITH_ENCRYPTION
    • FailureReason = "Arquivo criptografado não suportado"

  • Se o arquivo não estiver criptografado no momento, o filtro deverá permitir BypassIO. Se uma solicitação posterior for feita para criptografar esse arquivo, o filtro poderá usar a operação FS_BPIO_OP_STREAM_PAUSE para desabilitar o BypassIO.

FS_BPIO_OP_DISABLE solicitação

Essa solicitação pode vir do modo de usuário ou kernel. Ele permite que um driver limpe qualquer estado BypassIO associado.

Se um driver permitiu anteriormente que o BypassIO fosse habilitado neste arquivo e agora precisa desativar o suporte ao BypassIO para um arquivo, ele deve enviar a operação FS_BPIO_OP_DISABLE FSCTL_MANAGE_BYPASS_IO para a parte superior da pilha do sistema de arquivos usando o identificador associado. Um exemplo de quando essa condição pode ocorrer é um driver de criptografia que recebeu uma solicitação para criptografar esse arquivo.

Se um driver receber FS_BPIO_OP_DISABLE mas não tiver o BypassIO habilitado no momento, ele deverá ignorar a solicitação. Se essa operação for enviada em um arquivo que atualmente não tem o BypassIO habilitado, ela deverá ser ignorada.

Essa operação não deve falhar.

FS_BPIO_OP_QUERY pedido

Essa solicitação pode vir do modo de usuário ou kernel.

Um filtro deve processar uma solicitação de FS_BPIO_OP_QUERY semelhante a uma operação FS_BPIO_OP_ENABLE , chamando FltVetoBypassIo para vetar conforme apropriado com as mesmas informações de diagnóstico descritas anteriormente nos parâmetros apropriados. A principal diferença é que o driver não insere o estado BypassIO ENABLE durante um QUERY.

A operação FS_BPIO_OP_QUERY pode ser enviada em identificadores de diretório e volume (uma solicitação FS_BPIO_OP_ENABLE não pode ser enviada em identificadores de diretório ou volume).

Exemplo de consulta: filtro de criptografia

Quando um filtro de criptografia recebe uma operação FS_BPIO_OP_QUERY em um arquivo:

  • Se o arquivo já estiver criptografado, o filtro deverá chamar FltVetoBypassIo para vetar a operação BypassIO, fornecendo um status apropriado e uma mensagem de diagnóstico, como:

    • OpStatus = STATUS_NOT_SUPPORTED_WITH_ENCRYPTION
    • FailureReason = "Arquivo criptografado não suportado"

  • Se o arquivo não estiver criptografado no momento, o filtro deverá ser bem-sucedido na solicitação de consulta.

FS_BPIO_OP_VOLUME_STACK_PAUSE solicitação

Essa solicitação pode vir do modo de usuário ou kernel.

Se um driver de pilha de volumes permitiu anteriormente que o BypassIO fosse habilitado em um volume e agora precisa interromper o BypassIO (por exemplo, devido a alguma solicitação externa), o driver deverá enviar uma operação de FSCTL_MANAGE_BYPASS_IO FS_BPIO_OP_VOLUME_STACK_PAUSE para a parte superior da pilha de volumes para notificar o sistema de arquivos para parar de fazer BypassIO nas pilhas de volume e armazenamento desse volume. O sistema de arquivos drena todas as operações BypassIO ativas desse volume e, em seguida, retorna. O driver da pilha de volumes pode processar a solicitação externa.

Todos os arquivos ativos habilitados para BypassIO param de fazer operações BypassIO no nível da pilha de armazenamento. Esta solicitação de operação:

  • Pode ser enviado em um identificador de volume ou em qualquer identificador de arquivo para o volume fornecido.
  • Pode ser enviado várias vezes para o mesmo volume.
  • Pode ser enviado se não houver arquivos habilitados para BypassIO no volume.

O BypassIO continua a operar na pilha do sistema de arquivos.

Essa operação não deve falhar.

Exemplo de pausa da pilha de volumes

O BitLocker é um exemplo de um componente que usa essa operação quando precisa habilitar a criptografia em um volume.

Outro exemplo é o seguinte cenário: Digamos que o Volsnap permitiu que o BypassIO fosse habilitado em um volume que não tinha instantâneos de volume ativos. Posteriormente, foi feita uma solicitação para criar um instantâneo de volume. O Volsnap executa as seguintes ações antes de continuar:

  • Envia a operação FS_BPIO_OP_VOLUME_STACK_PAUSE para o topo da pilha solicitando que o sistema desabilite o BypassIO na pilha de volumes. Ele faz isso sempre que um novo instantâneo é criado. Após o retorno bem-sucedido, o BypassIO agora é desabilitado e drenado no volume fornecido.
  • Processa a solicitação de criação de snapshot

A Volsnap deve então vetar todas as solicitações futuras de BPIO_OP_ENABLE e BPIO_OP_QUERY neste volume.

FS_BPIO_OP_VOLUME_STACK_RESUME pedido

Um driver de pilha de volumes envia essa operação FSCTL ao sistema de arquivos para retomar o processamento BypassIO no volume fornecido. Ele envia essa operação quando o cenário que fez com que o driver enviasse FS_BPIO_OP_VOLUME_STACK_PAUSE não está mais ativo. Essa operação pode ser enviada mesmo se o BypassIO não estiver habilitado ou pausado no momento.

Essa solicitação pode vir do modo de usuário ou kernel.

Essa operação não deve falhar.

Exemplo de retomada da pilha de volumes

Usando o cenário de pausa da pilha de volumes descrito anteriormente, digamos que o volume não tenha mais instantâneos ativos. O Volsnap enviará FS_BPIO_OP_VOLUME_STACK_RESUME somente depois que o último snapshot desaparecer.

FS_BPIO_OP_STREAM_PAUSE solicitação

Um filtro pode enviar uma operação FS_BPIO_OP_STREAM_PAUSE para pausar BypassIO em um fluxo. Essa solicitação pode vir do modo de usuário ou kernel. Todos os arquivos ativos habilitados para BypassIO param de fazer operações BypassIO.

Especificamente, se um filtro permitiu anteriormente que o BypassIO fosse habilitado em um fluxo e depois precisar interromper o BypassIO (devido a uma solicitação externa, como uma solicitação para criptografar um arquivo ou diretório), ele poderá enviar um FS_BPIO_OP_STREAM_PAUSE para baixo na pilha de filtros para informar ao sistema de arquivos para parar de fazer BypassIO no fluxo fornecido. Um filtro não deve enviar essa operação para o topo da pilha.

Antes que o sistema de arquivos retorne, ele pausa todos os identificadores BypassIO abertos no fluxo e conclui todas as operações BypassIO ativas no fluxo. Essas ações garantem que, no retorno, o filtro possa executar a operação de arquivo que precisa fazer.

Essa operação pode ser enviada várias vezes para o mesmo fluxo. O sistema de arquivos o ignorará se ele for enviado em um fluxo que não esteja habilitado para BypassIO no momento.

Se um filtro fizer uma operação de pausa de fluxo, o BypassIO continuará nas pilhas de volume e armazenamento.

Essa operação não deve falhar.

Exemplo de pausa de transmissão: filtro de criptografia

Digamos que um filtro de criptografia permitiu que o BypassIO fosse habilitado em um fluxo que não foi criptografado, mas depois recebeu uma solicitação para criptografar esse fluxo.

Antes que o filtro de criptografia prossiga, ele deve chamar FsRtlGetBypassIoOpenCount para determinar se BypassIO está ativo nesse fluxo. Em caso afirmativo, o filtro de criptografia envia uma operação FS_BPIO_OP_STREAM_PAUSE solicitando que o sistema desabilite o BypassIO. Após o retorno bem-sucedido, o BypassIO é desabilitado e drenado, para que o filtro possa executar a solicitação de criptografia com segurança. Para eliminar possíveis condições de corrida, o filtro deve vetar todas as FS_BPIO_OP_ENABLE futuras e solicitações FS_BPIO_OP_QUERY neste fluxo agora criptografado.

FS_BPIO_OP_STREAM_RESUME solicitação

Quando o cenário que fez com que o filtro enviasse uma operação FS_BPIO_OP_STREAM_PAUSE não existe mais, o filtro envia uma operação FS_BPIO_OP_STREAM_RESUME ao sistema de arquivos para retomar o processamento BypassIO de um determinado fluxo. Essa solicitação pode vir do modo de usuário ou kernel.

Se essa operação for enviada quando o BypassIO não estiver habilitado ou pausado no momento, ela será ignorada.

Pausar e retomar não são contados por referência. Em vez disso, em um currículo, o sistema de arquivos emite uma solicitação de FS_BPIO_OP_QUERY para a parte superior da pilha do sistema de arquivos para determinar se os filtros restantes ainda estão sendo bloqueados. O sistema de arquivos retomará o BypassIO somente se todos os filtros na pilha não estiverem bloqueando o BypassIO.

Essa operação não deve falhar.

Exemplo de retomada de fluxo: filtro de criptografia

Usando o cenário FS_BPIO_OP_STREAM_PAUSE descrito anteriormente, digamos que o arquivo que foi criptografado anteriormente após a chamada para FS_BPIO_OP_STREAM_PAUSE não esteja mais criptografado. Em seguida, o filtro deve enviar a operação FS_BPIO_OP_STREAM_RESUME para permitir que o BypassIO seja retomado nesse fluxo.

FS_BPIO_OP_GET_INFO solicitação

Essa solicitação pode vir do modo de usuário ou kernel. O sistema de arquivos retorna informações sobre BypassIO para o volume em uma estrutura FS_BPIO_INFO .