Top 10 Things a Filter Driver Developer must know to work with TxF

1. Top 10 Things a Filter Driver Developer must know to work with TxF Sarosh Havewala Development Lead File System Filter Team

2. #1: KTM, RM and TxF • KTM – Kernel Transaction Manager • Transaction engine in the kernel • Important entity supporting Transactional NTFS (TxF) and Transactional Registry (TxR). • RM - Resource Manager • Enables co-ordination of transactions with resources • Fltmgr is a non-durable RM • TxF – Transactional NTFS • Allows transacted file system operations within the NTFS filesystem • Is a durable RM.

3. #2: KTRANSACTION object • Given a FILE_OBJECT, retrieve the KTRANSACTION object with IoGetTransactionParameterBlock: PTXN_PARAMETER_BLOCK IoGetTransactionParameterBlock ( __in PFILE_OBJECT FileObject ); typedef struct _TXN_PARAMETER_BLOCK { USHORT Length; // sizeof( TXN_PARAMETER_BLOCK ) USHORT TxFsContext; // this is mini version of the requested file PVOID TransactionObject; // referenced pointer to KTRANSACTION } TXN_PARAMETER_BLOCK, *PTXN_PARAMETER_BLOCK;

4. #2: KTRANSACTION object (continued) • May be used as a key for the lifetime of the transaction • Usual referencing concepts apply as with any kernel object • Always dereference with ObDereferenceObjectDeferDelete to be deadlock safe • Note that this pointer value can be reused, while TRANSACTION GUID is guaranteed to be unique.

5. #3: State Awareness • Potential States • Transacted state • Non-transacted state • Global state • KTM Notifications: • TRANSACTION_NOTIFY_PREPREPARE • TRANSACTION_NOTIFY_PREPARE • TRANSACTION_NOTIFY_COMMIT • TRANSACTION_NOTIFY_COMMIT_FINALIZE • TRANSACTION_NOTIFY_ROLLBACK • Rollback I/O not visible to filters

6. #4: Savepoints • Savepoints are a TxF concept, not a KTM concept • Savepoints come as FSCTL_TXFS_SAVEPOINT_INFORMATION on a handle to the root of the RM • Not KTM notifications • Action codes • TXFS_SAVEPOINT_SET • TXFS_SAVEPOINT_ROLLBACK • TXFS_SAVEPOINT_CLEAR/TXFS_SAVEPOINT_CLEAR_ALL

7. #4: Savepoints (continued) Scenario: 1. create transaction 1 <- state for transaction rollback 2. create a new file ‘a.txt’ in T1 3. Create a new file ‘b.txt’ in T1 4. Set savepoint (savepoint 0) <- state for rollback to savepoint 0 5. Create a new file ‘c.txt’ in T1 6. Create a new file ‘d.txt’ in T1 7. Set savepoint (savepoint 1) <- state for rollback to savepoint 1 8. Create a new file ‘e.txt’ in T1 9. Create a new file ‘f.txt’ in T1 <- state if transaction committed

8. #4: Savepoints (continued) • SavepointId: • Identifies a savepoint to rollback to • Monotonically increasing ULONG until clear or rollback • Set savepoint - TXFS_SAVEPOINT_SET • Returns the number of this new savepoint • Clear savepoint - TXFS_SAVEPOINT_CLEAR / TXFS_SAVEPOINT_CLEAR_ALL • Clears the last savepoint • Clear all savepoints • Rollback to savepoint – TXFS_SAVEPOINT_ROLLBACK • Rolls back state to savepoint specified • Specified savepoint and all later savepoints are cleared • Rollback I/O not visible to filters • Need to remember state at each savepoint within a transaction to be able to rollback to a savepoint

9. #5: Concept of Tx locked • When a file is opened with write/delete access in a transaction, Txf treats this file as trans-locked by that transaction • No one can open the same file for write or delete in a different transaction or non-transaction. • Trans-lock is per file • locks all the streams of the file • TXF-metadata query to query the trans-lock state of a file • FSCTL_TXFS_GET_METADATA_INFO

10. #5: Concept of Tx locked (continued) • The file remains trans-locked for the duration of the transaction • Closing the handle to the file does not release the trans-lock • Cancelling a create does not undo a trans-lock on the file • Trans-locked in a filter • Transaction committed by TxF, but filter is still in the process of updating state

11. #6: No defined order for KTM Notifications to RMs • TxF (NTFS) may receive commit notification before other RMs (say a minifilter) • Minifilter will see committed state for the transaction • TxF (NTFS) may receive commit notification after other RMs (say a minifilter) • Minifilter will see non-committed state for the transaction • Opens to the file may fail since the file may be trans-locked • Commit Finalize Notification • Called after all RMs have committed the transaction

12. #7: Context of the I/O operation • The I/O may be issued in transacted or non-transacted context • KTRANSACTION associated with the I/O identifies the transaction • FLT_RELATED_OBJECTS:: Transaction • IoGetTransactionParameterBlock • Issue filter I/O in the correct context • FltCreateFileEx2 • IO_DRIVER_CREATE_CONTEXT typedefstruct _IO_DRIVER_CREATE_CONTEXT { CSHORT Size; struct _ECP_LIST *ExtraCreateParameter; PVOID DeviceObjectHint; PTXN_PARAMETER_BLOCK TxnParameters; } IO_DRIVER_CREATE_CONTEXT, *PIO_DRIVER_CREATE_CONTEXT;

13. #8: Paging IO on Transacted File Objects Scenario: 1. create transaction 1 2. create file 'foo.txt’ in T1 3. close file 'foo.txt‘ in T1 4. commit transaction 1 5. create transaction 2 6. open file 'foo.txt‘ in T2 7. write to file 'foo.txt' (*** the FLT_RELATED_OBJECTS for paging IO will contain transaction 1's value *** ) in T2 8. close file 'foo.txt‘ in T2 9. commit transaction 2

14. #8: Paging IO on Transacted File Objects (continued) • Paging IO is sent down on the FILE_OBJECT captured by MM • The FILE_OBJECT is not necessarily opened in the context of the transaction that is causing the paging IO • This can confuse a filter looking for transacted IO and trying to attribute IO to a particular transaction • The transaction associated with the FILE_OBJECT for the paging I/O (in the described scenario) would show it’s state as inactive • Filter can use its own translocked state as an indicator of the real context of the paging IO • Will make this better in W7

15. #9: HSM-type Filters Scenario: A transacted writer modifies an attribute of a file in the context of transaction T1. A transacted reader (other than T1) or non-transacted reader tried to read the file and that triggers a recall of the primary data stream of the file. • The filter tries to open a writable handle to recall the primary data stream of the file. Problem: The create for write will fail because the file is transaction locked by transaction T1.

16. #9: HSM-type Filters (continued) Scenario: A transacted writer tried to write the file and that triggers a recall of the primary data stream of the file. • The HSM filter can recall and fill in the primary data stream in the context of that transaction using the transacted writer handle. Problem: The write would be isolated from any other non-transacted readers or readers in the context of other transactions, so they would not be able to see the recalled data until the transaction that write locked the file committed.

17. #9: HSM-type Filters (continued) Scenario: A transacted reader tried to read the file and that triggers a recall of the primary data stream of the file. • The HSM filter opens a writable handle in the context of the same transaction and recalls the file. Problem: The first transacted reader remains isolated from the writes.

18. #9: HSM-type Filters (continued) Proposed workaround: In the case of a transacted open, recall the entire file in pre-create • TxF not available over remote, so remote FS timeout on create is not a deal-breaker.

19. #10: Global Directory Enumeration • T1: • Create B • Delete D • T2: • Create C • Rename E to F

20. #10: Global Directory Enumeration (continued)

21. #10: Global Directory Enumeration (continued) • FileIdGlobalTxDirectoryInformation typedefstruct _FILE_ID_GLOBAL_TX_DIR_INFORMATION { ULONG NextEntryOffset; ULONG FileIndex; LARGE_INTEGER CreationTime; LARGE_INTEGER LastAccessTime; LARGE_INTEGER LastWriteTime; LARGE_INTEGER ChangeTime; LARGE_INTEGER EndOfFile; LARGE_INTEGER AllocationSize; ULONG FileAttributes; ULONG FileNameLength; LARGE_INTEGER FileId; GUID LockingTransactionId; ULONG TxInfoFlags; WCHAR FileName[1]; } FILE_ID_GLOBAL_TX_DIR_INFORMATION, *PFILE_ID_GLOBAL_TX_DIR_INFORMATION; #define FILE_ID_GLOBAL_TX_DIR_INFO_FLAG_WRITELOCKED 0x00000001 #define FILE_ID_GLOBAL_TX_DIR_INFO_FLAG_VISIBLE_TO_TX 0x00000002 #define FILE_ID_GLOBAL_TX_DIR_INFO_FLAG_VISIBLE_OUTSIDE_TX 0x00000004