filesystems/xfs/xfs-online-fsck-design.rst

70 Secondary metadata (e.g. reverse mapping and directory parent pointers) support
429 - Reverse mapping information
570   increases the time cost of persisting changes to disk, and the reverse space
573   reverse mapping features at format time, though this choice dramatically
967 Reverse Mapping
987 Like any system that improves redundancy, the reverse-mapping feature increases
989 However, it has two critical advantages: first, the reverse index is key to
992 Second, the different ondisk storage format of the reverse mapping btree
1013 The information captured in a reverse space mapping record is as follows:
1037 The reverse mapping index plays a key role in the consistency checking process
1048 * The correspondence of an entry in the reverse mapping information.
1050 There are several observations to make about reverse mapping indices:
1052 1. Reverse mappings can provide a positive affirmation of correctness if any of
1060    For example, checking a reverse mapping record for a file extent mapping
1072    This means that forward progress during this part of a scan of the reverse
1075 In summary, reverse mappings play a key role in reconstruction of primary
1211 For the reverse mapping btree, it is possible to mask parts of the key for the
1243    - Does the reverse mapping index list only the appropriate owner as the
1266    - Does the reverse mapping index list no owners of this space?
1310      are there the same number of reverse mapping records for each block as the
1555 reverse mapping and reflink were introduced.
1624 During the design phase of the reverse mapping and reflink features, it was
1625 decided that it was impractical to cram all the reverse mapping updates for a
1630 * A reverse mapping update for the block mapping update
1632 * A reverse mapping update for the freelist fix
1635 * A reverse mapping update for the btree update
1637 * A reverse mapping update for the freelist fix
1640 * A reverse mapping update for the refcount update
1642 * A reverse mapping update for the freelist fix
1646 * A reverse mapping update for the freelist fix
1650 * A reverse mapping update for the freelist fix
1658 work items to cover most reverse mapping updates and all refcount updates.
1672 For example, if a thread performing a copy-on-write has completed a reverse
1907 4. Staging btrees in memory (reverse mapping btrees)
1981 counts, file fork space, and reverse mappings) consists of a set of fixed-size
2032 reverse mapping information.
2204 Conveniently, however, XFS has a library to create and maintain ordered reverse
2572 1. Walk the reverse mapping records to generate ``struct xfs_inobt_rec``
2597 reverse mapping information.
2598 Reverse mapping records with an owner of ``XFS_RMAP_OWN_INOBT`` marks the
2600 Each reverse mapping record with an owner of ``XFS_RMAP_OWN_INODES`` marks the
2634 Reverse mapping records are used to rebuild the reference count information.
2637 Imagine the reverse mapping entries as rectangles representing extents of
2660 1. Walk the reverse mapping records to generate ``struct xfs_refcount_irec``
2661    records for any space having more than one reverse mapping and add them to
2687 generate refcount information from reverse mapping records.
2689 - Until the reverse mapping btree runs out of records:
2701       unprocessed reverse mapping or the next block after the shortest mapping
2706     - Collect all reverse mappings that start at this position from the btree
2715 Reverse mappings are added to the bag using ``xfarray_store_anywhere`` and
2729 1. Walk the reverse mapping records to generate ``struct xfs_bmbt_rec``
2730    records from the reverse mapping records for that inode and fork.
2781 As part of a repair, online fsck relies heavily on the reverse mapping records
2796 2. Survey the reverse mapping data to create a bitmap of space owned by the
2812 4. For each candidate extent, count the number of reverse mapping records for
2824 6. If the region is crosslinked, delete the reverse mapping entry for the
2862 2. For each reverse mapping record with an rmap owner corresponding to the
2874 common case), then step 2 can be performed at the same time as the reverse
2882 1. Walk the reverse mapping records to generate ``struct xfs_alloc_rec_incore``
2883    records from the gaps in the reverse mapping btree.
2900    reverse mapping btree, the new free space btrees, or the AGFL.
2905 First, free space is not explicitly tracked in the reverse mapping records.
2907 space component of the keyspace of the reverse mapping btree.
2922 As part of committing the new btrees, repair must ensure that reverse mappings
2930 Blocks for the free space btrees and the reverse mapping btrees are supplied by
2932 Blocks put onto the AGFL have reverse mapping records with the owner
2935 btrees or the reverse mapping btrees.
2936 When repair walks reverse mapping records to synthesize free space records, it
2953 Case Study: Reaping After Repairing Reverse Mapping Btrees
2956 Old reverse mapping btrees are less difficult to reap after a repair.
2958 btree blocks, and the reverse mapping btree blocks all have reverse mapping
2960 The full process of gathering reverse mapping records and building a new btree
2972 The rest of the process of rebuildng the reverse mapping btree is discussed
2985 1. Create a bitmap for all the space that the reverse mapping data claims is
2990 3. Subtract any space that the reverse mapping data claims is owned by any
3350 Resources are often released in the reverse order, though this is not required.
3754 Case Study: Rebuilding Reverse Mapping Records
3771 Unfortunately, repairs to the reverse mapping btree cannot use the "standard"
3777 scan for reverse mapping records.
3782    scrub, generate reverse mappings for all AG metadata: inodes, btrees, CoW
3874 fail because freeing space will find the extra reverse mappings and abort.
3990 a. When the reverse-mapping btree is enabled, the swap code must keep the
3991    reverse mapping information up to date with every exchange of mappings.
3995 b. Reverse-mapping is critical for the operation of online fsck, so the old
4016 the reverse-mapping extent swap code, but records intermedia progress in the
4463 way that the historic lack of reverse space mapping information once hindered
4493 |    followed up with the corresponding change to the reverse links.       |
5024    and reverse mapping btrees) depend on consistency within the AG headers and
5327 When the reverse mapping btree was later added to XFS, the only way to maintain
5328 the consistency of the fork mappings with the reverse mapping index was to
5428 reverse mapping index from userspace.