GNU Linux-libre 4.19.264-gnu1
[releases.git] / Documentation / vm / slub.rst
1 .. _slub:
2
3 ==========================
4 Short users guide for SLUB
5 ==========================
6
7 The basic philosophy of SLUB is very different from SLAB. SLAB
8 requires rebuilding the kernel to activate debug options for all
9 slab caches. SLUB always includes full debugging but it is off by default.
10 SLUB can enable debugging only for selected slabs in order to avoid
11 an impact on overall system performance which may make a bug more
12 difficult to find.
13
14 In order to switch debugging on one can add an option ``slub_debug``
15 to the kernel command line. That will enable full debugging for
16 all slabs.
17
18 Typically one would then use the ``slabinfo`` command to get statistical
19 data and perform operation on the slabs. By default ``slabinfo`` only lists
20 slabs that have data in them. See "slabinfo -h" for more options when
21 running the command. ``slabinfo`` can be compiled with
22 ::
23
24         gcc -o slabinfo tools/vm/slabinfo.c
25
26 Some of the modes of operation of ``slabinfo`` require that slub debugging
27 be enabled on the command line. F.e. no tracking information will be
28 available without debugging on and validation can only partially
29 be performed if debugging was not switched on.
30
31 Some more sophisticated uses of slub_debug:
32 -------------------------------------------
33
34 Parameters may be given to ``slub_debug``. If none is specified then full
35 debugging is enabled. Format:
36
37 slub_debug=<Debug-Options>
38         Enable options for all slabs
39 slub_debug=<Debug-Options>,<slab name>
40         Enable options only for select slabs
41
42
43 Possible debug options are::
44
45         F               Sanity checks on (enables SLAB_DEBUG_CONSISTENCY_CHECKS
46                         Sorry SLAB legacy issues)
47         Z               Red zoning
48         P               Poisoning (object and padding)
49         U               User tracking (free and alloc)
50         T               Trace (please only use on single slabs)
51         A               Toggle failslab filter mark for the cache
52         O               Switch debugging off for caches that would have
53                         caused higher minimum slab orders
54         -               Switch all debugging off (useful if the kernel is
55                         configured with CONFIG_SLUB_DEBUG_ON)
56
57 F.e. in order to boot just with sanity checks and red zoning one would specify::
58
59         slub_debug=FZ
60
61 Trying to find an issue in the dentry cache? Try::
62
63         slub_debug=,dentry
64
65 to only enable debugging on the dentry cache.
66
67 Red zoning and tracking may realign the slab.  We can just apply sanity checks
68 to the dentry cache with::
69
70         slub_debug=F,dentry
71
72 Debugging options may require the minimum possible slab order to increase as
73 a result of storing the metadata (for example, caches with PAGE_SIZE object
74 sizes).  This has a higher liklihood of resulting in slab allocation errors
75 in low memory situations or if there's high fragmentation of memory.  To
76 switch off debugging for such caches by default, use::
77
78         slub_debug=O
79
80 In case you forgot to enable debugging on the kernel command line: It is
81 possible to enable debugging manually when the kernel is up. Look at the
82 contents of::
83
84         /sys/kernel/slab/<slab name>/
85
86 Look at the writable files. Writing 1 to them will enable the
87 corresponding debug option. All options can be set on a slab that does
88 not contain objects. If the slab already contains objects then sanity checks
89 and tracing may only be enabled. The other options may cause the realignment
90 of objects.
91
92 Careful with tracing: It may spew out lots of information and never stop if
93 used on the wrong slab.
94
95 Slab merging
96 ============
97
98 If no debug options are specified then SLUB may merge similar slabs together
99 in order to reduce overhead and increase cache hotness of objects.
100 ``slabinfo -a`` displays which slabs were merged together.
101
102 Slab validation
103 ===============
104
105 SLUB can validate all object if the kernel was booted with slub_debug. In
106 order to do so you must have the ``slabinfo`` tool. Then you can do
107 ::
108
109         slabinfo -v
110
111 which will test all objects. Output will be generated to the syslog.
112
113 This also works in a more limited way if boot was without slab debug.
114 In that case ``slabinfo -v`` simply tests all reachable objects. Usually
115 these are in the cpu slabs and the partial slabs. Full slabs are not
116 tracked by SLUB in a non debug situation.
117
118 Getting more performance
119 ========================
120
121 To some degree SLUB's performance is limited by the need to take the
122 list_lock once in a while to deal with partial slabs. That overhead is
123 governed by the order of the allocation for each slab. The allocations
124 can be influenced by kernel parameters:
125
126 .. slub_min_objects=x           (default 4)
127 .. slub_min_order=x             (default 0)
128 .. slub_max_order=x             (default 3 (PAGE_ALLOC_COSTLY_ORDER))
129
130 ``slub_min_objects``
131         allows to specify how many objects must at least fit into one
132         slab in order for the allocation order to be acceptable.  In
133         general slub will be able to perform this number of
134         allocations on a slab without consulting centralized resources
135         (list_lock) where contention may occur.
136
137 ``slub_min_order``
138         specifies a minim order of slabs. A similar effect like
139         ``slub_min_objects``.
140
141 ``slub_max_order``
142         specified the order at which ``slub_min_objects`` should no
143         longer be checked. This is useful to avoid SLUB trying to
144         generate super large order pages to fit ``slub_min_objects``
145         of a slab cache with large object sizes into one high order
146         page. Setting command line parameter
147         ``debug_guardpage_minorder=N`` (N > 0), forces setting
148         ``slub_max_order`` to 0, what cause minimum possible order of
149         slabs allocation.
150
151 SLUB Debug output
152 =================
153
154 Here is a sample of slub debug output::
155
156  ====================================================================
157  BUG kmalloc-8: Right Redzone overwritten
158  --------------------------------------------------------------------
159
160  INFO: 0xc90f6d28-0xc90f6d2b. First byte 0x00 instead of 0xcc
161  INFO: Slab 0xc528c530 flags=0x400000c3 inuse=61 fp=0xc90f6d58
162  INFO: Object 0xc90f6d20 @offset=3360 fp=0xc90f6d58
163  INFO: Allocated in get_modalias+0x61/0xf5 age=53 cpu=1 pid=554
164
165  Bytes b4 (0xc90f6d10): 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ
166  Object   (0xc90f6d20): 31 30 31 39 2e 30 30 35                         1019.005
167  Redzone  (0xc90f6d28): 00 cc cc cc                                     .
168  Padding  (0xc90f6d50): 5a 5a 5a 5a 5a 5a 5a 5a                         ZZZZZZZZ
169
170    [<c010523d>] dump_trace+0x63/0x1eb
171    [<c01053df>] show_trace_log_lvl+0x1a/0x2f
172    [<c010601d>] show_trace+0x12/0x14
173    [<c0106035>] dump_stack+0x16/0x18
174    [<c017e0fa>] object_err+0x143/0x14b
175    [<c017e2cc>] check_object+0x66/0x234
176    [<c017eb43>] __slab_free+0x239/0x384
177    [<c017f446>] kfree+0xa6/0xc6
178    [<c02e2335>] get_modalias+0xb9/0xf5
179    [<c02e23b7>] dmi_dev_uevent+0x27/0x3c
180    [<c027866a>] dev_uevent+0x1ad/0x1da
181    [<c0205024>] kobject_uevent_env+0x20a/0x45b
182    [<c020527f>] kobject_uevent+0xa/0xf
183    [<c02779f1>] store_uevent+0x4f/0x58
184    [<c027758e>] dev_attr_store+0x29/0x2f
185    [<c01bec4f>] sysfs_write_file+0x16e/0x19c
186    [<c0183ba7>] vfs_write+0xd1/0x15a
187    [<c01841d7>] sys_write+0x3d/0x72
188    [<c0104112>] sysenter_past_esp+0x5f/0x99
189    [<b7f7b410>] 0xb7f7b410
190    =======================
191
192  FIX kmalloc-8: Restoring Redzone 0xc90f6d28-0xc90f6d2b=0xcc
193
194 If SLUB encounters a corrupted object (full detection requires the kernel
195 to be booted with slub_debug) then the following output will be dumped
196 into the syslog:
197
198 1. Description of the problem encountered
199
200    This will be a message in the system log starting with::
201
202      ===============================================
203      BUG <slab cache affected>: <What went wrong>
204      -----------------------------------------------
205
206      INFO: <corruption start>-<corruption_end> <more info>
207      INFO: Slab <address> <slab information>
208      INFO: Object <address> <object information>
209      INFO: Allocated in <kernel function> age=<jiffies since alloc> cpu=<allocated by
210         cpu> pid=<pid of the process>
211      INFO: Freed in <kernel function> age=<jiffies since free> cpu=<freed by cpu>
212         pid=<pid of the process>
213
214    (Object allocation / free information is only available if SLAB_STORE_USER is
215    set for the slab. slub_debug sets that option)
216
217 2. The object contents if an object was involved.
218
219    Various types of lines can follow the BUG SLUB line:
220
221    Bytes b4 <address> : <bytes>
222         Shows a few bytes before the object where the problem was detected.
223         Can be useful if the corruption does not stop with the start of the
224         object.
225
226    Object <address> : <bytes>
227         The bytes of the object. If the object is inactive then the bytes
228         typically contain poison values. Any non-poison value shows a
229         corruption by a write after free.
230
231    Redzone <address> : <bytes>
232         The Redzone following the object. The Redzone is used to detect
233         writes after the object. All bytes should always have the same
234         value. If there is any deviation then it is due to a write after
235         the object boundary.
236
237         (Redzone information is only available if SLAB_RED_ZONE is set.
238         slub_debug sets that option)
239
240    Padding <address> : <bytes>
241         Unused data to fill up the space in order to get the next object
242         properly aligned. In the debug case we make sure that there are
243         at least 4 bytes of padding. This allows the detection of writes
244         before the object.
245
246 3. A stackdump
247
248    The stackdump describes the location where the error was detected. The cause
249    of the corruption is may be more likely found by looking at the function that
250    allocated or freed the object.
251
252 4. Report on how the problem was dealt with in order to ensure the continued
253    operation of the system.
254
255    These are messages in the system log beginning with::
256
257         FIX <slab cache affected>: <corrective action taken>
258
259    In the above sample SLUB found that the Redzone of an active object has
260    been overwritten. Here a string of 8 characters was written into a slab that
261    has the length of 8 characters. However, a 8 character string needs a
262    terminating 0. That zero has overwritten the first byte of the Redzone field.
263    After reporting the details of the issue encountered the FIX SLUB message
264    tells us that SLUB has restored the Redzone to its proper value and then
265    system operations continue.
266
267 Emergency operations
268 ====================
269
270 Minimal debugging (sanity checks alone) can be enabled by booting with::
271
272         slub_debug=F
273
274 This will be generally be enough to enable the resiliency features of slub
275 which will keep the system running even if a bad kernel component will
276 keep corrupting objects. This may be important for production systems.
277 Performance will be impacted by the sanity checks and there will be a
278 continual stream of error messages to the syslog but no additional memory
279 will be used (unlike full debugging).
280
281 No guarantees. The kernel component still needs to be fixed. Performance
282 may be optimized further by locating the slab that experiences corruption
283 and enabling debugging only for that cache
284
285 I.e.::
286
287         slub_debug=F,dentry
288
289 If the corruption occurs by writing after the end of the object then it
290 may be advisable to enable a Redzone to avoid corrupting the beginning
291 of other objects::
292
293         slub_debug=FZ,dentry
294
295 Extended slabinfo mode and plotting
296 ===================================
297
298 The ``slabinfo`` tool has a special 'extended' ('-X') mode that includes:
299  - Slabcache Totals
300  - Slabs sorted by size (up to -N <num> slabs, default 1)
301  - Slabs sorted by loss (up to -N <num> slabs, default 1)
302
303 Additionally, in this mode ``slabinfo`` does not dynamically scale
304 sizes (G/M/K) and reports everything in bytes (this functionality is
305 also available to other slabinfo modes via '-B' option) which makes
306 reporting more precise and accurate. Moreover, in some sense the `-X'
307 mode also simplifies the analysis of slabs' behaviour, because its
308 output can be plotted using the ``slabinfo-gnuplot.sh`` script. So it
309 pushes the analysis from looking through the numbers (tons of numbers)
310 to something easier -- visual analysis.
311
312 To generate plots:
313
314 a) collect slabinfo extended records, for example::
315
316         while [ 1 ]; do slabinfo -X >> FOO_STATS; sleep 1; done
317
318 b) pass stats file(-s) to ``slabinfo-gnuplot.sh`` script::
319
320         slabinfo-gnuplot.sh FOO_STATS [FOO_STATS2 .. FOO_STATSN]
321
322    The ``slabinfo-gnuplot.sh`` script will pre-processes the collected records
323    and generates 3 png files (and 3 pre-processing cache files) per STATS
324    file:
325    - Slabcache Totals: FOO_STATS-totals.png
326    - Slabs sorted by size: FOO_STATS-slabs-by-size.png
327    - Slabs sorted by loss: FOO_STATS-slabs-by-loss.png
328
329 Another use case, when ``slabinfo-gnuplot.sh`` can be useful, is when you
330 need to compare slabs' behaviour "prior to" and "after" some code
331 modification.  To help you out there, ``slabinfo-gnuplot.sh`` script
332 can 'merge' the `Slabcache Totals` sections from different
333 measurements. To visually compare N plots:
334
335 a) Collect as many STATS1, STATS2, .. STATSN files as you need::
336
337         while [ 1 ]; do slabinfo -X >> STATS<X>; sleep 1; done
338
339 b) Pre-process those STATS files::
340
341         slabinfo-gnuplot.sh STATS1 STATS2 .. STATSN
342
343 c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the
344    generated pre-processed \*-totals::
345
346         slabinfo-gnuplot.sh -t STATS1-totals STATS2-totals .. STATSN-totals
347
348    This will produce a single plot (png file).
349
350    Plots, expectedly, can be large so some fluctuations or small spikes
351    can go unnoticed. To deal with that, ``slabinfo-gnuplot.sh`` has two
352    options to 'zoom-in'/'zoom-out':
353
354    a) ``-s %d,%d`` -- overwrites the default image width and heigh
355    b) ``-r %d,%d`` -- specifies a range of samples to use (for example,
356       in ``slabinfo -X >> FOO_STATS; sleep 1;`` case, using a ``-r
357       40,60`` range will plot only samples collected between 40th and
358       60th seconds).
359
360 Christoph Lameter, May 30, 2007
361 Sergey Senozhatsky, October 23, 2015