[PATCH] D41825: [Docs][PDB] Update MSF File documentation

[Colden Cullen via Phabricator via llvm-commits]

colden created this revision.
colden added reviewers: zturner, rnk.
Herald added a subscriber: llvm-commits.

As long as we have all this super useful knowledge, may as well share it.


Repository:
  rL LLVM

https://reviews.llvm.org/D41825

Files:
  docs/PDB/MsfFile.rst


Index: docs/PDB/MsfFile.rst
===================================================================
--- docs/PDB/MsfFile.rst
+++ docs/PDB/MsfFile.rst
@@ -5,6 +5,43 @@
 .. contents::
    :local:
 
+.. _msf_layout:
+
+File Layout
+===========
+
+The MSF file format consists of the following components:
+
+1. :ref:`msf_superblock`
+2. :ref:`msf_freeblockmap`
+3. Data
+
+Each component is stored as an indexed block, the length of which is specified
+in ``SuperBlock::BlockSize``. After index 0 (:ref:`msf_superblock`), the file
+repeats the following pattern of blocks:
+
+1. Free Block Map 1 (corresponds to ``SuperBlock::FreeBlockMapBlock`` 1)
+2. Free Block Map 2 (corresponds to ``SuperBlock::FreeBlockMapBlock`` 2)
+3. ``SuperBlock::BlockSize - 2`` blocks of data
+
+The file may end after any block, including immediately after a
+Free Block Map 1.
+
+The following diagram demonstrates the general layout of the file:
+
++-------------+-----------------------+------------------+------------------+----------+------+------+-------------+-----+
+| Block Index | 0                     | 1                | 2                | 3 - 4096 | 4097 | 4098 | 4099 - 8192 | ... |
++=============+=======================+==================+==================+==========+======+======+=============+=====+
+| Meaning     | :ref:`msf_superblock` | Free Block Map 1 | Free Block Map 2 | Data     | FBM1 | FBM2 | Data        | ... |
++-------------+-----------------------+------------------+------------------+----------+------+------+-------------+-----+
+
+Each group of FPM1, FPM2, and the following data blocks are sometimes referred
+to as an "interval."
+
+.. note::
+  LLVM only supports 4096 byte blocks (sometimes referred to as the "BigMsf"
+  variant), so the rest of this document will assume a block size of 4096.
+
 .. _msf_superblock:
 
 The Superblock
@@ -32,8 +69,8 @@
   sizes of 4KiB, and all further discussion assumes a block size of 4KiB.
 - **FreeBlockMapBlock** - The index of a block within the file, at which begins
   a bitfield representing the set of all blocks within the file which are "free"
-  (i.e. the data within that block is not used).  This bitfield is spread across
-  the MSF file at ``BlockSize`` intervals.
+  (i.e. the data within that block is not used).  See :ref:`msf_freeblockmap` for
+  more information.
   **Important**: ``FreeBlockMapBlock`` can only be ``1`` or ``2``!  This field
   is designed to support incremental and atomic updates of the underlying MSF
   file.  While writing to an MSF file, if the value of this field is `1`, you
@@ -54,6 +91,20 @@
   directory itself can be stitched together accordingly.  The number of
   ``ulittle32_t``'s in this array is given by ``ceil(NumDirectoryBytes / BlockSize)``.
   
+.. _msf_freeblockmap:
+
+The Free Block Map
+==================
+
+The Free Block Map (sometimes referred to as the Free Page Map, or FPM) is a
+block which contains a byte flag for every block in the interval it desribes.
+The flag will be set to 1 if the block is in use, and 0 if the block is in use.
+Because each interval includes the FPMs associated with it, the first two bytes
+of each FPM refer to FPM1 and FPM2, and are by definition 1 (the FPMs can't be
+unused). The only exception to this rule is the first interval, where byte 0
+refers to the Superblock, bype 1 refers to FPM1, byte 2 refers to FPM2, and
+byte 3 refers to the first data block.
+
 The Stream Directory
 ====================
 The Stream Directory is the root of all access to the other streams in an MSF


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D41825.128944.patch
Type: text/x-patch
Size: 3622 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20180108/f9fc912c/attachment.bin>