introduce XFS at a high level

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@oracle.com>
Reviewed-by: Christoph Hellwig <hch@lst.de>
Signed-off-by: Dave Chinner <david@fromorbit.com>

4 files changed, 70 insertions, 11 deletions

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@oss.sgi.com+.
+
+[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