Commit | Line | Data |
---|---|---|
3700bec3 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ============================ | |
4 | Glock internal locking rules | |
5 | ============================ | |
9f1585cb SW |
6 | |
7 | This documents the basic principles of the glock state machine | |
8 | internals. Each glock (struct gfs2_glock in fs/gfs2/incore.h) | |
9 | has two main (internal) locks: | |
10 | ||
f3dd1649 | 11 | 1. A spinlock (gl_lockref.lock) which protects the internal state such |
9f1585cb SW |
12 | as gl_state, gl_target and the list of holders (gl_holders) |
13 | 2. A non-blocking bit lock, GLF_LOCK, which is used to prevent other | |
14 | threads from making calls to the DLM, etc. at the same time. If a | |
15 | thread takes this lock, it must then call run_queue (usually via the | |
16 | workqueue) when it releases it in order to ensure any pending tasks | |
17 | are completed. | |
18 | ||
19 | The gl_holders list contains all the queued lock requests (not | |
20 | just the holders) associated with the glock. If there are any | |
21 | held locks, then they will be contiguous entries at the head | |
22 | of the list. Locks are granted in strictly the order that they | |
23 | are queued, except for those marked LM_FLAG_PRIORITY which are | |
24 | used only during recovery, and even then only for journal locks. | |
25 | ||
26 | There are three lock states that users of the glock layer can request, | |
27 | namely shared (SH), deferred (DF) and exclusive (EX). Those translate | |
28 | to the following DLM lock modes: | |
29 | ||
3700bec3 MCC |
30 | ========== ====== ===================================================== |
31 | Glock mode DLM lock mode | |
32 | ========== ====== ===================================================== | |
33 | UN IV/NL Unlocked (no DLM lock associated with glock) or NL | |
34 | SH PR (Protected read) | |
35 | DF CW (Concurrent write) | |
36 | EX EX (Exclusive) | |
37 | ========== ====== ===================================================== | |
9f1585cb SW |
38 | |
39 | Thus DF is basically a shared mode which is incompatible with the "normal" | |
40 | shared lock mode, SH. In GFS2 the DF mode is used exclusively for direct I/O | |
41 | operations. The glocks are basically a lock plus some routines which deal | |
42 | with cache management. The following rules apply for the cache: | |
43 | ||
3700bec3 MCC |
44 | ========== ========== ============== ========== ============== |
45 | Glock mode Cache data Cache Metadata Dirty Data Dirty Metadata | |
46 | ========== ========== ============== ========== ============== | |
47 | UN No No No No | |
48 | SH Yes Yes No No | |
49 | DF No Yes No No | |
50 | EX Yes Yes Yes Yes | |
51 | ========== ========== ============== ========== ============== | |
9f1585cb SW |
52 | |
53 | These rules are implemented using the various glock operations which | |
54 | are defined for each type of glock. Not all types of glocks use | |
55 | all the modes. Only inode glocks use the DF mode for example. | |
56 | ||
57 | Table of glock operations and per type constants: | |
58 | ||
3700bec3 MCC |
59 | ============= ============================================================= |
60 | Field Purpose | |
61 | ============= ============================================================= | |
62 | go_xmote_th Called before remote state change (e.g. to sync dirty data) | |
63 | go_xmote_bh Called after remote state change (e.g. to refill cache) | |
64 | go_inval Called if remote state change requires invalidating the cache | |
65 | go_demote_ok Returns boolean value of whether its ok to demote a glock | |
66 | (e.g. checks timeout, and that there is no cached data) | |
67 | go_lock Called for the first local holder of a lock | |
68 | go_unlock Called on the final local unlock of a lock | |
69 | go_dump Called to print content of object for debugfs file, or on | |
70 | error to dump glock to the log. | |
71 | go_type The type of the glock, ``LM_TYPE_*`` | |
72 | go_callback Called if the DLM sends a callback to drop this lock | |
73 | go_flags GLOF_ASPACE is set, if the glock has an address space | |
74 | associated with it | |
75 | ============= ============================================================= | |
9f1585cb SW |
76 | |
77 | The minimum hold time for each lock is the time after a remote lock | |
78 | grant for which we ignore remote demote requests. This is in order to | |
79 | prevent a situation where locks are being bounced around the cluster | |
80 | from node to node with none of the nodes making any progress. This | |
81 | tends to show up most with shared mmaped files which are being written | |
82 | to by multiple nodes. By delaying the demotion in response to a | |
83 | remote callback, that gives the userspace program time to make | |
84 | some progress before the pages are unmapped. | |
85 | ||
86 | There is a plan to try and remove the go_lock and go_unlock callbacks | |
87 | if possible, in order to try and speed up the fast path though the locking. | |
88 | Also, eventually we hope to make the glock "EX" mode locally shared | |
89 | such that any local locking will be done with the i_mutex as required | |
90 | rather than via the glock. | |
91 | ||
92 | Locking rules for glock operations: | |
93 | ||
3700bec3 MCC |
94 | ============= ====================== ============================= |
95 | Operation GLF_LOCK bit lock held gl_lockref.lock spinlock held | |
96 | ============= ====================== ============================= | |
97 | go_xmote_th Yes No | |
98 | go_xmote_bh Yes No | |
99 | go_inval Yes No | |
100 | go_demote_ok Sometimes Yes | |
101 | go_lock Yes No | |
102 | go_unlock Yes No | |
103 | go_dump Sometimes Yes | |
104 | go_callback Sometimes (N/A) Yes | |
105 | ============= ====================== ============================= | |
106 | ||
107 | .. Note:: | |
108 | ||
109 | Operations must not drop either the bit lock or the spinlock | |
110 | if its held on entry. go_dump and do_demote_ok must never block. | |
111 | Note that go_dump will only be called if the glock's state | |
112 | indicates that it is caching uptodate data. | |
9f1585cb SW |
113 | |
114 | Glock locking order within GFS2: | |
115 | ||
3e7aafc3 | 116 | 1. i_rwsem (if required) |
9f1585cb SW |
117 | 2. Rename glock (for rename only) |
118 | 3. Inode glock(s) | |
119 | (Parents before children, inodes at "same level" with same parent in | |
3700bec3 | 120 | lock number order) |
9f1585cb SW |
121 | 4. Rgrp glock(s) (for (de)allocation operations) |
122 | 5. Transaction glock (via gfs2_trans_begin) for non-read operations | |
3e7aafc3 BP |
123 | 6. i_rw_mutex (if required) |
124 | 7. Page lock (always last, very important!) | |
9f1585cb SW |
125 | |
126 | There are two glocks per inode. One deals with access to the inode | |
127 | itself (locking order as above), and the other, known as the iopen | |
128 | glock is used in conjunction with the i_nlink field in the inode to | |
129 | determine the lifetime of the inode in question. Locking of inodes | |
130 | is on a per-inode basis. Locking of rgrps is on a per rgrp basis. | |
2ebc3f8b SW |
131 | In general we prefer to lock local locks prior to cluster locks. |
132 | ||
3700bec3 MCC |
133 | Glock Statistics |
134 | ---------------- | |
2ebc3f8b SW |
135 | |
136 | The stats are divided into two sets: those relating to the | |
137 | super block and those relating to an individual glock. The | |
138 | super block stats are done on a per cpu basis in order to | |
139 | try and reduce the overhead of gathering them. They are also | |
140 | further divided by glock type. All timings are in nanoseconds. | |
141 | ||
142 | In the case of both the super block and glock statistics, | |
143 | the same information is gathered in each case. The super | |
144 | block timing statistics are used to provide default values for | |
145 | the glock timing statistics, so that newly created glocks | |
146 | should have, as far as possible, a sensible starting point. | |
147 | The per-glock counters are initialised to zero when the | |
148 | glock is created. The per-glock statistics are lost when | |
149 | the glock is ejected from memory. | |
150 | ||
151 | The statistics are divided into three pairs of mean and | |
152 | variance, plus two counters. The mean/variance pairs are | |
153 | smoothed exponential estimates and the algorithm used is | |
154 | one which will be very familiar to those used to calculation | |
155 | of round trip times in network code. See "TCP/IP Illustrated, | |
156 | Volume 1", W. Richard Stevens, sect 21.3, "Round-Trip Time Measurement", | |
157 | p. 299 and onwards. Also, Volume 2, Sect. 25.10, p. 838 and onwards. | |
158 | Unlike the TCP/IP Illustrated case, the mean and variance are | |
159 | not scaled, but are in units of integer nanoseconds. | |
160 | ||
161 | The three pairs of mean/variance measure the following | |
162 | things: | |
163 | ||
164 | 1. DLM lock time (non-blocking requests) | |
165 | 2. DLM lock time (blocking requests) | |
166 | 3. Inter-request time (again to the DLM) | |
167 | ||
168 | A non-blocking request is one which will complete right | |
169 | away, whatever the state of the DLM lock in question. That | |
170 | currently means any requests when (a) the current state of | |
171 | the lock is exclusive, i.e. a lock demotion (b) the requested | |
172 | state is either null or unlocked (again, a demotion) or (c) the | |
173 | "try lock" flag is set. A blocking request covers all the other | |
174 | lock requests. | |
175 | ||
176 | There are two counters. The first is there primarily to show | |
177 | how many lock requests have been made, and thus how much data | |
178 | has gone into the mean/variance calculations. The other counter | |
179 | is counting queuing of holders at the top layer of the glock | |
180 | code. Hopefully that number will be a lot larger than the number | |
181 | of dlm lock requests issued. | |
182 | ||
183 | So why gather these statistics? There are several reasons | |
184 | we'd like to get a better idea of these timings: | |
185 | ||
186 | 1. To be able to better set the glock "min hold time" | |
187 | 2. To spot performance issues more easily | |
188 | 3. To improve the algorithm for selecting resource groups for | |
3700bec3 MCC |
189 | allocation (to base it on lock wait time, rather than blindly |
190 | using a "try lock") | |
2ebc3f8b SW |
191 | |
192 | Due to the smoothing action of the updates, a step change in | |
193 | some input quantity being sampled will only fully be taken | |
194 | into account after 8 samples (or 4 for the variance) and this | |
195 | needs to be carefully considered when interpreting the | |
196 | results. | |
197 | ||
198 | Knowing both the time it takes a lock request to complete and | |
199 | the average time between lock requests for a glock means we | |
200 | can compute the total percentage of the time for which the | |
201 | node is able to use a glock vs. time that the rest of the | |
202 | cluster has its share. That will be very useful when setting | |
203 | the lock min hold time. | |
204 | ||
205 | Great care has been taken to ensure that we | |
206 | measure exactly the quantities that we want, as accurately | |
207 | as possible. There are always inaccuracies in any | |
208 | measuring system, but I hope this is as accurate as we | |
209 | can reasonably make it. | |
210 | ||
3700bec3 MCC |
211 | Per sb stats can be found here:: |
212 | ||
213 | /sys/kernel/debug/gfs2/<fsname>/sbstats | |
214 | ||
215 | Per glock stats can be found here:: | |
216 | ||
217 | /sys/kernel/debug/gfs2/<fsname>/glstats | |
2ebc3f8b SW |
218 | |
219 | Assuming that debugfs is mounted on /sys/kernel/debug and also | |
220 | that <fsname> is replaced with the name of the gfs2 filesystem | |
221 | in question. | |
222 | ||
223 | The abbreviations used in the output as are follows: | |
224 | ||
3700bec3 MCC |
225 | ========= ================================================================ |
226 | srtt Smoothed round trip time for non blocking dlm requests | |
227 | srttvar Variance estimate for srtt | |
228 | srttb Smoothed round trip time for (potentially) blocking dlm requests | |
229 | srttvarb Variance estimate for srttb | |
230 | sirt Smoothed inter request time (for dlm requests) | |
231 | sirtvar Variance estimate for sirt | |
232 | dlm Number of dlm requests made (dcnt in glstats file) | |
233 | queue Number of glock requests queued (qcnt in glstats file) | |
234 | ========= ================================================================ | |
2ebc3f8b SW |
235 | |
236 | The sbstats file contains a set of these stats for each glock type (so 8 lines | |
237 | for each type) and for each cpu (one column per cpu). The glstats file contains | |
238 | a set of these stats for each glock in a similar format to the glocks file, but | |
239 | using the format mean/variance for each of the timing stats. | |
240 | ||
241 | The gfs2_glock_lock_time tracepoint prints out the current values of the stats | |
242 | for the glock in question, along with some addition information on each dlm | |
243 | reply that is received: | |
244 | ||
3700bec3 MCC |
245 | ====== ======================================= |
246 | status The status of the dlm request | |
247 | flags The dlm request flags | |
248 | tdiff The time taken by this specific request | |
249 | ====== ======================================= | |
250 | ||
2ebc3f8b SW |
251 | (remaining fields as per above list) |
252 | ||
9f1585cb | 253 |