* [Cluster-devel] [PATCH 00/34] fs: convert remaining docs to ReST file format
@ 2020-04-15 14:32 Mauro Carvalho Chehab
2020-04-15 14:32 ` [Cluster-devel] [PATCH 18/34] docs: filesystems: convert gfs2-glocks.txt to ReST Mauro Carvalho Chehab
0 siblings, 1 reply; 3+ messages in thread
From: Mauro Carvalho Chehab @ 2020-04-15 14:32 UTC (permalink / raw)
To: cluster-devel.redhat.com
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
* [Cluster-devel] [PATCH 18/34] docs: filesystems: convert gfs2-glocks.txt to ReST
2020-04-15 14:32 [Cluster-devel] [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:52 ` Andreas Gruenbacher
0 siblings, 1 reply; 3+ messages in thread
From: Mauro Carvalho Chehab @ 2020-04-15 14:32 UTC (permalink / raw)
To: cluster-devel.redhat.com
- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Add table markups;
- Use notes markups;
- Add it to filesystems/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../{gfs2-glocks.txt => gfs2-glocks.rst} | 147 ++++++++++--------
Documentation/filesystems/index.rst | 1 +
MAINTAINERS | 2 +-
3 files changed, 86 insertions(+), 64 deletions(-)
rename Documentation/filesystems/{gfs2-glocks.txt => gfs2-glocks.rst} (63%)
diff --git a/Documentation/filesystems/gfs2-glocks.txt b/Documentation/filesystems/gfs2-glocks.rst
similarity index 63%
rename from Documentation/filesystems/gfs2-glocks.txt
rename to Documentation/filesystems/gfs2-glocks.rst
index 7059623635b2..d14f230f0b12 100644
--- a/Documentation/filesystems/gfs2-glocks.txt
+++ b/Documentation/filesystems/gfs2-glocks.rst
@@ -1,5 +1,8 @@
- Glock internal locking rules
- ------------------------------
+.. SPDX-License-Identifier: GPL-2.0
+
+============================
+Glock internal locking rules
+============================
This documents the basic principles of the glock state machine
internals. Each glock (struct gfs2_glock in fs/gfs2/incore.h)
@@ -24,24 +27,28 @@ There are three lock states that users of the glock layer can request,
namely shared (SH), deferred (DF) and exclusive (EX). Those translate
to the following DLM lock modes:
-Glock mode | DLM lock mode
-------------------------------
- UN | IV/NL Unlocked (no DLM lock associated with glock) or NL
- SH | PR (Protected read)
- DF | CW (Concurrent write)
- EX | EX (Exclusive)
+========== ====== =====================================================
+Glock mode DLM lock mode
+========== ====== =====================================================
+ UN IV/NL Unlocked (no DLM lock associated with glock) or NL
+ SH PR (Protected read)
+ DF CW (Concurrent write)
+ EX EX (Exclusive)
+========== ====== =====================================================
Thus DF is basically a shared mode which is incompatible with the "normal"
shared lock mode, SH. In GFS2 the DF mode is used exclusively for direct I/O
operations. The glocks are basically a lock plus some routines which deal
with cache management. The following rules apply for the cache:
-Glock mode | Cache data | Cache Metadata | Dirty Data | Dirty Metadata
---------------------------------------------------------------------------
- UN | No | No | No | No
- SH | Yes | Yes | No | No
- DF | No | Yes | No | No
- EX | Yes | Yes | Yes | Yes
+========== ========== ============== ========== ==============
+Glock mode Cache data Cache Metadata Dirty Data Dirty Metadata
+========== ========== ============== ========== ==============
+ UN No No No No
+ SH Yes Yes No No
+ DF No Yes No No
+ EX Yes Yes Yes Yes
+========== ========== ============== ========== ==============
These rules are implemented using the various glock operations which
are defined for each type of glock. Not all types of glocks use
@@ -49,21 +56,23 @@ all the modes. Only inode glocks use the DF mode for example.
Table of glock operations and per type constants:
-Field | Purpose
-----------------------------------------------------------------------------
-go_xmote_th | Called before remote state change (e.g. to sync dirty data)
-go_xmote_bh | Called after remote state change (e.g. to refill cache)
-go_inval | Called if remote state change requires invalidating the cache
-go_demote_ok | Returns boolean value of whether its ok to demote a glock
- | (e.g. checks timeout, and that there is no cached data)
-go_lock | Called for the first local holder of a lock
-go_unlock | Called on the final local unlock of a lock
-go_dump | Called to print content of object for debugfs file, or on
- | error to dump glock to the log.
-go_type | The type of the glock, LM_TYPE_.....
-go_callback | Called if the DLM sends a callback to drop this lock
-go_flags | GLOF_ASPACE is set, if the glock has an address space
- | associated with it
+============= =============================================================
+Field Purpose
+============= =============================================================
+go_xmote_th Called before remote state change (e.g. to sync dirty data)
+go_xmote_bh Called after remote state change (e.g. to refill cache)
+go_inval Called if remote state change requires invalidating the cache
+go_demote_ok Returns boolean value of whether its ok to demote a glock
+ (e.g. checks timeout, and that there is no cached data)
+go_lock Called for the first local holder of a lock
+go_unlock Called on the final local unlock of a lock
+go_dump Called to print content of object for debugfs file, or on
+ error to dump glock to the log.
+go_type The type of the glock, ``LM_TYPE_*``
+go_callback Called if the DLM sends a callback to drop this lock
+go_flags GLOF_ASPACE is set, if the glock has an address space
+ associated with it
+============= =============================================================
The minimum hold time for each lock is the time after a remote lock
grant for which we ignore remote demote requests. This is in order to
@@ -82,21 +91,25 @@ rather than via the glock.
Locking rules for glock operations:
-Operation | GLF_LOCK bit lock held | gl_lockref.lock spinlock held
--------------------------------------------------------------------------
-go_xmote_th | Yes | No
-go_xmote_bh | Yes | No
-go_inval | Yes | No
-go_demote_ok | Sometimes | Yes
-go_lock | Yes | No
-go_unlock | Yes | No
-go_dump | Sometimes | Yes
-go_callback | Sometimes (N/A) | Yes
+============= ====================== =============================
+Operation GLF_LOCK bit lock held gl_lockref.lock spinlock held
+============= ====================== =============================
+go_xmote_th Yes No
+go_xmote_bh Yes No
+go_inval Yes No
+go_demote_ok Sometimes Yes
+go_lock Yes No
+go_unlock Yes No
+go_dump Sometimes Yes
+go_callback Sometimes (N/A) Yes
+============= ====================== =============================
-N.B. Operations must not drop either the bit lock or the spinlock
-if its held on entry. go_dump and do_demote_ok must never block.
-Note that go_dump will only be called if the glock's state
-indicates that it is caching uptodate data.
+.. Note::
+
+ Operations must not drop either the bit lock or the spinlock
+ if its held on entry. go_dump and do_demote_ok must never block.
+ Note that go_dump will only be called if the glock's state
+ indicates that it is caching uptodate data.
Glock locking order within GFS2:
@@ -104,7 +117,7 @@ Glock locking order within GFS2:
2. Rename glock (for rename only)
3. Inode glock(s)
(Parents before children, inodes at "same level" with same parent in
- lock number order)
+ lock number order)
4. Rgrp glock(s) (for (de)allocation operations)
5. Transaction glock (via gfs2_trans_begin) for non-read operations
6. i_rw_mutex (if required)
@@ -117,8 +130,8 @@ determine the lifetime of the inode in question. Locking of inodes
is on a per-inode basis. Locking of rgrps is on a per rgrp basis.
In general we prefer to lock local locks prior to cluster locks.
- Glock Statistics
- ------------------
+Glock Statistics
+----------------
The stats are divided into two sets: those relating to the
super block and those relating to an individual glock. The
@@ -173,8 +186,8 @@ we'd like to get a better idea of these timings:
1. To be able to better set the glock "min hold time"
2. To spot performance issues more easily
3. To improve the algorithm for selecting resource groups for
-allocation (to base it on lock wait time, rather than blindly
-using a "try lock")
+ allocation (to base it on lock wait time, rather than blindly
+ using a "try lock")
Due to the smoothing action of the updates, a step change in
some input quantity being sampled will only fully be taken
@@ -195,10 +208,13 @@ as possible. There are always inaccuracies in any
measuring system, but I hope this is as accurate as we
can reasonably make it.
-Per sb stats can be found here:
-/sys/kernel/debug/gfs2/<fsname>/sbstats
-Per glock stats can be found here:
-/sys/kernel/debug/gfs2/<fsname>/glstats
+Per sb stats can be found here::
+
+ /sys/kernel/debug/gfs2/<fsname>/sbstats
+
+Per glock stats can be found here::
+
+ /sys/kernel/debug/gfs2/<fsname>/glstats
Assuming that debugfs is mounted on /sys/kernel/debug and also
that <fsname> is replaced with the name of the gfs2 filesystem
@@ -206,14 +222,16 @@ in question.
The abbreviations used in the output as are follows:
-srtt - Smoothed round trip time for non-blocking dlm requests
-srttvar - Variance estimate for srtt
-srttb - Smoothed round trip time for (potentially) blocking dlm requests
-srttvarb - Variance estimate for srttb
-sirt - Smoothed inter-request time (for dlm requests)
-sirtvar - Variance estimate for sirt
-dlm - Number of dlm requests made (dcnt in glstats file)
-queue - Number of glock requests queued (qcnt in glstats file)
+========= ================================================================
+srtt Smoothed round trip time for non blocking dlm requests
+srttvar Variance estimate for srtt
+srttb Smoothed round trip time for (potentially) blocking dlm requests
+srttvarb Variance estimate for srttb
+sirt Smoothed inter request time (for dlm requests)
+sirtvar Variance estimate for sirt
+dlm Number of dlm requests made (dcnt in glstats file)
+queue Number of glock requests queued (qcnt in glstats file)
+========= ================================================================
The sbstats file contains a set of these stats for each glock type (so 8 lines
for each type) and for each cpu (one column per cpu). The glstats file contains
@@ -224,9 +242,12 @@ The gfs2_glock_lock_time tracepoint prints out the current values of the stats
for the glock in question, along with some addition information on each dlm
reply that is received:
-status - The status of the dlm request
-flags - The dlm request flags
-tdiff - The time taken by this specific request
+====== =======================================
+status The status of the dlm request
+flags The dlm request flags
+tdiff The time taken by this specific request
+====== =======================================
+
(remaining fields as per above list)
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 300e12569f54..6a34d1b578a9 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -81,6 +81,7 @@ Documentation for filesystem implementations.
f2fs
gfs2
gfs2-uevents
+ gfs2-glocks
hfs
hfsplus
hpfs
diff --git a/MAINTAINERS b/MAINTAINERS
index eebb55517709..470389ef0135 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7181,7 +7181,7 @@ L: cluster-devel at redhat.com
S: Supported
W: http://sources.redhat.com/cluster/
T: git git://git.kernel.org/pub/scm/linux/kernel/git/gfs2/linux-gfs2.git
-F: Documentation/filesystems/gfs2*.txt
+F: Documentation/filesystems/gfs2*
F: fs/gfs2/
F: include/uapi/linux/gfs2_ondisk.h
--
2.25.2
^ permalink raw reply related [flat|nested] 3+ messages in thread
* [Cluster-devel] [PATCH 18/34] docs: filesystems: convert gfs2-glocks.txt to ReST
2020-04-15 14:32 ` [Cluster-devel] [PATCH 18/34] docs: filesystems: convert gfs2-glocks.txt to ReST Mauro Carvalho Chehab
@ 2020-04-15 14:52 ` Andreas Gruenbacher
0 siblings, 0 replies; 3+ messages in thread
From: Andreas Gruenbacher @ 2020-04-15 14:52 UTC (permalink / raw)
To: cluster-devel.redhat.com
Hi Mauro,
I've pushed this to for-next.
Thanks,
Andreas
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-04-15 14:52 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 [Cluster-devel] [PATCH 00/34] fs: convert remaining docs to ReST file format Mauro Carvalho Chehab
2020-04-15 14:32 ` [Cluster-devel] [PATCH 18/34] docs: filesystems: convert gfs2-glocks.txt to ReST Mauro Carvalho Chehab
2020-04-15 14:52 ` Andreas Gruenbacher
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).