oprofile for Debian
-------------------

For 0.9.2-2 and later versions
------------------------------
Starting with the version of OProfile, the 'oprofile-source' package
has been removed.  It only had value for Linux 2.4 and earlier kernels.
Starting with the etch release, 2.6 kernels are the default and the
kernel module source originally provided by 'oprofile-source' is now
contained in the upstream Linux kernel source.


For 0.9.2-1 and earlier versions
--------------------------------
This is the OProfile package for Debian.  OProfile has
been divided into three different packages for Debian:

   1) oprofile: contains all of the user-space components
      of OProfile.  These are all of the commands needed
      to start and stop data collection, as well as display
      what performance data has been collected.  Data is 
      collected by a small daemon that uses the kernel module
      described below.

   2) oprofile-source: contains all of the kernel source
      needed to build the dynamically-loaded kernel module
      that is used by the user-space commands.  The OProfile
      kernel module is the code that collects raw data from
      kernel-space, that is then moved to user-space by a
      small user-space daemon, and then processed by user-space
      commands to understand where performance bottlenecks might
      be.

   3) oprofile-modules-<kernel>: pre-compiled OProfile kernel
      modules for the various kernels.
      
Using the 'oprofile-source' or 'oprofile-modules-<kernel>' packages
are only necessary when running Linux kernel versions prior to 2.6.0.
Starting in Linux 2.5, the OProfile kernel module is included as
part of the standard kernel source tree (though it is listed as
an "experimental" module).

NB: when using the oprofile-source package, you will need to execute
the command 'make-kpkg' (from the package named 'kernel-package').
The provider of 'make-kpkg' recommends that users execute 'make
clean' at the top level of their kernel source tree before executing
'make-kpkg'.  Since 'make clean' removes object files and cleans up
dependency information, you may want to save those files before you
build the oprofile-source package.


Using vmlinuz or vmlinux
========================
In general, Linux kernels tend to be stored in a file called "vmlinuz"
-- a compressed kernel image.  Since OProfile needs to gather detailed
information from the kernel at run-time, yet maintain a fairly small
footprint, it needs to use a "vmlinux" kernel -- one that is not
compressed.  Fortunately, this is only true when you want profiling
information from the kernel itself; when profiling applications,
having vmlinux available is not required.  By default, the opcontrol
command will assume that vmlinux is available; to change that behavior,
use "opcontrol --no-vmlinux" instead.  If you are using oprof_start
(the GUI), there is a toggle box labeled "No kernel image" in the
"Configuration" tab that can be used to indicate if a vmlinux file
is available (off) or not (on).

If you wish to gather profiling information about your kernel, you
will need to build the kernel differently:

   -- On i386: instead of using "make bzImage", use "make vmlinux"

   -- On ia64: instead of using "make compressed", use "make vmlinux"

If your kernel image is too large when built this way (the make will
complain about the size of the kernel image), you will have to change
your kernel configuration (make config) so that more features are
built as modules.

Note that if you wish to use a file name other than "vmlinux", you
can also use "opcontrol --vmlinux=file" to tell opcontrol where the
kernel image is.

If you are using the 'make-kpkg' command to build a Debian kernel
image, read up on the variables that can be defined to control how
a kernel is built ("man kernel-pkg.conf").  The 'make-kpkg' command
is part of the package 'kernel-package', so you may have to install
it before you can read the man pages.  If you wish to have make-kpkg
automatically build a vmlinux image so you can profile the kernel,
edit the file /etc/kernel-pkg.conf (or ~/.kernel-pkg.conf) and add
this line:

        install_vmlinux=YES

Remember to format the line as you would with a Makefile; the
kernel-pkg.conf file is used as a snippet included into a Makefile
so it has to have proper syntax for 'make.'


Building A Kernel Module from Source
====================================
To build the OProfile kernel module from the contents of the
oprofile-source package, use the following commands:

    # cd /usr/src/linux
    # make-kpkg modules_image

When 'make-kpkg' is done, it will place a .deb file containing the
newly built OProfile kernel module in the directory /usr/src/.
For example, on an i386 machine, running a 2.4.19 kernel, the resulting
package will be called 'oprofile-modules-2.4.19_0.4-3_i386.deb' (the
'0.4-3' part is the OProfile version number, so you may see something
slightly different).  To install and use the OProfile kernel module
just built, using the example:

   # dpkg -i oprofile-modules-2.4.19-0.4-3_i386.deb
   # update-modules
   # modprobe oprofile allow_unload=1

For the 0.5.2 version of OProfile, we've converted to Qt3; in
some versions of sid, the file /etc/alternatives/moc does not get
properly linked to /usr/bin/moc-qt3 and will instead be linked to
/usr/bin/moc-qt2, which means you won't be able to build the package.
Fix the link and you should be fine.

SMP Systems and OProfile
========================
Note the use of the kernel module parameter "allow_unload=1" above.
This parameter determines whether or not rmmod (or modprobe -r)
will actually unload the OProfile kernel module.  If allow_unload=1,
rmmod will unload the module.  If allow_unload=0, rmmod will not
unload the module; you will have to reboot your system to unload it.

Why?  OProfile modifies the syscall table in order to intercept
syscalls in order to trace what is happening on a system.  On SMP
systems, with 2.4 Linux kernels, there used to be a possible race
condition where the syscall table would get corrupted, leaving the
kernel hopelessly confused.  Under exactly the right conditions, the
kernel module would be restoring the syscall table to it's original
state as some other CPU was trying to make a syscall (the inverse --
it would be part way through replacing the syscall table when someone
tried to use that table -- could also occur).  This led to the creation
and use of "allow_unload."

In 2.5 or 2.6 Linux kernels, it is not necessary to modify the syscall
table in order to collect the desired data.  Hence, the problem does
not exist with these kernels.

If you are using OProfile on an SMP system, and you are using the
original source tree, the kernel module is built such "allow_unload=0"
is the default behavior.  On single-CPU systems, the kernel module is
built so that "allow_unload=1" is the default behavior.  For Debian,
the rules file *always* sets the default to be "allow_unload=0."
If you wish different behavior, install the 'oprofile-sources' package,
modify the rules file (/usr/src/modules/oprofile/debian/rules) by
removing (or changing) 'CFLAGS="-DCONFIG_SMP"' in the $(MAKE) command
invoked in the kdist_image target, and use make-kpkg modules_image
as you normally would.

 -- Al Stone <ahs3@debian.org>, Sun, 17 Nov 2003 16:31:19 -0700
