Supporto delle operazioni BypassIO

  • Articolo

A partire da Windows 11, tutti i minifiltri devono aggiungere il supporto per le operazioni BypassIO. Le operazioni BypassIO vengono richieste chiamando FltFsControlFile o ZwFsControlFile con:

Questa pagina fornisce informazioni dettagliate per ogni operazione BypassIO. La richiesta di operazione viene specificata come valore FS_BPIO_OPERATIONS nel membro Operation di FS_BPIO_INPUT.

Per altre informazioni su BypassIO, vedere BypassIO per i filtri.

FS_BPIO_OP_ENABLE richiesta

Questa richiesta può provenire dalla modalità utente o kernel. BypassIO nelle scritture non memorizzate nella cache non è attualmente supportato.

FS_BPIO_OP_ENABLE richiede che il sistema abiliti BypassIO per il file specificato, il che significa che un driver potrebbe non visualizzare tutte le letture non memorizzate nella cache per tale file.

BypassIO è un concetto per ogni concetto di apertura file; ovvero, una richiesta di FS_BPIO_OP_ENABLE influisce solo sull'oggetto file associato alla richiesta di abilitazione e non modifica il comportamento di altre aperture nello stesso file o flusso. Se vengono inviate più richieste di abilitazione allo stesso oggetto file, solo la prima richiesta è significativa e tutte le richieste successive vengono ignorate.

Nel callback di preoperazione del driver:

  • Se un driver può supportare BypassIO per il file specificato, deve inoltrare la richiesta verso il basso nello stack.

  • Se il driver non può supportare BypassIO per il file specificato, deve chiamare FltVetoBypassIo con le informazioni seguenti:

    • Nome del driver, che si trova nella struttura FLT_RELATED_OBJECTS a cui punta il parametro FltObjects.
    • Codice di errore NTSTATUS che descrive il motivo per cui si sta vetando la richiesta di abilitazione nel parametro OperationStatus .
    • Stringa descrittiva univoca con i dettagli sul motivo per cui è stata eseguita la richiesta di abilitazione nel parametro FailureReason .

    FltVetoBypassIo scrive il nome del driver, il codice di errore e la stringa che descrive il motivo per cui il minifiltro ha impostato la richiesta di abilitazione nella struttura FS_BPIO_OUTPUT e scrive un evento ETW con lo stato, il motivo specificato dal filtro e il nome del filtro nel registro eventi.

Il minifiltro deve completare FSCTL_MANAGE_BYPASS_IO con STATUS_SUCCESS se FltVetoBypassIo ha esito positivo; in caso contrario, dovrebbe restituire l'errore restituito da FltVetoBypassIo .

Durante la post-operazione, il driver può vedere se tutti i driver seguenti sono in grado di supportare BypassIO. In caso affermativo, il driver deve mantenere lo stato necessario per il file e continuare l'elaborazione del completamento. È responsabilità del filtro e del file system mantenere lo stato per gestire correttamente le richieste che potrebbero non essere compatibili con lo stato abilitato per BypassIO.

Nota

Tutti i filtri nello stack del file system hanno la possibilità di impostare la richiesta di abilitazione BypassIO durante la pre-operazione, ma sono invitati a mantenerli abilitati il più possibile.

Il file system attiva automaticamente una richiesta di abilitazione BypassIO per i tipi di file seguenti:

  • Directory (flussi di dati alternativi in una directory possono usare BypassIO)
  • Volumi (DASD si apre)
  • File compressi NTFS
  • File ntfs-encryted
  • File sparse
  • File di paging
  • Tutti i file nei volumi DAX

La maggior parte dei filtri non deve mantenere lo stato che BypassIO è stato abilitato in un flusso specifico. Queste informazioni possono essere invece sottoposte a query chiamando FsRtlGetBypassIoOpenCount.

esempio di FS_BPIO_OP_ENABLE: filtro di crittografia

Quando un filtro di crittografia riceve un'operazione di FS_BPIO_OP_ENABLE su un file:

  • Se il file è già crittografato, il filtro deve chiamare FltVetoBypassIo per impostare l'operazione BypassIO, fornendo lo stato appropriato e un messaggio di diagnostica, ad esempio:

    • OpStatus = STATUS_NOT_SUPPORTED_WITH_ENCRYPTION
    • FailureReason = "File crittografato non supportato"

  • Se il file non è attualmente crittografato, il filtro deve consentire BypassIO. Se viene effettuata una richiesta successiva per crittografare questo file, il filtro può usare l'operazione di FS_BPIO_OP_STREAM_PAUSE per disabilitare BypassIO.

FS_BPIO_OP_DISABLE richiesta

Questa richiesta può provenire dalla modalità utente o kernel. Consente a un driver di pulire qualsiasi stato BypassIO associato.

Se un driver ha consentito l'abilitazione di BypassIO in precedenza in questo file e ora deve disattivare il supporto BypassIO per un file, deve inviare l'operazione di FS_BPIO_OP_DISABLE FSCTL_MANAGE_BYPASS_IO all'inizio dello stack del file system usando l'handle associato. Un esempio di quando questa condizione può verificarsi è un driver di crittografia che ha ricevuto una richiesta per crittografare il file.

Se un driver riceve FS_BPIO_OP_DISABLE ma non dispone attualmente di BypassIO abilitato, deve ignorare la richiesta. Se questa operazione viene inviata in un file che attualmente non dispone di BypassIO abilitato, deve essere ignorato.

Questa operazione non deve essere riuscita.

FS_BPIO_OP_QUERY richiesta

Questa richiesta può provenire dalla modalità utente o kernel.

Un filtro deve elaborare una richiesta di FS_BPIO_OP_QUERY simile a un'operazione di FS_BPIO_OP_ENABLE, chiamando FltVetoBypassIo per veto in base alle stesse informazioni di diagnostica descritte in precedenza nei parametri appropriati. La differenza principale è che il driver non immette lo stato BypassIO ENABLE durante una QUERY.

L'operazione FS_BPIO_OP_QUERY può essere inviata su handle di directory e volumi (non è possibile inviare una richiesta FS_BPIO_OP_ENABLE negli handle di directory o di volume).

Esempio di query: filtro di crittografia

Quando un filtro di crittografia riceve un'operazione di FS_BPIO_OP_QUERY su un file:

  • Se il file è già crittografato, il filtro deve chiamare FltVetoBypassIo per impostare l'operazione BypassIO, fornendo uno stato appropriato e un messaggio di diagnostica, ad esempio:

    • OpStatus = STATUS_NOT_SUPPORTED_WITH_ENCRYPTION
    • FailureReason = "File crittografato non supportato"

  • Se il file non è attualmente crittografato, il filtro deve avere esito positivo sulla richiesta di query.

FS_BPIO_OP_VOLUME_STACK_PAUSE richiesta

Questa richiesta può provenire dalla modalità utente o kernel.

Se un driver dello stack di volumi ha consentito l'abilitazione di BypassIO in precedenza in un volume e ora deve arrestare BypassIO (ad esempio, a causa di una richiesta esterna), il driver deve inviare un'operazione di FS_BPIO_OP_VOLUME_STACK_PAUSE FSCTL_MANAGE_BYPASS_IO all'inizio dello stack di volumi per notificare al file system di interrompere l'esecuzione di BypassIO nei volumi e negli stack di archiviazione del volume. Il file system svuota tutte le operazioni BypassIO attive da questo volume e quindi restituisce. Il driver dello stack di volumi può quindi elaborare la richiesta esterna.

Tutti i file abilitati per BypassIO attivi arrestano quindi l'esecuzione di operazioni BypassIO a livello di stack di archiviazione. Questa richiesta di operazione:

  • Può essere inviato su un handle di volume o su qualsiasi handle di file per il volume specificato.
  • Può essere inviato più volte allo stesso volume.
  • Può essere inviato se non sono presenti file abilitati per BypassIO nel volume.

BypassIO continua a funzionare nello stack del file system.

Questa operazione non deve essere riuscita.

Esempio di sospensione dello stack di volumi

BitLocker è un esempio di componente che usa questa operazione quando deve abilitare la crittografia in un volume.

Un altro esempio è lo scenario seguente: Si supponga che Volsnap consentiva l'abilitazione di BypassIO in un volume che non disponeva di snapshot del volume attivi. Successivamente, è stata effettuata una richiesta per creare uno snapshot del volume. Prima di procedere, Volsnap esegue le azioni seguenti:

  • Invia l'operazione di FS_BPIO_OP_VOLUME_STACK_PAUSE all'inizio dello stack che richiede che il sistema disabiliti BypassIO nello stack di volumi. Questa operazione viene eseguita ogni volta che viene creato un nuovo snapshot. Al termine della restituzione, BypassIO è ora disabilitato e svuotato nel volume specificato.
  • Elabora la richiesta di creazione dello snapshot

Volsnap deve quindi veto tutte le future richieste di BPIO_OP_ENABLE e BPIO_OP_QUERY su questo volume.

FS_BPIO_OP_VOLUME_STACK_RESUME richiesta

Un driver dello stack di volumi invia questa operazione FSCTL al file system per riprendere l'elaborazione BypassIO nel volume specificato. Invia questa operazione quando lo scenario che ha causato l'invio del driver FS_BPIO_OP_VOLUME_STACK_PAUSE non è più attivo. Questa operazione può essere inviata anche se BypassIO non è attualmente abilitato o sospeso.

Questa richiesta può provenire dalla modalità utente o kernel.

Questa operazione non deve essere riuscita.

Esempio di ripresa dello stack di volumi

Usando lo scenario di sospensione dello stack di volumi descritto in precedenza, si supponga che il volume non abbia più snapshot attivi. Volsnap invierà FS_BPIO_OP_VOLUME_STACK_RESUME solo dopo la scomparsa dell'ultimo snapshot.

FS_BPIO_OP_STREAM_PAUSE richiesta

Un filtro può inviare un'operazione FS_BPIO_OP_STREAM_PAUSE per sospendere BypassIO in un flusso. Questa richiesta può provenire dalla modalità utente o kernel. Tutti i file abilitati per BypassIO attivi arrestano l'esecuzione di operazioni BypassIO.

In particolare, se un filtro ha consentito l'abilitazione di BypassIO in precedenza in un flusso e successivamente deve arrestare BypassIO (a causa di una richiesta esterna, ad esempio una richiesta per crittografare un file o una directory), può inviare un FS_BPIO_OP_STREAM_PAUSE verso il basso dello stack di filtri per indicare al file system di interrompere l'esecuzione di BypassIO nel flusso specificato. Un filtro non deve inviare questa operazione all'inizio dello stack.

Prima che il file system venga restituito, sospende tutti gli handle BypassIO aperti nel flusso e completa tutte le operazioni BypassIO attive nel flusso. Queste azioni assicurano che, in caso di restituzione, il filtro possa eseguire l'operazione di file che deve eseguire.

Questa operazione può essere inviata più volte allo stesso flusso. Il file system lo ignora se viene inviato in un flusso che non è attualmente abilitato per BypassIO.

Se un filtro esegue un'operazione di sospensione del flusso, BypassIO continua nei volumi e negli stack di archiviazione.

Questa operazione non deve essere riuscita.

Esempio di pausa del flusso: filtro di crittografia

Si supponga che un filtro di crittografia abbia consentito l'abilitazione di BypassIO in un flusso non crittografato, ma successivamente ha ricevuto una richiesta per crittografare questo flusso.

Prima che il filtro di crittografia proceda, deve chiamare FsRtlGetBypassIoOpenCount per determinare se BypassIO è attivo in questo flusso. In caso affermativo, il filtro di crittografia invia un'operazione di FS_BPIO_OP_STREAM_PAUSE chiedendo al sistema di disabilitare BypassIO. Al termine della restituzione, BypassIO è disabilitato e svuotato, in modo che il filtro possa eseguire in modo sicuro la richiesta di crittografia. Per eliminare le possibili condizioni di race condition, il filtro deve veto a tutte le future richieste di FS_BPIO_OP_ENABLE e FS_BPIO_OP_QUERY su questo flusso crittografato.

FS_BPIO_OP_STREAM_RESUME richiesta

Quando lo scenario che ha causato l'invio di un'operazione di FS_BPIO_OP_STREAM_PAUSE non esiste più, il filtro invia un'operazione di FS_BPIO_OP_STREAM_RESUME al file system per riprendere l'elaborazione BypassIO di un determinato flusso. Questa richiesta può provenire dalla modalità utente o kernel.

Se questa operazione viene inviata quando BypassIO non è attualmente abilitato o sospeso, viene ignorato.

La sospensione e la ripresa non vengono conteggiate. In un curriculum, invece, il file system invia una richiesta di FS_BPIO_OP_QUERY all'inizio dello stack del file system per determinare se i filtri rimanenti continuano a bloccarsi. Il file system riprende BypassIO solo se tutti i filtri nello stack non bloccano BypassIO.

Questa operazione non deve essere riuscita.

Esempio di ripresa del flusso: filtro di crittografia

Usando lo scenario di FS_BPIO_OP_STREAM_PAUSE descritto in precedenza, si supponga che il file crittografato in precedenza dopo la chiamata a FS_BPIO_OP_STREAM_PAUSE non sia più crittografato. Il filtro deve quindi inviare l'operazione di FS_BPIO_OP_STREAM_RESUME per consentire a BypassIO di riprendere il flusso.

FS_BPIO_OP_GET_INFO richiesta

Questa richiesta può provenire dalla modalità utente o kernel. Il file system restituisce informazioni su BypassIO per il volume in una struttura FS_BPIO_INFO.