mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2025-01-06 05:06:29 +00:00
docs: filesystems: convert gfs2-glocks.txt to ReST
- 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> Signed-off-by: Andreas Gruenbacher <agruenba@redhat.com>
This commit is contained in:
parent
3d77e6a880
commit
3700bec332
@ -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
|
This documents the basic principles of the glock state machine
|
||||||
internals. Each glock (struct gfs2_glock in fs/gfs2/incore.h)
|
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
|
namely shared (SH), deferred (DF) and exclusive (EX). Those translate
|
||||||
to the following DLM lock modes:
|
to the following DLM lock modes:
|
||||||
|
|
||||||
Glock mode | DLM lock mode
|
========== ====== =====================================================
|
||||||
------------------------------
|
Glock mode DLM lock mode
|
||||||
UN | IV/NL Unlocked (no DLM lock associated with glock) or NL
|
========== ====== =====================================================
|
||||||
SH | PR (Protected read)
|
UN IV/NL Unlocked (no DLM lock associated with glock) or NL
|
||||||
DF | CW (Concurrent write)
|
SH PR (Protected read)
|
||||||
EX | EX (Exclusive)
|
DF CW (Concurrent write)
|
||||||
|
EX EX (Exclusive)
|
||||||
|
========== ====== =====================================================
|
||||||
|
|
||||||
Thus DF is basically a shared mode which is incompatible with the "normal"
|
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
|
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
|
operations. The glocks are basically a lock plus some routines which deal
|
||||||
with cache management. The following rules apply for the cache:
|
with cache management. The following rules apply for the cache:
|
||||||
|
|
||||||
Glock mode | Cache data | Cache Metadata | Dirty Data | Dirty Metadata
|
========== ========== ============== ========== ==============
|
||||||
--------------------------------------------------------------------------
|
Glock mode Cache data Cache Metadata Dirty Data Dirty Metadata
|
||||||
UN | No | No | No | No
|
========== ========== ============== ========== ==============
|
||||||
SH | Yes | Yes | No | No
|
UN No No No No
|
||||||
DF | No | Yes | No | No
|
SH Yes Yes No No
|
||||||
EX | Yes | Yes | Yes | Yes
|
DF No Yes No No
|
||||||
|
EX Yes Yes Yes Yes
|
||||||
|
========== ========== ============== ========== ==============
|
||||||
|
|
||||||
These rules are implemented using the various glock operations which
|
These rules are implemented using the various glock operations which
|
||||||
are defined for each type of glock. Not all types of glocks use
|
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:
|
Table of glock operations and per type constants:
|
||||||
|
|
||||||
Field | Purpose
|
============= =============================================================
|
||||||
----------------------------------------------------------------------------
|
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_xmote_th Called before remote state change (e.g. to sync dirty data)
|
||||||
go_inval | Called if remote state change requires invalidating the cache
|
go_xmote_bh Called after remote state change (e.g. to refill cache)
|
||||||
go_demote_ok | Returns boolean value of whether its ok to demote a glock
|
go_inval Called if remote state change requires invalidating the cache
|
||||||
| (e.g. checks timeout, and that there is no cached data)
|
go_demote_ok Returns boolean value of whether its ok to demote a glock
|
||||||
go_lock | Called for the first local holder of a lock
|
(e.g. checks timeout, and that there is no cached data)
|
||||||
go_unlock | Called on the final local unlock of a lock
|
go_lock Called for the first local holder of a lock
|
||||||
go_dump | Called to print content of object for debugfs file, or on
|
go_unlock Called on the final local unlock of a lock
|
||||||
| error to dump glock to the log.
|
go_dump Called to print content of object for debugfs file, or on
|
||||||
go_type | The type of the glock, LM_TYPE_.....
|
error to dump glock to the log.
|
||||||
go_callback | Called if the DLM sends a callback to drop this lock
|
go_type The type of the glock, ``LM_TYPE_*``
|
||||||
go_flags | GLOF_ASPACE is set, if the glock has an address space
|
go_callback Called if the DLM sends a callback to drop this lock
|
||||||
| associated with it
|
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
|
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
|
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:
|
Locking rules for glock operations:
|
||||||
|
|
||||||
Operation | GLF_LOCK bit lock held | gl_lockref.lock spinlock held
|
============= ====================== =============================
|
||||||
-------------------------------------------------------------------------
|
Operation GLF_LOCK bit lock held gl_lockref.lock spinlock held
|
||||||
go_xmote_th | Yes | No
|
============= ====================== =============================
|
||||||
go_xmote_bh | Yes | No
|
go_xmote_th Yes No
|
||||||
go_inval | Yes | No
|
go_xmote_bh Yes No
|
||||||
go_demote_ok | Sometimes | Yes
|
go_inval Yes No
|
||||||
go_lock | Yes | No
|
go_demote_ok Sometimes Yes
|
||||||
go_unlock | Yes | No
|
go_lock Yes No
|
||||||
go_dump | Sometimes | Yes
|
go_unlock Yes No
|
||||||
go_callback | Sometimes (N/A) | Yes
|
go_dump Sometimes Yes
|
||||||
|
go_callback Sometimes (N/A) Yes
|
||||||
|
============= ====================== =============================
|
||||||
|
|
||||||
N.B. Operations must not drop either the bit lock or the spinlock
|
.. Note::
|
||||||
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
|
Operations must not drop either the bit lock or the spinlock
|
||||||
indicates that it is caching uptodate data.
|
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:
|
Glock locking order within GFS2:
|
||||||
|
|
||||||
@ -104,7 +117,7 @@ Glock locking order within GFS2:
|
|||||||
2. Rename glock (for rename only)
|
2. Rename glock (for rename only)
|
||||||
3. Inode glock(s)
|
3. Inode glock(s)
|
||||||
(Parents before children, inodes at "same level" with same parent in
|
(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)
|
4. Rgrp glock(s) (for (de)allocation operations)
|
||||||
5. Transaction glock (via gfs2_trans_begin) for non-read operations
|
5. Transaction glock (via gfs2_trans_begin) for non-read operations
|
||||||
6. i_rw_mutex (if required)
|
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.
|
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.
|
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
|
The stats are divided into two sets: those relating to the
|
||||||
super block and those relating to an individual glock. 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"
|
1. To be able to better set the glock "min hold time"
|
||||||
2. To spot performance issues more easily
|
2. To spot performance issues more easily
|
||||||
3. To improve the algorithm for selecting resource groups for
|
3. To improve the algorithm for selecting resource groups for
|
||||||
allocation (to base it on lock wait time, rather than blindly
|
allocation (to base it on lock wait time, rather than blindly
|
||||||
using a "try lock")
|
using a "try lock")
|
||||||
|
|
||||||
Due to the smoothing action of the updates, a step change in
|
Due to the smoothing action of the updates, a step change in
|
||||||
some input quantity being sampled will only fully be taken
|
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
|
measuring system, but I hope this is as accurate as we
|
||||||
can reasonably make it.
|
can reasonably make it.
|
||||||
|
|
||||||
Per sb stats can be found here:
|
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>/sbstats
|
||||||
/sys/kernel/debug/gfs2/<fsname>/glstats
|
|
||||||
|
Per glock stats can be found here::
|
||||||
|
|
||||||
|
/sys/kernel/debug/gfs2/<fsname>/glstats
|
||||||
|
|
||||||
Assuming that debugfs is mounted on /sys/kernel/debug and also
|
Assuming that debugfs is mounted on /sys/kernel/debug and also
|
||||||
that <fsname> is replaced with the name of the gfs2 filesystem
|
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:
|
The abbreviations used in the output as are follows:
|
||||||
|
|
||||||
srtt - Smoothed round trip time for non-blocking dlm requests
|
========= ================================================================
|
||||||
srttvar - Variance estimate for srtt
|
srtt Smoothed round trip time for non blocking dlm requests
|
||||||
srttb - Smoothed round trip time for (potentially) blocking dlm requests
|
srttvar Variance estimate for srtt
|
||||||
srttvarb - Variance estimate for srttb
|
srttb Smoothed round trip time for (potentially) blocking dlm requests
|
||||||
sirt - Smoothed inter-request time (for dlm requests)
|
srttvarb Variance estimate for srttb
|
||||||
sirtvar - Variance estimate for sirt
|
sirt Smoothed inter request time (for dlm requests)
|
||||||
dlm - Number of dlm requests made (dcnt in glstats file)
|
sirtvar Variance estimate for sirt
|
||||||
queue - Number of glock requests queued (qcnt in glstats file)
|
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
|
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
|
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
|
for the glock in question, along with some addition information on each dlm
|
||||||
reply that is received:
|
reply that is received:
|
||||||
|
|
||||||
status - The status of the dlm request
|
====== =======================================
|
||||||
flags - The dlm request flags
|
status The status of the dlm request
|
||||||
tdiff - The time taken by this specific request
|
flags The dlm request flags
|
||||||
|
tdiff The time taken by this specific request
|
||||||
|
====== =======================================
|
||||||
|
|
||||||
(remaining fields as per above list)
|
(remaining fields as per above list)
|
||||||
|
|
||||||
|
|
@ -69,6 +69,7 @@ Documentation for filesystem implementations.
|
|||||||
f2fs
|
f2fs
|
||||||
gfs2
|
gfs2
|
||||||
gfs2-uevents
|
gfs2-uevents
|
||||||
|
gfs2-glocks
|
||||||
hfs
|
hfs
|
||||||
hfsplus
|
hfsplus
|
||||||
hpfs
|
hpfs
|
||||||
|
@ -7179,7 +7179,7 @@ L: cluster-devel@redhat.com
|
|||||||
S: Supported
|
S: Supported
|
||||||
W: http://sources.redhat.com/cluster/
|
W: http://sources.redhat.com/cluster/
|
||||||
T: git git://git.kernel.org/pub/scm/linux/kernel/git/gfs2/linux-gfs2.git
|
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: fs/gfs2/
|
||||||
F: include/uapi/linux/gfs2_ondisk.h
|
F: include/uapi/linux/gfs2_ondisk.h
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user