# Generating Instrumentation for Other Computers

cross-compiling script from here: http://sourceware.org/ml/systemtap/2008-q3/msg00310.html above; add short description, significance, howto, script (test first)

When users run a SystemTap script, SystemTap builds a kernel module out of that script. SystemTap then loads the module into the kernel, allowing it to extract the specified data directly from the kernel (refer to in for more information).

Normally, however, SystemTap scripts can only be run on systems where SystemTap is deployed (as in ). This could mean that if you want to run SystemTap on ten systems, you would need to deploy SystemTap on all those systems. In some cases, this may be neither feasible nor desired. For instance, corporate policy may prohibit an administrator from installing RPMs that provide compilers or debug information on specific machines, which will prevent the deployment of SystemTap.

To work around this, you can resort to cross-instrumentation. Cross-instrumentation is the process of generating SystemTap instrumentation module from a SystemTap script on one computer to be used on another computer. This process offers the following benefits:

- The kernel information packages for various machines can be installed on a single host machine.

- Each target machine only needs one RPM to be installed to use the generated SystemTap instrumentation module: `systemtap-runtime`.

Note

For the sake of simplicity, we will be using the following terms throughout this section:

- instrumentation module — the kernel module built from a SystemTap script; i.e. the SystemTap module is built on the host system, and will be loaded on the target kernel of target system.

  cross-instrumentation instrumentation module
  instrumentation module cross-instrumentation

- host system — the system on which you compile the instrumentation modules (from SystemTap scripts), to be loaded on target systems.

  cross-instrumentation host system
  host system cross-instrumentation

- target system — the system for which you are building the instrumentation module (from SystemTap scripts).

  cross-instrumentation target system
  target system cross-instrumentation

- target kernel — the kernel of the target system. This is the kernel on which you wish to load/run the instrumentation module.

  cross-instrumentation target kernel
  target kernel cross-instrumentation

Configuring a Host System and Target Systems

- Install the `systemtap-runtime` RPM on each target system.

- Determine the kernel running on each target system by running `uname -r` on each target system.

- Install SystemTap on the host system. You will be building the instrumentation module for the target systems on the host system. For instructions on how to install SystemTap, refer to .

- Using the target kernel version determined earlier, install the target kernel and related RPMs on the host system by the method described in . If multiple target systems use different target kernels, you will need to repeat this step for each different kernel used on the target systems.

cross-instrumentation configuration host system and target system
host system and target system cross-instrumentation configuration
target system and host system configuration

After performing , you can now build the instrumentation module (for any target system) on the host system.

To build the instrumentation module, run the following command on the host system (be sure to specify the appropriate values):

    stap -r kernel_version script -m module_name

Here, `kernel_version` refers to the version of the target kernel (the output of `uname -r` on the target machine), `script` refers to the script to be converted into an instrumentation module, and `module_name` is the desired name of the instrumentation module.

Note

To determine the architecture notation of a running kernel, run `uname -m`.

uname -m
determining architecture notation
architecture notation, determining

Once the instrumentation module is compiled, copy it to the target system and then load it using:

    staprun module_name.ko

For example, to create the instrumentation module `simple.ko` from a SystemTap script named `simple.stp` for the target kernel 2.6.18-92.1.10.el5 (on x86_64 architecture), use the following command:

`stap -r 2.6.18-92.1.10.el5 -e 'probe vfs.read {exit()}' -m simple`

This will create a module named `simple.ko`. To use the instrumentation module `simple.ko`, copy it to the target system and run the following command (on the target system):

`staprun simple.ko`

Important

The host system must be the same architecture and running the same distribution of Linux as the target system in order for the built instrumentation module to work.

cross-instrumentation building kernel modules from SystemTap scripts
cross-instrumentation generating instrumentation from SystemTap scripts
kernel modules from SystemTap scripts, building
building kernel modules from SystemTap scripts
instrumentation modules from SystemTap scripts, building
building instrumentation modules from SystemTap scripts
compiling instrumentation/kernel modules from SystemTap scripts
cross-compiling
cross-instrumentation advantages of
advantages of cross-instrumentation