* [PATCH 00/34] fs: convert remaining docs to ReST file format
@ 2020-04-15 14:32 Mauro Carvalho Chehab
2020-04-15 14:32 ` [PATCH 33/34] docs: filesystems: convert xfs-delayed-logging-design.txt to ReST Mauro Carvalho Chehab
2020-04-15 14:32 ` [PATCH 34/34] docs: filesystems: convert xfs-self-describing-metadata.txt " Mauro Carvalho Chehab
0 siblings, 2 replies; 3+ messages in thread
From: Mauro Carvalho Chehab @ 2020-04-15 14:32 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Alexander Viro, linuxppc-dev, linux-arm-msm, dri-devel,
freedreno, linux-fsdevel, linux-afs, ecryptfs, linux-ntfs-dev,
ocfs2-devel, linux-unionfs, linux-cachefs, linux-usb, codalist,
linux-ext4, cluster-devel, linux-xfs
This patch series convert the remaining files under Documentation/filesystems
to the ReST file format. It is based on linux-next (next-20200414).
PS.: I opted to add mainly ML from the output of get_maintainers.pl to the c/c
list of patch 00/34, because otherwise the number of c/c would be too many,
with would very likely cause ML servers to reject it.
The results of those changes (together with other changes from my pending
doc patches) are available at:
https://www.infradead.org/~mchehab/kernel_docs/filesystems/index.html
Mauro Carvalho Chehab (34):
docs: filesystems: fix references for doc files there
docs: filesystems: convert caching/object.txt to ReST
docs: filesystems: convert caching/fscache.txt to ReST format
docs: filesystems: caching/netfs-api.txt: convert it to ReST
docs: filesystems: caching/operations.txt: convert it to ReST
docs: filesystems: caching/cachefiles.txt: convert to ReST
docs: filesystems: caching/backend-api.txt: convert it to ReST
docs: filesystems: convert cifs/cifsroot.rst to ReST
docs: filesystems: convert configfs.txt to ReST
docs: filesystems: convert automount-support.txt to ReST
docs: filesystems: convert coda.txt to ReST
docs: filesystems: convert dax.txt to ReST
docs: filesystems: convert devpts.txt to ReST
docs: filesystems: convert dnotify.txt to ReST
docs: filesystems: convert fiemap.txt to ReST
docs: filesystems: convert files.txt to ReST
docs: filesystems: convert fuse-io.txt to ReST
docs: filesystems: convert gfs2-glocks.txt to ReST
docs: filesystems: convert locks.txt to ReST
docs: filesystems: convert mandatory-locking.txt to ReST
docs: filesystems: convert mount_api.txt to ReST
docs: filesystems: rename path-lookup.txt file
docs: filesystems: convert path-walking.txt to ReST
docs: filesystems: convert quota.txt to ReST
docs: filesystems: convert seq_file.txt to ReST
docs: filesystems: convert sharedsubtree.txt to ReST
docs: filesystems: split spufs.txt into 3 separate files
docs: filesystems: convert spufs/spu_create.txt to ReST
docs: filesystems: convert spufs/spufs.txt to ReST
docs: filesystems: convert spufs/spu_run.txt to ReST
docs: filesystems: convert sysfs-pci.txt to ReST
docs: filesystems: convert sysfs-tagging.txt to ReST
docs: filesystems: convert xfs-delayed-logging-design.txt to ReST
docs: filesystems: convert xfs-self-describing-metadata.txt to ReST
Documentation/ABI/stable/sysfs-devices-node | 2 +-
Documentation/ABI/testing/procfs-smaps_rollup | 2 +-
Documentation/admin-guide/cpu-load.rst | 2 +-
Documentation/admin-guide/ext4.rst | 2 +-
Documentation/admin-guide/nfs/nfsroot.rst | 2 +-
Documentation/admin-guide/sysctl/kernel.rst | 2 +-
.../driver-api/driver-model/device.rst | 2 +-
.../driver-api/driver-model/overview.rst | 2 +-
...ount-support.txt => automount-support.rst} | 23 +-
.../{backend-api.txt => backend-api.rst} | 165 +-
.../{cachefiles.txt => cachefiles.rst} | 139 +-
Documentation/filesystems/caching/fscache.rst | 565 ++++++
Documentation/filesystems/caching/fscache.txt | 448 -----
Documentation/filesystems/caching/index.rst | 14 +
.../caching/{netfs-api.txt => netfs-api.rst} | 172 +-
.../caching/{object.txt => object.rst} | 43 +-
.../{operations.txt => operations.rst} | 45 +-
.../cifs/{cifsroot.txt => cifsroot.rst} | 56 +-
Documentation/filesystems/coda.rst | 1670 ++++++++++++++++
Documentation/filesystems/coda.txt | 1676 -----------------
.../{configfs/configfs.txt => configfs.rst} | 129 +-
.../filesystems/{dax.txt => dax.rst} | 11 +-
Documentation/filesystems/devpts.rst | 36 +
Documentation/filesystems/devpts.txt | 26 -
.../filesystems/{dnotify.txt => dnotify.rst} | 13 +-
Documentation/filesystems/ext2.rst | 2 +-
.../filesystems/{fiemap.txt => fiemap.rst} | 133 +-
.../filesystems/{files.txt => files.rst} | 15 +-
.../filesystems/{fuse-io.txt => fuse-io.rst} | 6 +
.../{gfs2-glocks.txt => gfs2-glocks.rst} | 147 +-
Documentation/filesystems/index.rst | 26 +
.../filesystems/{locks.txt => locks.rst} | 14 +-
...tory-locking.txt => mandatory-locking.rst} | 25 +-
.../{mount_api.txt => mount_api.rst} | 329 ++--
.../{path-lookup.txt => path-walking.rst} | 88 +-
Documentation/filesystems/porting.rst | 2 +-
Documentation/filesystems/proc.rst | 2 +-
.../filesystems/{quota.txt => quota.rst} | 41 +-
.../filesystems/ramfs-rootfs-initramfs.rst | 2 +-
.../{seq_file.txt => seq_file.rst} | 61 +-
.../{sharedsubtree.txt => sharedsubtree.rst} | 394 ++--
Documentation/filesystems/spufs/index.rst | 13 +
.../filesystems/spufs/spu_create.rst | 131 ++
Documentation/filesystems/spufs/spu_run.rst | 138 ++
.../{spufs.txt => spufs/spufs.rst} | 304 +--
.../{sysfs-pci.txt => sysfs-pci.rst} | 23 +-
.../{sysfs-tagging.txt => sysfs-tagging.rst} | 22 +-
...ign.txt => xfs-delayed-logging-design.rst} | 65 +-
...a.txt => xfs-self-describing-metadata.rst} | 182 +-
Documentation/iio/iio_configfs.rst | 2 +-
.../powerpc/firmware-assisted-dump.rst | 2 +-
Documentation/process/adding-syscalls.rst | 2 +-
.../it_IT/process/adding-syscalls.rst | 2 +-
.../translations/zh_CN/filesystems/sysfs.txt | 6 +-
Documentation/usb/gadget_configfs.rst | 4 +-
MAINTAINERS | 16 +-
drivers/gpu/drm/msm/disp/dpu1/dpu_kms.h | 2 +-
fs/Kconfig | 2 +-
fs/Kconfig.binfmt | 2 +-
fs/adfs/Kconfig | 2 +-
fs/affs/Kconfig | 2 +-
fs/afs/Kconfig | 6 +-
fs/bfs/Kconfig | 2 +-
fs/cachefiles/Kconfig | 4 +-
fs/coda/Kconfig | 2 +-
fs/configfs/inode.c | 2 +-
fs/configfs/item.c | 2 +-
fs/cramfs/Kconfig | 2 +-
fs/dcache.c | 6 +-
fs/ecryptfs/Kconfig | 2 +-
fs/fat/Kconfig | 8 +-
fs/fscache/Kconfig | 8 +-
fs/fscache/cache.c | 8 +-
fs/fscache/cookie.c | 2 +-
fs/fscache/object.c | 4 +-
fs/fscache/operation.c | 2 +-
fs/fuse/Kconfig | 2 +-
fs/fuse/dev.c | 2 +-
fs/hfs/Kconfig | 2 +-
fs/hpfs/Kconfig | 2 +-
fs/isofs/Kconfig | 2 +-
fs/locks.c | 2 +-
fs/namei.c | 2 +-
fs/namespace.c | 2 +-
fs/notify/inotify/Kconfig | 2 +-
fs/ntfs/Kconfig | 2 +-
fs/ocfs2/Kconfig | 2 +-
fs/overlayfs/Kconfig | 6 +-
fs/proc/Kconfig | 4 +-
fs/romfs/Kconfig | 2 +-
fs/sysfs/dir.c | 2 +-
fs/sysfs/file.c | 2 +-
fs/sysfs/mount.c | 2 +-
fs/sysfs/symlink.c | 2 +-
fs/sysv/Kconfig | 2 +-
fs/udf/Kconfig | 2 +-
include/linux/configfs.h | 2 +-
include/linux/fs_context.h | 2 +-
include/linux/fscache-cache.h | 4 +-
include/linux/fscache.h | 42 +-
include/linux/lsm_hooks.h | 2 +-
include/linux/relay.h | 2 +-
include/linux/sysfs.h | 2 +-
kernel/relay.c | 2 +-
104 files changed, 4048 insertions(+), 3572 deletions(-)
rename Documentation/filesystems/{automount-support.txt => automount-support.rst} (92%)
rename Documentation/filesystems/caching/{backend-api.txt => backend-api.rst} (87%)
rename Documentation/filesystems/caching/{cachefiles.txt => cachefiles.rst} (90%)
create mode 100644 Documentation/filesystems/caching/fscache.rst
delete mode 100644 Documentation/filesystems/caching/fscache.txt
create mode 100644 Documentation/filesystems/caching/index.rst
rename Documentation/filesystems/caching/{netfs-api.txt => netfs-api.rst} (91%)
rename Documentation/filesystems/caching/{object.txt => object.rst} (95%)
rename Documentation/filesystems/caching/{operations.txt => operations.rst} (90%)
rename Documentation/filesystems/cifs/{cifsroot.txt => cifsroot.rst} (72%)
create mode 100644 Documentation/filesystems/coda.rst
delete mode 100644 Documentation/filesystems/coda.txt
rename Documentation/filesystems/{configfs/configfs.txt => configfs.rst} (87%)
rename Documentation/filesystems/{dax.txt => dax.rst} (96%)
create mode 100644 Documentation/filesystems/devpts.rst
delete mode 100644 Documentation/filesystems/devpts.txt
rename Documentation/filesystems/{dnotify.txt => dnotify.rst} (88%)
rename Documentation/filesystems/{fiemap.txt => fiemap.rst} (70%)
rename Documentation/filesystems/{files.txt => files.rst} (95%)
rename Documentation/filesystems/{fuse-io.txt => fuse-io.rst} (95%)
rename Documentation/filesystems/{gfs2-glocks.txt => gfs2-glocks.rst} (63%)
rename Documentation/filesystems/{locks.txt => locks.rst} (91%)
rename Documentation/filesystems/{mandatory-locking.txt => mandatory-locking.rst} (91%)
rename Documentation/filesystems/{mount_api.txt => mount_api.rst} (79%)
rename Documentation/filesystems/{path-lookup.txt => path-walking.rst} (91%)
rename Documentation/filesystems/{quota.txt => quota.rst} (81%)
rename Documentation/filesystems/{seq_file.txt => seq_file.rst} (92%)
rename Documentation/filesystems/{sharedsubtree.txt => sharedsubtree.rst} (72%)
create mode 100644 Documentation/filesystems/spufs/index.rst
create mode 100644 Documentation/filesystems/spufs/spu_create.rst
create mode 100644 Documentation/filesystems/spufs/spu_run.rst
rename Documentation/filesystems/{spufs.txt => spufs/spufs.rst} (57%)
rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (92%)
rename Documentation/filesystems/{sysfs-tagging.txt => sysfs-tagging.rst} (72%)
rename Documentation/filesystems/{xfs-delayed-logging-design.txt => xfs-delayed-logging-design.rst} (97%)
rename Documentation/filesystems/{xfs-self-describing-metadata.txt => xfs-self-describing-metadata.rst} (83%)
--
2.25.2
^ permalink raw reply [flat|nested] 3+ messages in thread
* [PATCH 33/34] docs: filesystems: convert xfs-delayed-logging-design.txt to ReST
2020-04-15 14:32 [PATCH 00/34] fs: convert remaining docs to ReST file format Mauro Carvalho Chehab
@ 2020-04-15 14:32 ` Mauro Carvalho Chehab
2020-04-15 14:32 ` [PATCH 34/34] docs: filesystems: convert xfs-self-describing-metadata.txt " Mauro Carvalho Chehab
1 sibling, 0 replies; 3+ messages in thread
From: Mauro Carvalho Chehab @ 2020-04-15 14:32 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Darrick J. Wong, linux-xfs
- 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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/filesystems/index.rst | 1 +
...ign.txt => xfs-delayed-logging-design.rst} | 65 +++++++++++--------
MAINTAINERS | 2 +-
3 files changed, 40 insertions(+), 28 deletions(-)
rename Documentation/filesystems/{xfs-delayed-logging-design.txt => xfs-delayed-logging-design.rst} (97%)
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 687fe64d8b5c..70c0e0b29e74 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -121,4 +121,5 @@ Documentation for filesystem implementations.
udf
virtiofs
vfat
+ xfs-delayed-logging-design
zonefs
diff --git a/Documentation/filesystems/xfs-delayed-logging-design.txt b/Documentation/filesystems/xfs-delayed-logging-design.rst
similarity index 97%
rename from Documentation/filesystems/xfs-delayed-logging-design.txt
rename to Documentation/filesystems/xfs-delayed-logging-design.rst
index 9a6dd289b17b..464405d2801e 100644
--- a/Documentation/filesystems/xfs-delayed-logging-design.txt
+++ b/Documentation/filesystems/xfs-delayed-logging-design.rst
@@ -1,8 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
XFS Delayed Logging Design
---------------------------
+==========================
Introduction to Re-logging in XFS
----------------------------------
+=================================
XFS logging is a combination of logical and physical logging. Some objects,
such as inodes and dquots, are logged in logical format where the details
@@ -25,7 +28,7 @@ changes in the new transaction that is written to the log.
That is, if we have a sequence of changes A through to F, and the object was
written to disk after change D, we would see in the log the following series
of transactions, their contents and the log sequence number (LSN) of the
-transaction:
+transaction::
Transaction Contents LSN
A A X
@@ -85,7 +88,7 @@ IO permanently. Hence the XFS journalling subsystem can be considered to be IO
bound.
Delayed Logging: Concepts
--------------------------
+=========================
The key thing to note about the asynchronous logging combined with the
relogging technique XFS uses is that we can be relogging changed objects
@@ -154,9 +157,10 @@ The fundamental requirements for delayed logging in XFS are simple:
6. No performance regressions for synchronous transaction workloads.
Delayed Logging: Design
------------------------
+=======================
Storing Changes
+---------------
The problem with accumulating changes at a logical level (i.e. just using the
existing log item dirty region tracking) is that when it comes to writing the
@@ -194,30 +198,30 @@ asynchronous transactions to the log. The differences between the existing
formatting method and the delayed logging formatting can be seen in the
diagram below.
-Current format log vector:
+Current format log vector::
-Object +---------------------------------------------+
-Vector 1 +----+
-Vector 2 +----+
-Vector 3 +----------+
+ Object +---------------------------------------------+
+ Vector 1 +----+
+ Vector 2 +----+
+ Vector 3 +----------+
-After formatting:
+After formatting::
-Log Buffer +-V1-+-V2-+----V3----+
+ Log Buffer +-V1-+-V2-+----V3----+
-Delayed logging vector:
+Delayed logging vector::
-Object +---------------------------------------------+
-Vector 1 +----+
-Vector 2 +----+
-Vector 3 +----------+
+ Object +---------------------------------------------+
+ Vector 1 +----+
+ Vector 2 +----+
+ Vector 3 +----------+
-After formatting:
+After formatting::
-Memory Buffer +-V1-+-V2-+----V3----+
-Vector 1 +----+
-Vector 2 +----+
-Vector 3 +----------+
+ Memory Buffer +-V1-+-V2-+----V3----+
+ Vector 1 +----+
+ Vector 2 +----+
+ Vector 3 +----------+
The memory buffer and associated vector need to be passed as a single object,
but still need to be associated with the parent object so if the object is
@@ -242,6 +246,7 @@ relogged in memory.
Tracking Changes
+----------------
Now that we can record transactional changes in memory in a form that allows
them to be used without limitations, we need to be able to track and accumulate
@@ -278,6 +283,7 @@ done for convenience/sanity of the developers.
Delayed Logging: Checkpoints
+----------------------------
When we have a log synchronisation event, commonly known as a "log force",
all the items in the CIL must be written into the log via the log buffers.
@@ -341,7 +347,7 @@ Hence log vectors need to be able to be chained together to allow them to be
detached from the log items. That is, when the CIL is flushed the memory
buffer and log vector attached to each log item needs to be attached to the
checkpoint context so that the log item can be released. In diagrammatic form,
-the CIL would look like this before the flush:
+the CIL would look like this before the flush::
CIL Head
|
@@ -362,7 +368,7 @@ the CIL would look like this before the flush:
-> vector array
And after the flush the CIL head is empty, and the checkpoint context log
-vector list would look like:
+vector list would look like::
Checkpoint Context
|
@@ -411,6 +417,7 @@ compare" situation that can be done after a working and reviewed implementation
is in the dev tree....
Delayed Logging: Checkpoint Sequencing
+--------------------------------------
One of the key aspects of the XFS transaction subsystem is that it tags
committed transactions with the log sequence number of the transaction commit.
@@ -474,6 +481,7 @@ force the log at the LSN of that transaction) and so the higher level code
behaves the same regardless of whether delayed logging is being used or not.
Delayed Logging: Checkpoint Log Space Accounting
+------------------------------------------------
The big issue for a checkpoint transaction is the log space reservation for the
transaction. We don't know how big a checkpoint transaction is going to be
@@ -491,7 +499,7 @@ the size of the transaction and the number of regions being logged (the number
of log vectors in the transaction).
An example of the differences would be logging directory changes versus logging
-inode changes. If you modify lots of inode cores (e.g. chmod -R g+w *), then
+inode changes. If you modify lots of inode cores (e.g. ``chmod -R g+w *``), then
there are lots of transactions that only contain an inode core and an inode log
format structure. That is, two vectors totaling roughly 150 bytes. If we modify
10,000 inodes, we have about 1.5MB of metadata to write in 20,000 vectors. Each
@@ -565,6 +573,7 @@ which is once every 30s.
Delayed Logging: Log Item Pinning
+---------------------------------
Currently log items are pinned during transaction commit while the items are
still locked. This happens just after the items are formatted, though it could
@@ -605,6 +614,7 @@ object, we have a race with CIL being flushed between the check and the pin
lock to guarantee that we pin the items correctly.
Delayed Logging: Concurrent Scalability
+---------------------------------------
A fundamental requirement for the CIL is that accesses through transaction
commits must scale to many concurrent commits. The current transaction commit
@@ -683,8 +693,9 @@ woken by the wrong event.
Lifecycle Changes
+-----------------
-The existing log item life cycle is as follows:
+The existing log item life cycle is as follows::
1. Transaction allocate
2. Transaction reserve
@@ -729,7 +740,7 @@ at the same time. If the log item is in the AIL or between steps 6 and 7
and steps 1-6 are re-entered, then the item is relogged. Only when steps 8-9
are entered and completed is the object considered clean.
-With delayed logging, there are new steps inserted into the life cycle:
+With delayed logging, there are new steps inserted into the life cycle::
1. Transaction allocate
2. Transaction reserve
diff --git a/MAINTAINERS b/MAINTAINERS
index 2ac15ec9ebf8..c52991586853 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -18551,7 +18551,7 @@ W: http://xfs.org/
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.txt
+F: Documentation/filesystems/xfs-delayed-logging-design.rst
F: Documentation/filesystems/xfs-self-describing-metadata.txt
F: fs/xfs/
F: include/uapi/linux/dqblk_xfs.h
--
2.25.2
^ permalink raw reply related [flat|nested] 3+ messages in thread
* [PATCH 34/34] docs: filesystems: convert xfs-self-describing-metadata.txt to ReST
2020-04-15 14:32 [PATCH 00/34] fs: convert remaining docs to ReST file format Mauro Carvalho Chehab
2020-04-15 14:32 ` [PATCH 33/34] docs: filesystems: convert xfs-delayed-logging-design.txt to ReST Mauro Carvalho Chehab
@ 2020-04-15 14:32 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 3+ messages in thread
From: Mauro Carvalho Chehab @ 2020-04-15 14:32 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Darrick J. Wong, linux-xfs
- 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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/filesystems/index.rst | 1 +
...a.txt => xfs-self-describing-metadata.rst} | 182 +++++++++---------
MAINTAINERS | 2 +-
3 files changed, 94 insertions(+), 91 deletions(-)
rename Documentation/filesystems/{xfs-self-describing-metadata.txt => xfs-self-describing-metadata.rst} (83%)
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 70c0e0b29e74..61d5be3f6f9a 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -122,4 +122,5 @@ Documentation for filesystem implementations.
virtiofs
vfat
xfs-delayed-logging-design
+ xfs-self-describing-metadata
zonefs
diff --git a/Documentation/filesystems/xfs-self-describing-metadata.txt b/Documentation/filesystems/xfs-self-describing-metadata.rst
similarity index 83%
rename from Documentation/filesystems/xfs-self-describing-metadata.txt
rename to Documentation/filesystems/xfs-self-describing-metadata.rst
index 8db0121d0980..51cdafe01ab1 100644
--- a/Documentation/filesystems/xfs-self-describing-metadata.txt
+++ b/Documentation/filesystems/xfs-self-describing-metadata.rst
@@ -1,8 +1,11 @@
+.. 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,18 +186,18 @@ 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 */
- __be32 crc; /* CRC, not logged */
- uuid_t uuid; /* filesystem identifier */
- __be64 owner; /* parent object */
- __be64 blkno; /* location on disk */
- __be64 lsn; /* last modification in log, not logged */
-};
+ struct xfs_ondisk_hdr {
+ __be32 magic; /* magic number */
+ __be32 crc; /* CRC, not logged */
+ uuid_t uuid; /* filesystem identifier */
+ __be64 owner; /* parent object */
+ __be64 blkno; /* location on disk */
+ __be64 lsn; /* last modification in log, not logged */
+ };
Depending on the metadata, this information may be part of a header structure
separate to the metadata contents, or may be distributed through an existing
@@ -214,24 +217,24 @@ 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)
+ #define XFS_FOO_CRC_OFF offsetof(struct xfs_ondisk_hdr, crc)
-static void
-xfs_foo_read_verify(
- struct xfs_buf *bp)
-{
- struct xfs_mount *mp = bp->b_mount;
+ static void
+ xfs_foo_read_verify(
+ struct xfs_buf *bp)
+ {
+ struct xfs_mount *mp = bp->b_mount;
- if ((xfs_sb_version_hascrc(&mp->m_sb) &&
- !xfs_verify_cksum(bp->b_addr, BBTOB(bp->b_length),
- XFS_FOO_CRC_OFF)) ||
- !xfs_foo_verify(bp)) {
- XFS_CORRUPTION_ERROR(__func__, XFS_ERRLEVEL_LOW, mp, bp->b_addr);
- xfs_buf_ioerror(bp, EFSCORRUPTED);
- }
-}
+ if ((xfs_sb_version_hascrc(&mp->m_sb) &&
+ !xfs_verify_cksum(bp->b_addr, BBTOB(bp->b_length),
+ XFS_FOO_CRC_OFF)) ||
+ !xfs_foo_verify(bp)) {
+ XFS_CORRUPTION_ERROR(__func__, XFS_ERRLEVEL_LOW, mp, bp->b_addr);
+ xfs_buf_ioerror(bp, EFSCORRUPTED);
+ }
+ }
The code ensures that the CRC is only checked if the filesystem has CRCs enabled
by checking the superblock of the feature bit, and then if the CRC verifies OK
@@ -239,83 +242,83 @@ 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(
- struct xfs_buf *bp)
-{
- struct xfs_mount *mp = bp->b_mount;
- struct xfs_ondisk_hdr *hdr = bp->b_addr;
+ static bool
+ xfs_foo_verify(
+ struct xfs_buf *bp)
+ {
+ struct xfs_mount *mp = bp->b_mount;
+ struct xfs_ondisk_hdr *hdr = bp->b_addr;
- if (hdr->magic != cpu_to_be32(XFS_FOO_MAGIC))
- return false;
+ if (hdr->magic != cpu_to_be32(XFS_FOO_MAGIC))
+ return false;
- if (!xfs_sb_version_hascrc(&mp->m_sb)) {
- if (!uuid_equal(&hdr->uuid, &mp->m_sb.sb_uuid))
- return false;
- if (bp->b_bn != be64_to_cpu(hdr->blkno))
- return false;
- if (hdr->owner == 0)
- return false;
- }
+ if (!xfs_sb_version_hascrc(&mp->m_sb)) {
+ if (!uuid_equal(&hdr->uuid, &mp->m_sb.sb_uuid))
+ return false;
+ if (bp->b_bn != be64_to_cpu(hdr->blkno))
+ return false;
+ if (hdr->owner == 0)
+ return false;
+ }
- /* object specific verification checks here */
+ /* object specific verification checks here */
- return true;
-}
+ return true;
+ }
If there are different magic numbers for the different formats, the verifier
-will look like:
+will look like::
-static bool
-xfs_foo_verify(
- struct xfs_buf *bp)
-{
- struct xfs_mount *mp = bp->b_mount;
- struct xfs_ondisk_hdr *hdr = bp->b_addr;
+ static bool
+ xfs_foo_verify(
+ struct xfs_buf *bp)
+ {
+ struct xfs_mount *mp = bp->b_mount;
+ struct xfs_ondisk_hdr *hdr = bp->b_addr;
- if (hdr->magic == cpu_to_be32(XFS_FOO_CRC_MAGIC)) {
- if (!uuid_equal(&hdr->uuid, &mp->m_sb.sb_uuid))
- return false;
- if (bp->b_bn != be64_to_cpu(hdr->blkno))
- return false;
- if (hdr->owner == 0)
- return false;
- } else if (hdr->magic != cpu_to_be32(XFS_FOO_MAGIC))
- return false;
+ if (hdr->magic == cpu_to_be32(XFS_FOO_CRC_MAGIC)) {
+ if (!uuid_equal(&hdr->uuid, &mp->m_sb.sb_uuid))
+ return false;
+ if (bp->b_bn != be64_to_cpu(hdr->blkno))
+ return false;
+ if (hdr->owner == 0)
+ return false;
+ } else if (hdr->magic != cpu_to_be32(XFS_FOO_MAGIC))
+ return false;
- /* object specific verification checks here */
+ /* object specific verification checks here */
- return true;
-}
+ return true;
+ }
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(
- struct xfs_buf *bp)
-{
- struct xfs_mount *mp = bp->b_mount;
- struct xfs_buf_log_item *bip = bp->b_fspriv;
+ static void
+ xfs_foo_write_verify(
+ struct xfs_buf *bp)
+ {
+ struct xfs_mount *mp = bp->b_mount;
+ struct xfs_buf_log_item *bip = bp->b_fspriv;
- if (!xfs_foo_verify(bp)) {
- XFS_CORRUPTION_ERROR(__func__, XFS_ERRLEVEL_LOW, mp, bp->b_addr);
- xfs_buf_ioerror(bp, EFSCORRUPTED);
- return;
- }
+ if (!xfs_foo_verify(bp)) {
+ XFS_CORRUPTION_ERROR(__func__, XFS_ERRLEVEL_LOW, mp, bp->b_addr);
+ xfs_buf_ioerror(bp, EFSCORRUPTED);
+ return;
+ }
- if (!xfs_sb_version_hascrc(&mp->m_sb))
- return;
+ if (!xfs_sb_version_hascrc(&mp->m_sb))
+ return;
- if (bip) {
- struct xfs_ondisk_hdr *hdr = bp->b_addr;
- hdr->lsn = cpu_to_be64(bip->bli_item.li_lsn);
- }
- xfs_update_cksum(bp->b_addr, BBTOB(bp->b_length), XFS_FOO_CRC_OFF);
-}
+ if (bip) {
+ struct xfs_ondisk_hdr *hdr = bp->b_addr;
+ hdr->lsn = cpu_to_be64(bip->bli_item.li_lsn);
+ }
+ xfs_update_cksum(bp->b_addr, BBTOB(bp->b_length), XFS_FOO_CRC_OFF);
+ }
This will verify the internal structure of the metadata before we go any
further, detecting corruptions that have occurred as the metadata has been
@@ -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.
-
diff --git a/MAINTAINERS b/MAINTAINERS
index c52991586853..9f9454f12e06 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -18552,7 +18552,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
--
2.25.2
^ permalink raw reply related [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-04-15 14:34 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-04-15 14:32 [PATCH 00/34] fs: convert remaining docs to ReST file format Mauro Carvalho Chehab
2020-04-15 14:32 ` [PATCH 33/34] docs: filesystems: convert xfs-delayed-logging-design.txt to ReST Mauro Carvalho Chehab
2020-04-15 14:32 ` [PATCH 34/34] docs: filesystems: convert xfs-self-describing-metadata.txt " Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).