This directory contains a version of the "lockstat" command used
to control Lockmeter and to produce lock usage reports.
The lockmeter kernel patch is maintained separately.
Note:  the interface between the kernel lockmeter functions and the
lockstat command is a static/compile-time interface, defined in the
<linux/lockmeter.h> header in the patched kernel sources.  A version
of that header is kept here under ./include/linux.  However, the lockstat
command must be kept in sync with the version of lockmeter.h in the
kernel patch.

To use lockmeter, you must apply the appropriate kernel patch[es] to your
kernel source tree--e.g., using quilt or by manually applying the patch[es].
Start with an appropriate .config, then "make oldconfig" and enable the
LOCKMETER config option.

	Note: lockmeter cannot be enabled for preemptible kernels.
	So, select the "Preempt NONE" option by commenting out any
	CONFIG_PREEMPT=y or "CONFIG_PREEMPT_VOLUNTARY=y" in the
	.config file before running "make oldconfig".
	TODO:  Preempt Voluntary might work?

Lockstat is the basic tool used to control the kernel's Lockmeter
functionality:  e.g., turning the kernel's data gathering on or off, and
retrieving that data from the kernel so that Lockstat can massage it and
produce printed reports.  See http://oss.sgi.com/projects/lockmeter for
details.

The default target of the Makefile builds the basic Lockstat tool.
Other targets include:
	install		install lockstat command and shell wrapper in
			BINDIR [default: /usr/local/bin].  Requires
			write access to BINDIR.
	cscope		make cscope cross reference database.  Depends
			on cscope availability.
	clean		undo the make.  cleanup in prep for archive.
	tarball		make clean and create a tarball of this
			directory in ..

Compiling Lockstat requires the kernel file "lockmeter.h", which is found in
source tree of a lockmeter-capable kernel (i.e., a kernel that has been patched
by the lockmeter patch).  The Lockstat Makefile expects that the symbol
LINUX_INC_ROOT points to the include subdirectory in such a lockmeter-capable
kernel source tree.  LINUX_INC_ROOT defaults to:
	 "/lib/modules/$(uname -r)/build/include"
That is, the include subtree for the currently running kernel.  This would be
the case if you boot a lockmeter patched kernel and build lockstat from there.

If this default is incorrect, then you must redefine the symbol as appropriate
before attempting the 'make'.  For example, you could place the appropriate
lockmeter.h in the ./include/linux directory and change LINUX_INC_ROOT to
"./include".

After building lockstat, you may obtain "help" by invoking "./lockstat --help".
You do not require [root] privilege to list the help.  However, you will require
root privilege to control lockmeter and to collect lock statistics.

Note:  'make install' installs the lockstat executable in BINDIR as
lockstat-$(uname -r).  This assumes that you are building, or at least
installing, lockstat on the kernel revision for which it is intended.
Thus, you should boot into the lockmeter patched kernel before building
and installing lockstat.

Furthermore, 'make install' installs a "lockstat" wrapper script in
BINDIR that invokes the lockstat executable as "<BINDIR>/lockstat-$(uname -r)".
Again, this assumes that you are running on the kernel for which lockstat
was built.  If this is not the case, you'll need to invoke lockstat by its
full path--e.g., to generate a report from saved results on a different system.

TODO:  verify this is possible.

Questions?  Send email to owner-lockmeter@oss.sgi.com or to the entire
mailing list, lockmeter@oss.sgi.com.  Feel free to join the mailing list by
sending email to majordomo@oss.sgi.com with a text body
	subscribe lockmeter <your-email-address>
