| b.liu | e958203 | 2025-04-17 19:18:16 +0800 | [diff] [blame^] | 1 | .. SPDX-License-Identifier: GPL-2.0 |
| 2 | |
| 3 | ================================================= |
| 4 | incfs: A stacked incremental filesystem for Linux |
| 5 | ================================================= |
| 6 | |
| 7 | /sys/fs interface |
| 8 | ================= |
| 9 | |
| 10 | Please update Documentation/ABI/testing/sysfs-fs-incfs if you update this |
| 11 | section. |
| 12 | |
| 13 | incfs creates the following files in /sys/fs. |
| 14 | |
| 15 | Features |
| 16 | -------- |
| 17 | |
| 18 | /sys/fs/incremental-fs/features/corefs |
| 19 | Reads 'supported'. Always present. |
| 20 | |
| 21 | /sys/fs/incremental-fs/features/v2 |
| 22 | Reads 'supported'. Present if all v2 features of incfs are supported. These |
| 23 | are: |
| 24 | fs-verity support |
| 25 | inotify support |
| 26 | ioclts: |
| 27 | INCFS_IOC_SET_READ_TIMEOUTS |
| 28 | INCFS_IOC_GET_READ_TIMEOUTS |
| 29 | INCFS_IOC_GET_BLOCK_COUNT |
| 30 | INCFS_IOC_CREATE_MAPPED_FILE |
| 31 | .incomplete folder |
| 32 | .blocks_written pseudo file |
| 33 | report_uid mount option |
| 34 | |
| 35 | /sys/fs/incremental-fs/features/zstd |
| 36 | Reads 'supported'. Present if zstd compression is supported for data blocks. |
| 37 | |
| 38 | /sys/fs/incremental-fs/features/bugfix_throttling |
| 39 | Reads 'supported'. Present if the throttling lock bug is fixed |
| 40 | |
| 41 | Optional per mount |
| 42 | ------------------ |
| 43 | |
| 44 | For each incfs mount, the mount option sysfs_name=[name] creates a /sys/fs |
| 45 | node called: |
| 46 | |
| 47 | /sys/fs/incremental-fs/instances/[name] |
| 48 | |
| 49 | This will contain the following files: |
| 50 | |
| 51 | /sys/fs/incremental-fs/instances/[name]/reads_delayed_min |
| 52 | Returns a count of the number of reads that were delayed as a result of the |
| 53 | per UID read timeouts min time setting. |
| 54 | |
| 55 | /sys/fs/incremental-fs/instances/[name]/reads_delayed_min_us |
| 56 | Returns total delay time for all files since first mount as a result of the |
| 57 | per UID read timeouts min time setting. |
| 58 | |
| 59 | /sys/fs/incremental-fs/instances/[name]/reads_delayed_pending |
| 60 | Returns a count of the number of reads that were delayed as a result of |
| 61 | waiting for a pending read. |
| 62 | |
| 63 | /sys/fs/incremental-fs/instances/[name]/reads_delayed_pending_us |
| 64 | Returns total delay time for all files since first mount as a result of |
| 65 | waiting for a pending read. |
| 66 | |
| 67 | /sys/fs/incremental-fs/instances/[name]/reads_failed_hash_verification |
| 68 | Returns number of reads that failed because of hash verification failures. |
| 69 | |
| 70 | /sys/fs/incremental-fs/instances/[name]/reads_failed_other |
| 71 | Returns number of reads that failed for reasons other than timing out or |
| 72 | hash failures. |
| 73 | |
| 74 | /sys/fs/incremental-fs/instances/[name]/reads_failed_timed_out |
| 75 | Returns number of reads that timed out. |
| 76 | |
| 77 | For reads_delayed_*** settings, note that a file can count for both |
| 78 | reads_delayed_min and reads_delayed_pending if incfs first waits for a pending |
| 79 | read then has to wait further for the min time. In that case, the time spent |
| 80 | waiting is split between reads_delayed_pending_us, which is increased by the |
| 81 | time spent waiting for the pending read, and reads_delayed_min_us, which is |
| 82 | increased by the remainder of the time spent waiting. |
| 83 | |
| 84 | Reads that timed out are not added to the reads_delayed_pending or the |
| 85 | reads_delayed_pending_us counters. |