1 .. SPDX-License-Identifier: GPL-2.0
6 Introduced in ext3, the ext4 filesystem employs a journal to protect the
7 filesystem against metadata inconsistencies in the case of a system crash. Up
8 to 10,240,000 file system blocks (see man mke2fs(8) for more details on journal
9 size limits) can be reserved inside the filesystem as a place to land
10 “important” data writes on-disk as quickly as possible. Once the important
11 data transaction is fully written to the disk and flushed from the disk write
12 cache, a record of the data being committed is also written to the journal. At
13 some later point in time, the journal code writes the transactions to their
14 final locations on disk (this could involve a lot of seeking or a lot of small
15 read-write-erases) before erasing the commit record. Should the system
16 crash during the second slow write, the journal can be replayed all the
17 way to the latest commit record, guaranteeing the atomicity of whatever
18 gets written through the journal to the disk. The effect of this is to
19 guarantee that the filesystem does not become stuck midway through a
22 For performance reasons, ext4 by default only writes filesystem metadata
23 through the journal. This means that file data blocks are /not/
24 guaranteed to be in any consistent state after a crash. If this default
25 guarantee level (``data=ordered``) is not satisfactory, there is a mount
26 option to control journal behavior. If ``data=journal``, all data and
27 metadata are written to disk through the journal. This is slower but
28 safest. If ``data=writeback``, dirty data blocks are not flushed to the
29 disk before the metadata are written to disk through the journal.
31 In case of ``data=ordered`` mode, Ext4 also supports fast commits which
32 help reduce commit latency significantly. The default ``data=ordered``
33 mode works by logging metadata blocks to the journal. In fast commit
34 mode, Ext4 only stores the minimal delta needed to recreate the
35 affected metadata in fast commit space that is shared with JBD2.
36 Once the fast commit area fills in or if fast commit is not possible
37 or if JBD2 commit timer goes off, Ext4 performs a traditional full commit.
38 A full commit invalidates all the fast commits that happened before
39 it and thus it makes the fast commit area empty for further fast
40 commits. This feature needs to be enabled at mkfs time.
42 The journal inode is typically inode 8. The first 68 bytes of the
43 journal inode are replicated in the ext4 superblock. The journal itself
44 is normal (but hidden) file within the filesystem. The file usually
45 consumes an entire block group, though mke2fs tries to put it in the
48 All fields in jbd2 are written to disk in big-endian order. This is the
51 NOTE: Both ext4 and ocfs2 use jbd2.
53 The maximum size of a journal embedded in an ext4 filesystem is 2^32
54 blocks. jbd2 itself does not seem to care.
59 Generally speaking, the journal has this format:
66 - descriptor\_block (data\_blocks or revocation\_block) [more data or
67 revocations] commmit\_block
68 - [more transactions...]
73 Notice that a transaction begins with either a descriptor and some data,
74 or a block revocation list. A finished transaction always ends with a
75 commit. If there is no commit record (or the checksums don't match), the
76 transaction will be discarded during replay.
81 Optionally, an ext4 filesystem can be created with an external journal
82 device (as opposed to an internal journal, which uses a reserved inode).
83 In this case, on the filesystem device, ``s_journal_inum`` should be
84 zero and ``s_journal_uuid`` should be set. On the journal device there
85 will be an ext4 super block in the usual place, with a matching UUID.
86 The journal superblock will be in the next full block after the
90 :widths: 12 12 12 32 12
93 * - 1024 bytes of padding
96 - descriptor\_block (data\_blocks or revocation\_block) [more data or
97 revocations] commmit\_block
98 - [more transactions...]
108 Every block in the journal starts with a common 12-byte header
109 ``struct journal_header_s``:
122 - jbd2 magic number, 0xC03B3998.
126 - Description of what this block contains. See the jbd2_blocktype_ table
131 - The transaction ID that goes with this block.
135 The journal block type can be any one of:
144 - Descriptor. This block precedes a series of data blocks that were
145 written through the journal during a transaction.
147 - Block commit record. This block signifies the completion of a
150 - Journal superblock, v1.
152 - Journal superblock, v2.
154 - Block revocation records. This speeds up recovery by enabling the
155 journal to skip writing blocks that were subsequently rewritten.
160 The super block for the journal is much simpler as compared to ext4's.
161 The key data kept within are size of the journal, and where to find the
162 start of the log of transactions.
164 The journal superblock is recorded as ``struct journal_superblock_s``,
165 which is 1024 bytes long:
178 - Static information describing the journal.
180 - journal\_header\_t (12 bytes)
182 - Common header identifying this as a superblock.
186 - Journal device block size.
190 - Total number of blocks in this journal.
194 - First block of log information.
198 - Dynamic information describing the current state of the log.
202 - First commit ID expected in log.
206 - Block number of the start of log. Contrary to the comments, this field
207 being zero does not imply that the journal is clean!
211 - Error value, as set by jbd2\_journal\_abort().
215 - The remaining fields are only valid in a v2 superblock.
218 - s\_feature\_compat;
219 - Compatible feature set. See the table jbd2_compat_ below.
222 - s\_feature\_incompat
223 - Incompatible feature set. See the table jbd2_incompat_ below.
226 - s\_feature\_ro\_compat
227 - Read-only compatible feature set. There aren't any of these currently.
231 - 128-bit uuid for journal. This is compared against the copy in the ext4
232 super block at mount time.
236 - Number of file systems sharing this journal.
240 - Location of dynamic super block copy. (Not used?)
243 - s\_max\_transaction
244 - Limit of journal blocks per transaction. (Not used?)
247 - s\_max\_trans\_data
248 - Limit of data blocks per transaction. (Not used?)
252 - Checksum algorithm used for the journal. See jbd2_checksum_type_ for
261 - Number of fast commit blocks in the journal.
269 - Checksum of the entire superblock, with this field set to zero.
273 - ids of all file systems sharing the log. e2fsprogs/Linux don't allow
274 shared external journals, but I imagine Lustre (or ocfs2?), which use
275 the jbd2 code, might.
279 The journal compat features are any combination of the following:
288 - Journal maintains checksums on the data blocks.
289 (JBD2\_FEATURE\_COMPAT\_CHECKSUM)
293 The journal incompat features are any combination of the following:
302 - Journal has block revocation records. (JBD2\_FEATURE\_INCOMPAT\_REVOKE)
304 - Journal can deal with 64-bit block numbers.
305 (JBD2\_FEATURE\_INCOMPAT\_64BIT)
307 - Journal commits asynchronously. (JBD2\_FEATURE\_INCOMPAT\_ASYNC\_COMMIT)
309 - This journal uses v2 of the checksum on-disk format. Each journal
310 metadata block gets its own checksum, and the block tags in the
311 descriptor table contain checksums for each of the data blocks in the
312 journal. (JBD2\_FEATURE\_INCOMPAT\_CSUM\_V2)
314 - This journal uses v3 of the checksum on-disk format. This is the same as
315 v2, but the journal block tag size is fixed regardless of the size of
316 block numbers. (JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3)
318 - Journal has fast commit blocks. (JBD2\_FEATURE\_INCOMPAT\_FAST\_COMMIT)
320 .. _jbd2_checksum_type:
322 Journal checksum type codes are one of the following. crc32 or crc32c are the
343 The descriptor block contains an array of journal block tags that
344 describe the final locations of the data blocks that follow in the
345 journal. Descriptor blocks are open-coded instead of being completely
346 described by a data structure, but here is the block structure anyway.
347 Descriptor blocks consume at least 36 bytes, but use a full block:
360 - Common block header.
362 - struct journal\_block\_tag\_s
364 - Enough tags either to fill up the block or to describe all the data
365 blocks that follow this descriptor block.
367 Journal block tags have any of the following formats, depending on which
368 journal feature and block tag flags are set.
370 If JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 is set, the journal block tag is
371 defined as ``struct journal_block_tag3_s``, which looks like the
372 following. The size is 16 or 32 bytes.
385 - Lower 32-bits of the location of where the corresponding data block
386 should end up on disk.
390 - Flags that go with the descriptor. See the table jbd2_tag_flags_ for
395 - Upper 32-bits of the location of where the corresponding data block
396 should end up on disk. This is zero if JBD2\_FEATURE\_INCOMPAT\_64BIT is
401 - Checksum of the journal UUID, the sequence number, and the data block.
405 - This field appears to be open coded. It always comes at the end of the
406 tag, after t_checksum. This field is not present if the "same UUID" flag
411 - A UUID to go with this tag. This field appears to be copied from the
412 ``j_uuid`` field in ``struct journal_s``, but only tune2fs touches that
417 The journal tag flags are any combination of the following:
426 - On-disk block is escaped. The first four bytes of the data block just
427 happened to match the jbd2 magic number.
429 - This block has the same UUID as previous, therefore the UUID field is
432 - The data block was deleted by the transaction. (Not used?)
434 - This is the last tag in this descriptor block.
436 If JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 is NOT set, the journal block tag
437 is defined as ``struct journal_block_tag_s``, which looks like the
438 following. The size is 8, 12, 24, or 28 bytes:
451 - Lower 32-bits of the location of where the corresponding data block
452 should end up on disk.
456 - Checksum of the journal UUID, the sequence number, and the data block.
457 Note that only the lower 16 bits are stored.
461 - Flags that go with the descriptor. See the table jbd2_tag_flags_ for
466 - This next field is only present if the super block indicates support for
467 64-bit block numbers.
471 - Upper 32-bits of the location of where the corresponding data block
472 should end up on disk.
476 - This field appears to be open coded. It always comes at the end of the
477 tag, after t_flags or t_blocknr_high. This field is not present if the
478 "same UUID" flag is set.
482 - A UUID to go with this tag. This field appears to be copied from the
483 ``j_uuid`` field in ``struct journal_s``, but only tune2fs touches that
486 If JBD2\_FEATURE\_INCOMPAT\_CSUM\_V2 or
487 JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 are set, the end of the block is a
488 ``struct jbd2_journal_block_tail``, which looks like this:
501 - Checksum of the journal UUID + the descriptor block, with this field set
507 In general, the data blocks being written to disk through the journal
508 are written verbatim into the journal file after the descriptor block.
509 However, if the first four bytes of the block match the jbd2 magic
510 number then those four bytes are replaced with zeroes and the “escaped”
511 flag is set in the descriptor block tag.
516 A revocation block is used to prevent replay of a block in an earlier
517 transaction. This is used to mark blocks that were journalled at one
518 time but are no longer journalled. Typically this happens if a metadata
519 block is freed and re-allocated as a file data block; in this case, a
520 journal replay after the file block was written to disk will cause
523 **NOTE**: This mechanism is NOT used to express “this journal block is
524 superseded by this other journal block”, as the author (djwong)
525 mistakenly thought. Any block being added to a transaction will cause
526 the removal of all existing revocation records for that block.
528 Revocation blocks are described in
529 ``struct jbd2_journal_revoke_header_s``, are at least 16 bytes in
530 length, but use a full block:
543 - Common block header.
547 - Number of bytes used in this block.
549 - \_\_be32 or \_\_be64
553 After r\_count is a linear array of block numbers that are effectively
554 revoked by this transaction. The size of each block number is 8 bytes if
555 the superblock advertises 64-bit block number support, or 4 bytes
558 If JBD2\_FEATURE\_INCOMPAT\_CSUM\_V2 or
559 JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 are set, the end of the revocation
560 block is a ``struct jbd2_journal_revoke_tail``, which has this format:
573 - Checksum of the journal UUID + revocation block
578 The commit block is a sentry that indicates that a transaction has been
579 completely written to the journal. Once this commit block reaches the
580 journal, the data stored with this transaction can be written to their
581 final locations on disk.
583 The commit block is described by ``struct commit_header``, which is 32
584 bytes long (but uses a full block):
597 - Common block header.
601 - The type of checksum to use to verify the integrity of the data blocks
602 in the transaction. See jbd2_checksum_type_ for more info.
606 - The number of bytes used by the checksum. Most likely 4.
613 - h\_chksum[JBD2\_CHECKSUM\_BYTES]
614 - 32 bytes of space to store checksums. If
615 JBD2\_FEATURE\_INCOMPAT\_CSUM\_V2 or JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3
616 are set, the first ``__be32`` is the checksum of the journal UUID and
617 the entire commit block, with this field zeroed. If
618 JBD2\_FEATURE\_COMPAT\_CHECKSUM is set, the first ``__be32`` is the
619 crc32 of all the blocks already written to the transaction.
623 - The time that the transaction was committed, in seconds since the epoch.
627 - Nanoseconds component of the above timestamp.
632 Fast commit area is organized as a log of tag length values. Each TLV has
633 a ``struct ext4_fc_tl`` in the beginning which stores the tag and the length
634 of the entire field. It is followed by variable length tag specific value.
635 Here is the list of supported tags and their meanings:
646 - Fast commit area header
647 - ``struct ext4_fc_head``
648 - Stores the TID of the transaction after which these fast commits should
650 * - EXT4_FC_TAG_ADD_RANGE
651 - Add extent to inode
652 - ``struct ext4_fc_add_range``
653 - Stores the inode number and extent to be added in this inode
654 * - EXT4_FC_TAG_DEL_RANGE
655 - Remove logical offsets to inode
656 - ``struct ext4_fc_del_range``
657 - Stores the inode number and the logical offset range that needs to be
659 * - EXT4_FC_TAG_CREAT
660 - Create directory entry for a newly created file
661 - ``struct ext4_fc_dentry_info``
662 - Stores the parent inode number, inode number and directory entry of the
665 - Link a directory entry to an inode
666 - ``struct ext4_fc_dentry_info``
667 - Stores the parent inode number, inode number and directory entry
668 * - EXT4_FC_TAG_UNLINK
669 - Unlink a directory entry of an inode
670 - ``struct ext4_fc_dentry_info``
671 - Stores the parent inode number, inode number and directory entry
674 - Padding (unused area)
676 - Unused bytes in the fast commit area.
679 - Mark the end of a fast commit
680 - ``struct ext4_fc_tail``
681 - Stores the TID of the commit, CRC of the fast commit of which this tag
682 represents the end of
684 Fast Commit Replay Idempotence
685 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
687 Fast commits tags are idempotent in nature provided the recovery code follows
688 certain rules. The guiding principle that the commit path follows while
689 committing is that it stores the result of a particular operation instead of
690 storing the procedure.
692 Let's consider this rename operation: 'mv /a /b'. Let's assume dirent '/a'
693 was associated with inode 10. During fast commit, instead of storing this
694 operation as a procedure "rename a to b", we store the resulting file system
695 state as a "series" of outcomes:
697 - Link dirent b to inode 10
699 - Inode 10 with valid refcount
701 Now when recovery code runs, it needs "enforce" this state on the file
702 system. This is what guarantees idempotence of fast commit replay.
704 Let's take an example of a procedure that is not idempotent and see how fast
705 commits make it idempotent. Consider following sequence of operations:
711 If we store this sequence of operations as is then the replay is not idempotent.
712 Let's say while in replay, we crash after (2). During the second replay,
713 file A (which was actually created as a result of "mv B A" operation) would get
714 deleted. Thus, file named A would be absent when we try to read A. So, this
715 sequence of operations is not idempotent. However, as mentioned above, instead
716 of storing the procedure fast commits store the outcome of each procedure. Thus
717 the fast commit log for above procedure would be as follows:
719 (Let's assume dirent A was linked to inode 10 and dirent B was linked to
720 inode 11 before the replay)
723 2) Link A to inode 11
727 If we crash after (3) we will have file A linked to inode 11. During the second
728 replay, we will remove file A (inode 11). But we will create it back and make
729 it point to inode 11. We won't find B, so we'll just skip that step. At this
730 point, the refcount for inode 11 is not reliable, but that gets fixed by the
731 replay of last inode 11 tag. Thus, by converting a non-idempotent procedure
732 into a series of idempotent outcomes, fast commits ensured idempotence during
736 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
738 Checkpointing the journal ensures all transactions and their associated buffers
739 are submitted to the disk. In-progress transactions are waited upon and included
740 in the checkpoint. Checkpointing is used internally during critical updates to
741 the filesystem including journal recovery, filesystem resizing, and freeing of
742 the journal_t structure.
744 A journal checkpoint can be triggered from userspace via the ioctl
745 EXT4_IOC_CHECKPOINT. This ioctl takes a single, u64 argument for flags.
746 Currently, three flags are supported. First, EXT4_IOC_CHECKPOINT_FLAG_DRY_RUN
747 can be used to verify input to the ioctl. It returns error if there is any
748 invalid input, otherwise it returns success without performing
749 any checkpointing. This can be used to check whether the ioctl exists on a
750 system and to verify there are no issues with arguments or flags. The
751 other two flags are EXT4_IOC_CHECKPOINT_FLAG_DISCARD and
752 EXT4_IOC_CHECKPOINT_FLAG_ZEROOUT. These flags cause the journal blocks to be
753 discarded or zero-filled, respectively, after the journal checkpoint is
754 complete. EXT4_IOC_CHECKPOINT_FLAG_DISCARD and EXT4_IOC_CHECKPOINT_FLAG_ZEROOUT
755 cannot both be set. The ioctl may be useful when snapshotting a system or for
756 complying with content deletion SLOs.
projects / platform / kernel / linux-starfive.git / blob