import-on-disk-layout-book-from-wiki-page

   1 ext4: import on-disk layout book from wiki page
   2
   3 From: Darrick J. Wong <darrick.wong@oracle.com>
   4
   5 Create the basic structure of the "new" data structures & algorithms
   6 book to be ported over from the on-disk format wiki, and then start by
   7 pulling in the introductory information.
   8
   9 Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
  10 Signed-off-by: Theodore Ts'o <tytso@mit.edu>
  11 ---
  12 v2: fix subject line bogosity
  13 ---
  14  Documentation/filesystems/ext4/index.rst        |    1 +
  15  Documentation/filesystems/ext4/ondisk/about.rst |   44 +++++++++++++++++++++++
  16  Documentation/filesystems/ext4/ondisk/index.rst |    6 +++
  17  3 files changed, 51 insertions(+)
  18  create mode 100644 Documentation/filesystems/ext4/ondisk/about.rst
  19  create mode 100644 Documentation/filesystems/ext4/ondisk/index.rst
  20
  21 diff --git a/Documentation/filesystems/ext4/index.rst b/Documentation/filesystems/ext4/index.rst
  22 index 1270b34f643f..8fe4f7693e8c 100644
  23 --- a/Documentation/filesystems/ext4/index.rst
  24 +++ b/Documentation/filesystems/ext4/index.rst
  25 @@ -14,3 +14,4 @@ the ext4 community.
  26     :numbered:
  27
  28     ext4
  29 +   ondisk/index
  30 diff --git a/Documentation/filesystems/ext4/ondisk/about.rst b/Documentation/filesystems/ext4/ondisk/about.rst
  31 new file mode 100644
  32 index 000000000000..0aadba052264
  33 --- /dev/null
  34 +++ b/Documentation/filesystems/ext4/ondisk/about.rst
  35 @@ -0,0 +1,44 @@
  36 +.. SPDX-License-Identifier: GPL-2.0
  37 +
  38 +About this Book
  39 +===============
  40 +
  41 +This document attempts to describe the on-disk format for ext4
  42 +filesystems. The same general ideas should apply to ext2/3 filesystems
  43 +as well, though they do not support all the features that ext4 supports,
  44 +and the fields will be shorter.
  45 +
  46 +**NOTE**: This is a work in progress, based on notes that the author
  47 +(djwong) made while picking apart a filesystem by hand. The data
  48 +structure definitions should be current as of Linux 4.18 and
  49 +e2fsprogs-1.44. All comments and corrections are welcome, since there is
  50 +undoubtedly plenty of lore that might not be reflected in freshly
  51 +created demonstration filesystems.
  52 +
  53 +License
  54 +-------
  55 +This book is licensed under the terms of the GNU Public License, v2.
  56 +
  57 +Terminology
  58 +-----------
  59 +
  60 +ext4 divides a storage device into an array of logical blocks both to
  61 +reduce bookkeeping overhead and to increase throughput by forcing larger
  62 +transfer sizes. Generally, the block size will be 4KiB (the same size as
  63 +pages on x86 and the block layer's default block size), though the
  64 +actual size is calculated as 2 ^ (10 + ``sb.s_log_block_size``) bytes.
  65 +Throughout this document, disk locations are given in terms of these
  66 +logical blocks, not raw LBAs, and not 1024-byte blocks. For the sake of
  67 +convenience, the logical block size will be referred to as
  68 +``$block_size`` throughout the rest of the document.
  69 +
  70 +When referenced in ``preformatted text`` blocks, ``sb`` refers to fields
  71 +in the super block, and ``inode`` refers to fields in an inode table
  72 +entry.
  73 +
  74 +Other References
  75 +----------------
  76 +
  77 +Also see http://www.nongnu.org/ext2-doc/ for quite a collection of
  78 +information about ext2/3. Here's another old reference:
  79 +http://wiki.osdev.org/Ext2
  80 diff --git a/Documentation/filesystems/ext4/ondisk/index.rst b/Documentation/filesystems/ext4/ondisk/index.rst
  81 new file mode 100644
  82 index 000000000000..98cde12ee8cb
  83 --- /dev/null
  84 +++ b/Documentation/filesystems/ext4/ondisk/index.rst
  85 @@ -0,0 +1,6 @@
  86 +.. SPDX-License-Identifier: GPL-2.0
  87 +
  88 +==============================
  89 +Data Structures and Algorithms
  90 +==============================
  91 +.. include:: about.rst
  92