Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) NILFS2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) NILFS2 is a log-structured file system (LFS) supporting continuous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) snapshotting.  In addition to versioning capability of the entire file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) system, users can even restore files mistakenly overwritten or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) destroyed just a few seconds ago.  Since NILFS2 can keep consistency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) like conventional LFS, it achieves quick recovery after system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) crashes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) NILFS2 creates a number of checkpoints every few seconds or per
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) synchronous write basis (unless there is no change).  Users can select
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) significant versions among continuously created checkpoints, and can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) change them into snapshots which will be preserved until they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) changed back to checkpoints.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) There is no limit on the number of snapshots until the volume gets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) full.  Each snapshot is mountable as a read-only file system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) concurrently with its writable mount, and this feature is convenient
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) for online backup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) The userland tools are included in nilfs-utils package, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) available from the following download page.  At least "mkfs.nilfs2",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) "mount.nilfs2", "umount.nilfs2", and "nilfs_cleanerd" (so called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) cleaner or garbage collector) are required.  Details on the tools are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) described in the man pages included in the package.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) :Project web page:    https://nilfs.sourceforge.io/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) :Download page:       https://nilfs.sourceforge.io/en/download.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) :List info:           http://vger.kernel.org/vger-lists.html#linux-nilfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) Caveats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) Features which NILFS2 does not support yet:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) 	- atime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) 	- extended attributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) 	- POSIX ACLs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) 	- quotas
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) 	- fsck
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) 	- defragmentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) Mount options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) NILFS2 supports the following mount options:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) (*) == default
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) barrier(*)		This enables/disables the use of write barriers.  This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) nobarrier		requires an IO stack which can support barriers, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 			if nilfs gets an error on a barrier write, it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) 			disable again with a warning.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) errors=continue		Keep going on a filesystem error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) errors=remount-ro(*)	Remount the filesystem read-only on an error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) errors=panic		Panic and halt the machine if an error occurs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) cp=n			Specify the checkpoint-number of the snapshot to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) 			mounted.  Checkpoints and snapshots are listed by lscp
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) 			user command.  Only the checkpoints marked as snapshot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) 			are mountable with this option.  Snapshot is read-only,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) 			so a read-only mount option must be specified together.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) order=relaxed(*)	Apply relaxed order semantics that allows modified data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) 			blocks to be written to disk without making a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) 			checkpoint if no metadata update is going.  This mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) 			is equivalent to the ordered data mode of the ext3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) 			filesystem except for the updates on data blocks still
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) 			conserve atomicity.  This will improve synchronous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) 			write performance for overwriting.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) order=strict		Apply strict in-order semantics that preserves sequence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) 			of all file operations including overwriting of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) 			blocks.  That means, it is guaranteed that no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) 			overtaking of events occurs in the recovered file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) 			system after a crash.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) norecovery		Disable recovery of the filesystem on mount.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) 			This disables every write access on the device for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) 			read-only mounts or snapshots.  This option will fail
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) 			for r/w mounts on an unclean volume.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) discard			This enables/disables the use of discard/TRIM commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) nodiscard(*)		The discard/TRIM commands are sent to the underlying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) 			block device when blocks are freed.  This is useful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) 			for SSD devices and sparse/thinly-provisioned LUNs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) Ioctls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) There is some NILFS2 specific functionality which can be accessed by applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) through the system call interfaces. The list of all NILFS2 specific ioctls are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) shown in the table below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) Table of NILFS2 specific ioctls:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97)  ============================== ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98)  Ioctl			        Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99)  ============================== ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)  NILFS_IOCTL_CHANGE_CPMODE      Change mode of given checkpoint between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) 			        checkpoint and snapshot state. This ioctl is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 			        used in chcp and mkcp utilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)  NILFS_IOCTL_DELETE_CHECKPOINT  Remove checkpoint from NILFS2 file system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) 			        This ioctl is used in rmcp utility.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)  NILFS_IOCTL_GET_CPINFO         Return info about requested checkpoints. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) 			        ioctl is used in lscp utility and by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) 			        nilfs_cleanerd daemon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)  NILFS_IOCTL_GET_CPSTAT         Return checkpoints statistics. This ioctl is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 			        used by lscp, rmcp utilities and by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 			        nilfs_cleanerd daemon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)  NILFS_IOCTL_GET_SUINFO         Return segment usage info about requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) 			        segments. This ioctl is used in lssu,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 			        nilfs_resize utilities and by nilfs_cleanerd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) 			        daemon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)  NILFS_IOCTL_SET_SUINFO         Modify segment usage info of requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) 				segments. This ioctl is used by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) 				nilfs_cleanerd daemon to skip unnecessary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 				cleaning operation of segments and reduce
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) 				performance penalty or wear of flash device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 				due to redundant move of in-use blocks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)  NILFS_IOCTL_GET_SUSTAT         Return segment usage statistics. This ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) 			        is used in lssu, nilfs_resize utilities and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 			        by nilfs_cleanerd daemon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)  NILFS_IOCTL_GET_VINFO          Return information on virtual block addresses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) 			        This ioctl is used by nilfs_cleanerd daemon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)  NILFS_IOCTL_GET_BDESCS         Return information about descriptors of disk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 			        block numbers. This ioctl is used by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) 			        nilfs_cleanerd daemon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)  NILFS_IOCTL_CLEAN_SEGMENTS     Do garbage collection operation in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) 			        environment of requested parameters from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 			        userspace. This ioctl is used by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) 			        nilfs_cleanerd daemon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)  NILFS_IOCTL_SYNC               Make a checkpoint. This ioctl is used in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 			        mkcp utility.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)  NILFS_IOCTL_RESIZE             Resize NILFS2 volume. This ioctl is used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) 			        by nilfs_resize utility.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)  NILFS_IOCTL_SET_ALLOC_RANGE    Define lower limit of segments in bytes and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 			        upper limit of segments in bytes. This ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) 			        is used by nilfs_resize utility.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)  ============================== ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) NILFS2 usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) To use nilfs2 as a local file system, simply::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)  # mkfs -t nilfs2 /dev/block_device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)  # mount -t nilfs2 /dev/block_device /dir
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) This will also invoke the cleaner through the mount helper program
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) (mount.nilfs2).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) Checkpoints and snapshots are managed by the following commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) Their manpages are included in the nilfs-utils package above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)   ====     ===========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)   lscp     list checkpoints or snapshots.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)   mkcp     make a checkpoint or a snapshot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)   chcp     change an existing checkpoint to a snapshot or vice versa.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)   rmcp     invalidate specified checkpoint(s).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)   ====     ===========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) To mount a snapshot::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)  # mount -t nilfs2 -r -o cp=<cno> /dev/block_device /snap_dir
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) where <cno> is the checkpoint number of the snapshot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) To unmount the NILFS2 mount point or snapshot, simply::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)  # umount /dir
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) Then, the cleaner daemon is automatically shut down by the umount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) helper program (umount.nilfs2).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) Disk format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) A nilfs2 volume is equally divided into a number of segments except
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) for the super block (SB) and segment #0.  A segment is the container
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) of logs.  Each log is composed of summary information blocks, payload
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) blocks, and an optional super root block (SR)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)    ______________________________________________________
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)   | |SB| | Segment | Segment | Segment | ... | Segment | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)   |_|__|_|____0____|____1____|____2____|_____|____N____|_|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)   0 +1K +4K       +8M       +16M      +24M  +(8MB x N)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)        .             .            (Typical offsets for 4KB-block)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)     .                  .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)   .______________________.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)   | log | log |... | log |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)   |__1__|__2__|____|__m__|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)         .       .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)       .               .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)     .                       .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)   .______________________________.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)   | Summary | Payload blocks  |SR|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)   |_blocks__|_________________|__|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) The payload blocks are organized per file, and each file consists of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) data blocks and B-tree node blocks::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)     |<---       File-A        --->|<---       File-B        --->|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)    _______________________________________________________________
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)     | Data blocks | B-tree blocks | Data blocks | B-tree blocks | ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)    _|_____________|_______________|_____________|_______________|_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) Since only the modified blocks are written in the log, it may have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) files without data blocks or B-tree node blocks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) The organization of the blocks is recorded in the summary information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) blocks, which contains a header structure (nilfs_segment_summary), per
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) file structures (nilfs_finfo), and per block structures (nilfs_binfo)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)   _________________________________________________________________________
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)  | Summary | finfo | binfo | ... | binfo | finfo | binfo | ... | binfo |...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)  |_blocks__|___A___|_(A,1)_|_____|(A,Na)_|___B___|_(B,1)_|_____|(B,Nb)_|___
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) The logs include regular files, directory files, symbolic link files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) and several meta data files.  The mata data files are the files used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) to maintain file system meta data.  The current version of NILFS2 uses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) the following meta data files::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)  1) Inode file (ifile)             -- Stores on-disk inodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)  2) Checkpoint file (cpfile)       -- Stores checkpoints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)  3) Segment usage file (sufile)    -- Stores allocation state of segments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)  4) Data address translation file  -- Maps virtual block numbers to usual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)     (DAT)                             block numbers.  This file serves to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)                                       make on-disk blocks relocatable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) The following figure shows a typical organization of the logs::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)   _________________________________________________________________________
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)  | Summary | regular file | file  | ... | ifile | cpfile | sufile | DAT |SR|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)  |_blocks__|_or_directory_|_______|_____|_______|________|________|_____|__|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) To stride over segment boundaries, this sequence of files may be split
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) into multiple logs.  The sequence of logs that should be treated as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) logically one log, is delimited with flags marked in the segment
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) summary.  The recovery code of nilfs2 looks this boundary information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) to ensure atomicity of updates.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) The super root block is inserted for every checkpoints.  It includes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) three special inodes, inodes for the DAT, cpfile, and sufile.  Inodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) of regular files, directories, symlinks and other special files, are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) included in the ifile.  The inode of ifile itself is included in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) corresponding checkpoint entry in the cpfile.  Thus, the hierarchy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) among NILFS2 files can be depicted as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)   Super block (SB)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)        |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)        v
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)   Super root block (the latest cno=xx)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)        |-- DAT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)        |-- sufile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)        `-- cpfile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)               |-- ifile (cno=c1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)               |-- ifile (cno=c2) ---- file (ino=i1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)               :        :          |-- file (ino=i2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)               `-- ifile (cno=xx)  |-- file (ino=i3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)                                   :        :
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)                                   `-- file (ino=yy)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)                                     ( regular file, directory, or symlink )
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) For detail on the format of each file, please see nilfs2_ondisk.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) located at include/uapi/linux directory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) There are no patents or other intellectual property that we protect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) with regard to the design of NILFS2.  It is allowed to replicate the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) design in hopes that other operating systems could share (mount, read,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) write, etc.) data stored in this format.