Commit fc2f6fe7 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

docs: filesystems: convert xfs-self-describing-metadata.txt to ReST 



- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/7c26b200e12cfc07b9bd379612452d845a8d1474.1588021877.git.mchehab+huawei@kernel.org


Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent c3d2f6cb

Documentation/filesystems/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -118,4 +118,5 @@ Documentation for filesystem implementations. 
   virtiofs

   vfat

   xfs-delayed-logging-design

   xfs-self-describing-metadata

   zonefs

Documentation/filesystems/xfs-self-describing-metadata.txt→Documentation/filesystems/xfs-self-describing-metadata.rst

+96 −94
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



============================

XFS Self Describing Metadata

----------------------------

============================



Introduction

------------

============



The largest scalability problem facing XFS is not one of algorithmic

scalability, but of verification of the filesystem structure. Scalabilty of the
@@ -34,7 +37,7 @@ required for basic forensic analysis of the filesystem structure. 




Self Describing Metadata

------------------------

========================



One of the problems with the current metadata format is that apart from the

magic number in the metadata block, we have no other way of identifying what it
@@ -142,7 +145,7 @@ modification occurred between the corruption being written and when it was 
detected.



Runtime Validation

------------------

==================



Validation of self-describing metadata takes place at runtime in two places:
@@ -183,9 +186,9 @@ error occurs during this process, the buffer is again marked with a EFSCORRUPTED 
error for the higher layers to catch.



Structures

----------

==========



A typical on-disk structure needs to contain the following information:

A typical on-disk structure needs to contain the following information::



    struct xfs_ondisk_hdr {

	    __be32  magic;		/* magic number */
@@ -214,7 +217,7 @@ level of information is generally provided. For example: 
	  well. hence the additional metadata headers change the overall format

	  of the metadata.



A typical buffer read verifier is structured as follows:

A typical buffer read verifier is structured as follows::



    #define XFS_FOO_CRC_OFF		offsetof(struct xfs_ondisk_hdr, crc)
@@ -239,7 +242,7 @@ by checking the superblock of the feature bit, and then if the CRC verifies OK 


The verifier function will take a couple of different forms, depending on

whether the magic number can be used to determine the format of the block. In

the case it can't, the code is structured as follows:

the case it can't, the code is structured as follows::



    static bool

    xfs_foo_verify(
@@ -266,7 +269,7 @@ xfs_foo_verify( 
    }



If there are different magic numbers for the different formats, the verifier

will look like:

will look like::



    static bool

    xfs_foo_verify(
@@ -291,7 +294,7 @@ xfs_foo_verify( 
    }



Write verifiers are very similar to the read verifiers, they just do things in

the opposite order to the read verifiers. A typical write verifier:

the opposite order to the read verifiers. A typical write verifier::



    static void

    xfs_foo_write_verify(
@@ -324,7 +327,7 @@ update the LSN field (when it was last modified) and calculate the CRC on the 
metadata. Once this is done, we can issue the IO.



Inodes and Dquots

-----------------

=================



Inodes and dquots are special snowflakes. They have per-object CRC and

self-identifiers, but they are packed so that there are multiple objects per
@@ -347,4 +350,3 @@ XXX: inode unlinked list modification doesn't recalculate the inode CRC! None of 
the unlinked list modifications check or update CRCs, neither during unlink nor

log recovery. So, it's gone unnoticed until now. This won't matter immediately -

repair will probably complain about it - but it needs to be fixed.

MAINTAINERS

+1 −1
Original line number Diff line number Diff line
@@ -18534,7 +18534,7 @@ T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git 
F:	Documentation/ABI/testing/sysfs-fs-xfs

F:	Documentation/admin-guide/xfs.rst

F:	Documentation/filesystems/xfs-delayed-logging-design.rst

F:	Documentation/filesystems/xfs-self-describing-metadata.txt

F:	Documentation/filesystems/xfs-self-describing-metadata.rst

F:	fs/xfs/

F:	include/uapi/linux/dqblk_xfs.h

F:	include/uapi/linux/fsmap.h

CRA Git | Maintained and supported by SUSTech CRA and CCSE