docs: chcpu and readprofile are sysadmin utils

Signed-off-by: Sami Kerola <kerolasa@iki.fi>

1 files changed, 168 insertions, 0 deletions

diff --git a/sys-utils/readprofile.8 b/sys-utils/readprofile.8
new file mode 100644
index 000000000..a27043590
--- /dev/null
+++ b/sys-utils/readprofile.8
@@ -0,0 +1,168 @@
+.TH READPROFILE "8" "May 1996" "util-linux" "System Administration"
+.SH NAME
+readprofile - read kernel profiling information
+.SH SYNOPSIS
+.B readprofile
+.RI [ options ]
+
+.SH VERSION
+This manpage documents version 2.0 of the program.
+
+.SH DESCRIPTION
+
+.LP
+The
+.B readprofile
+command uses the
+.B /proc/profile
+information to print ascii data on standard output.
+The output is
+organized in three columns: the first is the number of clock ticks,
+the second is the name of the C function in the kernel where those many
+ticks occurred, and the third is the normalized `load' of the procedure,
+calculated as a ratio between the number of ticks and the length of
+the procedure. The output is filled with blanks to ease readability.
+
+.LP
+Available command line options are the following:
+
+.TP
+.BI \-m " mapfile"
+Specify a mapfile, which by default is
+.B /usr/src/linux/System.map.
+You should specify the map file on cmdline if your current kernel isn't the
+last one you compiled, or if you keep System.map elsewhere. If the name of
+the map file ends with `.gz' it is decompressed on the fly.
+
+.TP
+.BI \-p " pro-file"
+Specify a different profiling buffer, which by default is
+.B /proc/profile.
+Using a different pro-file is useful if you want to `freeze' the
+kernel profiling at some time and read it later. The
+.B /proc/profile
+file can be copied using `cat' or `cp'. There is no more support for
+compressed profile buffers, like in
+.B readprofile-1.1,
+because the program needs to know the size of the buffer in advance.
+
+.TP
+.B \-i
+Info. This makes
+.B readprofile
+only print the profiling step used by the kernel.
+The profiling step is the resolution of the profiling buffer, and
+is chosen during kernel configuration (through `make config'),
+or in the kernel's command line.
+If the
+.B \-t
+(terse) switch is used together with
+.B \-i
+only the decimal number is printed.
+
+.TP
+.B \-a
+Print all symbols in the mapfile. By default the procedures with 0 reported
+ticks are not printed.
+
+.TP
+.B \-b
+Print individual histogram-bin counts.
+
+.TP
+.B \-r
+Reset the profiling buffer. This can only be invoked by root, because
+.B /proc/profile
+is readable by everybody but writable only by the superuser. However,
+you can make
+.B readprofile
+setuid 0, in order to reset the buffer without gaining privileges.
+
+.TP
+.BI \-M " multiplier"
+On some architectures it is possible to alter the frequency at which
+the kernel delivers profiling interrupts to each CPU.  This option allows you to
+set the frequency, as a multiplier of the system clock frequency, HZ.
+This is supported on i386-SMP (2.2 and 2.4 kernel) and also on sparc-SMP
+and sparc64-SMP (2.4 kernel).  This option also resets the profiling buffer,
+and requires superuser privileges.
+
+.TP
+.B \-v
+Verbose. The output is organized in four columns and filled with blanks.
+The first column is the RAM address of a kernel function, the second is
+the name of the function, the third is the number of clock ticks and the
+last is the normalized load.
+
+.TP
+.B \-V
+Version. This makes
+.B readprofile
+print its version number and exit.
+
+.SH EXAMPLES
+Browse the profiling buffer ordering by clock ticks:
+.nf
+   readprofile | sort -nr | less
+
+.fi
+Print the 20 most loaded procedures:
+.nf
+   readprofile | sort -nr +2 | head -20
+
+.fi
+Print only filesystem profile:
+.nf
+   readprofile | grep _ext2
+
+.fi
+Look at all the kernel information, with ram addresses"
+.nf
+   readprofile -av | less
+
+.fi
+Browse a `freezed' profile buffer for a non current kernel:
+.nf
+   readprofile -p ~/profile.freeze -m /zImage.map.gz
+
+.fi
+Request profiling at 2kHz per CPU, and reset the profiling buffer
+.nf
+   sudo readprofile -M 20
+
+.fi
+
+.SH BUGS
+
+.LP
+.B readprofile
+only works with an 1.3.x or newer kernel,
+because
+.B /proc/profile
+changed in the step from 1.2 to 1.3
+
+.LP
+This program only works with ELF kernels. The change for a.out kernels
+is trivial, and left as an exercise to the a.out user.
+
+.LP
+To enable profiling, the kernel must be rebooted, because no profiling module
+is available, and it wouldn't be easy to build. To enable profiling,
+you can specify "profile=2" (or another number) on the kernel commandline.
+The number you specify is the two-exponent used as profiling step.
+
+.LP
+Profiling is disabled when interrupts are inhibited. This means that many
+profiling ticks happen when interrupts are re-enabled. Watch out for
+misleading information.
+
+.SH FILES
+.nf
+/proc/profile              A binary snapshot of the profiling buffer.
+/usr/src/linux/System.map  The symbol table for the kernel.
+/usr/src/linux/*           The program being profiled :-)
+.fi
+
+.SH AVAILABILITY
+The readprofile command is part of the util-linux package and is available from
+ftp://ftp.kernel.org/pub/linux/utils/util-linux/.