Merge tag 'docs-for-linus' of git://git.lwn.net/linux

Pull documentation update from Jon Corbet:
 "There is a nice new document from Neil on how pathname lookups work
  and some new CAN driver documentation.  Beyond that, we have
  kernel-doc fixes, a bit more work to support reproducible builds, and
  the usual collection of small fixes"

* tag 'docs-for-linus' of git://git.lwn.net/linux: (34 commits)
  Documentation: add new description of path-name lookup.
  Documentation/vm/slub.txt: document slabinfo-gnuplot.sh
  Doc: ABI/stable: Fix typo in ABI/stable
  doc: Clarify that nmi_watchdog param is for hardlockups
  Typo correction for description in gpio document.
  DocBook: Fix kernel-doc to be case-insensitive for private:
  kernel-docs.txt: update kernelnewbies reference
  Doc:kvm: Fix typo in Doc/virtual/kvm
  Documentation/Changes: Add bc in "Current Minimal Requirements" section
  Documentation/email-clients.txt: remove trailing whitespace
  DocBook: Use a fixed encoding for output
  MAINTAINERS: The docs tree has moved
  Docs/kernel-parameters: Add earlycon devicetree usage
  SubmittingPatches: make Subject examples match the de facto standard
  Documentation: gpio: mention that <function>-gpio has been deprecated
  Documentation: cgroups: just fix a few typos
  Documentation: Update kselftest.txt
  Documentation: DMA API: Be more explicit that nents is always the same
  Documentation: Update the default value of crashkernel low
  zram: update documentation
  ...

1 files changed, 59 insertions, 0 deletions

diff --git a/Documentation/vm/slub.txt b/Documentation/vm/slub.txt
index b0c6d1bbb434..699d8ea5c230 100644
--- a/Documentation/vm/slub.txt
+++ b/Documentation/vm/slub.txt
@@ -280,4 +280,63 @@ of other objects.
 
 	slub_debug=FZ,dentry
 
+Extended slabinfo mode and plotting
+-----------------------------------
+
+The slabinfo tool has a special 'extended' ('-X') mode that includes:
+ - Slabcache Totals
+ - Slabs sorted by size (up to -N <num> slabs, default 1)
+ - Slabs sorted by loss (up to -N <num> slabs, default 1)
+
+Additionally, in this mode slabinfo does not dynamically scale sizes (G/M/K)
+and reports everything in bytes (this functionality is also available to
+other slabinfo modes via '-B' option) which makes reporting more precise and
+accurate. Moreover, in some sense the `-X' mode also simplifies the analysis
+of slabs' behaviour, because its output can be plotted using the
+slabinfo-gnuplot.sh script. So it pushes the analysis from looking through
+the numbers (tons of numbers) to something easier -- visual analysis.
+
+To generate plots:
+a) collect slabinfo extended records, for example:
+
+  while [ 1 ]; do slabinfo -X >> FOO_STATS; sleep 1; done
+
+b) pass stats file(-s) to slabinfo-gnuplot.sh script:
+  slabinfo-gnuplot.sh FOO_STATS [FOO_STATS2 .. FOO_STATSN]
+
+The slabinfo-gnuplot.sh script will pre-processes the collected records
+and generates 3 png files (and 3 pre-processing cache files) per STATS
+file:
+ - Slabcache Totals: FOO_STATS-totals.png
+ - Slabs sorted by size: FOO_STATS-slabs-by-size.png
+ - Slabs sorted by loss: FOO_STATS-slabs-by-loss.png
+
+Another use case, when slabinfo-gnuplot can be useful, is when you need
+to compare slabs' behaviour "prior to" and "after" some code modification.
+To help you out there, slabinfo-gnuplot.sh script can 'merge' the
+`Slabcache Totals` sections from different measurements. To visually
+compare N plots:
+
+a) Collect as many STATS1, STATS2, .. STATSN files as you need
+  while [ 1 ]; do slabinfo -X >> STATS<X>; sleep 1; done
+
+b) Pre-process those STATS files
+  slabinfo-gnuplot.sh STATS1 STATS2 .. STATSN
+
+c) Execute slabinfo-gnuplot.sh in '-t' mode, passing all of the
+generated pre-processed *-totals
+  slabinfo-gnuplot.sh -t STATS1-totals STATS2-totals .. STATSN-totals
+
+This will produce a single plot (png file).
+
+Plots, expectedly, can be large so some fluctuations or small spikes
+can go unnoticed. To deal with that, `slabinfo-gnuplot.sh' has two
+options to 'zoom-in'/'zoom-out':
+ a) -s %d,%d  overwrites the default image width and heigh
+ b) -r %d,%d  specifies a range of samples to use (for example,
+              in `slabinfo -X >> FOO_STATS; sleep 1;' case, using
+              a "-r 40,60" range will plot only samples collected
+              between 40th and 60th seconds).
+
 Christoph Lameter, May 30, 2007
+Sergey Senozhatsky, October 23, 2015