Provide a quick overview of the history and design goals of XFS, and specify what exactly this documentation aims to do. Signed-off-by: Darrick J. Wong <darrick.wong@xxxxxxxxxx> --- .../allocation_groups.asciidoc | 9 +++-- design/XFS_Filesystem_Structure/docinfo.xml | 3 +- design/XFS_Filesystem_Structure/overview.asciidoc | 38 ++++++++++++++++++++ .../xfs_filesystem_structure.asciidoc | 31 +++++++++++++--- 4 files changed, 70 insertions(+), 11 deletions(-) create mode 100644 design/XFS_Filesystem_Structure/overview.asciidoc diff --git a/design/XFS_Filesystem_Structure/allocation_groups.asciidoc b/design/XFS_Filesystem_Structure/allocation_groups.asciidoc index 0527ecc..346f1b2 100644 --- a/design/XFS_Filesystem_Structure/allocation_groups.asciidoc +++ b/design/XFS_Filesystem_Structure/allocation_groups.asciidoc @@ -1,10 +1,11 @@ [[Allocation_Groups]] = Allocation Groups -XFS filesystems are divided into a number of equally sized chunks called -Allocation Groups. Each AG can almost be thought of as an individual filesystem -that maintains its own space usage. Each AG can be up to one terabyte in size -(512 bytes × 2^31^), regardless of the underlying device's sector size. +As mentioned earlier, XFS filesystems are divided into a number of equally +sized chunks called Allocation Groups. Each AG can almost be thought of as an +individual filesystem that maintains its own space usage. Each AG can be up to +one terabyte in size (512 bytes × 2^31^), regardless of the underlying device's +sector size. Each AG has the following characteristics: diff --git a/design/XFS_Filesystem_Structure/docinfo.xml b/design/XFS_Filesystem_Structure/docinfo.xml index 85ccda5..6620acf 100644 --- a/design/XFS_Filesystem_Structure/docinfo.xml +++ b/design/XFS_Filesystem_Structure/docinfo.xml @@ -1,7 +1,7 @@ <subtitle>3rd Edition</subtitle> <!-- <abstract> - <para>This book documents the XFS Filesystem Structure</para> + <para>This book documents the on-disk structure of the XFS filesystem.</para> </abstract> --> <corpauthor> @@ -84,6 +84,7 @@ <member>Miscellaneous fixes.</member> <member>Add missing field definitions.</member> <member>Add some missing xfs_db examples.</member> + <member>Add an overview of XFS.</member> </simplelist> </revdescription> </revision> diff --git a/design/XFS_Filesystem_Structure/overview.asciidoc b/design/XFS_Filesystem_Structure/overview.asciidoc new file mode 100644 index 0000000..d15b50a --- /dev/null +++ b/design/XFS_Filesystem_Structure/overview.asciidoc @@ -0,0 +1,38 @@ += Overview + +XFS presents to users a standard Unix filesystem interface: a rooted +tree of directories, files, symbolic links, and devices. All five of those +entities are represented inside the filesystem by an index node, or ``inode''; +each node is uniquely referenced by an inode number. Directories consist of +(name, inode number) tuples and it is possible for multiple tuples to contain +the same inode number. Data blocks are associated with files by means of a +block map in each index node. It is also possible to attach (key, value) +tuples to any index node; these are known as ``extended attributes'', which +extend beyond the standard Unix file attributes. + +Internally, XFS filesystems are divided into a number of equally sized chunks +called Allocation Groups. Each AG can almost be thought of as an individual +filesystem that maintains its own space usage, index nodes, and other secondary +metadata. Having multiple AGs allows XFS to handle most operations in parallel +without degrading performance as the number of concurrent accesses increases. +Each allocation group uses multiple B+trees to maintain bookkeeping records +such as the locations of free blocks, the locations of allocated inodes, and +the locations of free inodes. + +Files, symbolic links, and directories can have up to two block maps, or +``forks'', which associate filesystems blocks with a particular file or +directory. The ``attribute fork'' tracks blocks used to store and index +extended attributes, whereas the ``data fork'' tracks file data blocks, +symbolic link targets, or directory blocks, depending on the type of the inode +record. Both forks associate a logical offset with an extent of physical +blocks, which makes sparse files and directories possible. Directory entries +and extended attributes are contained inside a second-level data structure +within the blocks that are mapped by the forks. This structure consists of +variable-length directory or attribute records and possible a second B+tree to +index these records. + +XFS employs a journalling log in which metadata changes are collected so that +filesystem operations can be carried out atomically in the case of a crash. +Furthermore, there is the concept of a real-time device wherein allocations are +tracked more simply and in larger chunks to reduce jitter in allocation +latency. diff --git a/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc b/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc index a78f3b9..9f4c096 100644 --- a/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc +++ b/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc @@ -16,17 +16,36 @@ High Level Design [partintro] -- -This document describes the layout of an XFS filesystem. - -It shows how to manually inspect it by showing examples using the xfs_db -user-space tool supplied with the XFS filesystem driver. - -TODO: More description. +XFS is a high performance filesystem which was designed to maximize parallel +throughput and to scale up to extremely large 64-bit storage systems. +Originally developed by SGI in October 1993 for IRIX, XFS can handle large +files, large filesystems, many inodes, large directories, large file +attributes, and large allocations. Filesystems are optimized for parallel +access by splitting the storage device into semi-autonomous allocation groups. +XFS employs branching trees (B+ trees) to facilitate fast searches of large +lists; it also uses delayed extent-based allocation to improve data contiguity +and IO performance. + +This document describes the on-disk layout of an XFS filesystem and how to use +the debugging tools +xfs_db+ and +xfs_logprint+ to inspect the metadata +structures. It also describes how on-disk metadata relates to the higher level +design goals. + +The information contained in this document derives from the XFS source code in +the Linux kernel as of v4.3. This book's source code is available at ++git://git.kernel.org/pub/scm/fs/xfs/xfs-documentation.git+. Feedback should +be sent to the XFS mailing list, currently at +xfs@xxxxxxxxxxx+. + +[NOTE] +All fields in XFS metadata structures are in big-endian byte order except for +log items which are formatted in host order. -- // Push titles down one level :leveloffset: 1 +include::overview.asciidoc[] + include::common_types.asciidoc[] // return titles to normal _______________________________________________ xfs mailing list xfs@xxxxxxxxxxx http://oss.sgi.com/mailman/listinfo/xfs
