1 files changed, 153 insertions, 0 deletions
diff --git a/sys-utils/readprofile.8 b/sys-utils/readprofile.8
new file mode 100644
index 0000000..a37aa0a
--- /dev/null
+++ b/sys-utils/readprofile.8
@@ -0,0 +1,153 @@
+.TH READPROFILE "8" "October 2011" "util-linux" "System Administration"
+.SH NAME
+readprofile \- read kernel profiling information
+.SH SYNOPSIS
+.B readprofile
+[options]
+.SH VERSION
+This manpage documents version 2.0 of the program.
+.SH DESCRIPTION
+.LP
+The
+.B readprofile
+command uses the
+.I /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.
+.SH OPTIONS
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+Print all symbols in the mapfile.  By default the procedures with
+reported ticks are not printed.
+.TP
+\fB\-b\fR, \fB\-\-histbin\fR
+Print individual histogram-bin counts.
+.TP
+\fB\-i\fR, \fB\-\-info\fR
+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
+\fB\-m\fR, \fB\-\-mapfile\fR \fImapfile\fR
+Specify a mapfile, which by default is
+.IR /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
+\fB\-M\fR, \fB\-\-multiplier\fR \fImultiplier\fR
+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. Linux 2.6.16 dropped multiplier support for most systems.
+This option also resets the profiling buffer, and requires superuser
+privileges.
+.TP
+\fB\-p\fR, \fB\-\-profile\fR \fIpro-file\fR
+Specify a different profiling buffer, which by default is
+.IR /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
+.I /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
+\fB\-r\fR, \fB\-\-reset\fR
+Reset the profiling buffer.  This can only be invoked by root,
+because
+.I /proc/profile
+is readable by everybody but writable only by the superuser.
+However, you can make
+.B readprofile
+set-user-ID 0, in order to reset the buffer without gaining privileges.
+.TP
+\fB\-s, \fB\-\-counters\fR
+Print individual counters within functions.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+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
+\fB\-V\fR, \fB\-\-version\fR
+Display version information and exit.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display help text 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 `frozen' 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 a 1.3.x or newer kernel, because
+.I /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
+.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .