UnixWare 7 Release 7.1 Kstuff'ed kernels (kstuff)












UnixWare 7 Release 7.1 Kstuff'ed kernels

NOTE: Please click here for updated instructions.

The kstuff'ed kernels provide enhanced debugging environments for UnixWare 7 drivers. Running your driver under these kernels allow you to find and fix various problems that can cause erratic driver behavior and to obtain metrics about lock usage and contention problems.

Two different bundles are provided:

LEAKS.bundle.Z
Contains a kernel that is used to detect memory leaks and memory corruption.

debug.bundle.Z
Contains additional debugging information that is useful for general driver development and testing such as assertion and lock checking.

The kstuff'ed kernels should only be installed on test systems. A pair of systems is used: a source system where the kstuff'ed bundle is initially copied, and a target system, which should be running the released operating system kernel that corresponds to the kstuff'ed kernel and where the driver being tested is installed. The target system must have two or more CPUs with corresponding licenses.

It is possible to use a single system as both the source and the target system, but this is not recommended.

This is the first time this feature has been released.

For current information about the entire UnixWare/OpenServer Hardware Development Kit (HDK) release, see the HDK Release Notes.

Note: Documentation references on this page link to the Product Documentation. They are also available on your local system when the BASEman, HDKdoc, and HDKman packages are installed.

System requirements

This package does not have formal dependencies, although the bundles and utilities can only be used on UnixWare 7 systems.

Before installing the kstuff'ed bundles:

  1. Install the UnixWare 7, Release 7.1 kernel on both the source and target systems. Do not install any PTFs on the target system, since these could modify the kernel to be different than the one provided in the kstuff'ed bundles.

  2. Configure a NIC and install TCP/IP on both the source and target machines. Do not configure PPP and SLIP on these machines.

  3. Create a normal user account for yourself on the source machine. The examples that follow are for user "foo".

  4. Create a directory on the source machine for each kstuff'ed bundle you want to use. These directories can be located anywhere, but the standard place is within the $HOME directory of the user who is running the kstuff utilities. For example:

    mkdir $HOME/foo/i386at/etc/conf/kstuff.d/LEAKS
    mkdir $HOME/foo/i386at/etc/conf/kstuff.d/debug

    You can put both bundles on the source system at one time, although you can only run one at a time. The bundle to be used is determined by the setting of the $ROOT variable; see the "Configuring and running a kstuff'ed kernel" section of this document.

  5. Install kdb on the target machine. You will use special kdb functions to study the system while running the kstuff'ed kernels, and to diagnose the state of the system or your driver before or after a panic.

Installation

Before installing this version of the UnixWare 7 Release 7.1 Kstuff'ed kernel package on your system, you must remove any earlier versions.

To install the package from media distribution:

  1. Log in as root.

  2. Mount the CD-ROM by typing:
    mount  -r  -F  cdfs  /dev/cdrom/c1b0t0l0  /cdrom

  3. Copy the bundle.Z file(s) to the appropriate directory.
    cp /cdrom/info/kstuff/LEAKS.bundle.Z $HOME/foo/i386at/etc/conf/kstuff.d/LEAKS/bundle.Z
    cp  /cdrom/info/kstuff/debug.bundle.Z  $HOME/foo/i386at/etc/conf/kstuff.d/debug/bundle.Z

    These example lines install the kstuff'ed bundles in the home directory of the user foo, but they can be installed in any reasonable directory.

  4. Copy the scripts.tar file to a directory
    cp  /cdrom/info/kstuff/scripts.tar $HOME/foo/bin
    tar -xv scripts.tar
    PATH=$PATH:.

    All the scripts must be in the same directory and the $PATH environment variable for the user(s) who are running the kstuff'ed kernels must include ".".

  5. If desired, move the kstuff documentation files (kstuff.1.txt, kstuff.cmpflgs.txt, andkstuff_kdb.txt) from /cdrom/info/kstuff to a convenient location.

Configuring and running a kstuff'ed kernel

  1. Create user equivalency on the target machine. This means, if you are user "foo", on machine "source", the /.rhosts file on machine "target" should have the following lines:

    source foo
    source.my.domain.com foo
    1.2.3.4 foo     # IP address of machine "source"

    Run the netstat -a command on the "target" machine to get the valid IP address for the "source" machine. If the source machine has multiple NICs, list them all in the /.rhosts file.

    Verify that user equivalency is set up correctly on machine "target" by executing the following command as user "foo" on machine "source":

    rsh -l root target date

  2. On the source machine, set the $ROOT environment variable to the path of the bundle to be used:
    ROOT=$HOME/foo/i386at/etc/conf/kstuff.d/LEAKS
    OR
    ROOT=$HOME/foo/i386at/etc/conf/kstuff.d/debug

  3. Run the kstuff binary from the local directory:
    cd $HOME/foo/bin
    ./kstuff -v
    where target is the name of the target machine. A menu similar to the following is displayed:
    Available Kernel Trees:
    1) /etc/conf/kstuff.d/LEAKS
    q) quit
    Enter Kernel Number:

    Select option 1.

  4. You will be prompted with a string such as the following:

    Install the /etc/conf/kstuff.d/LEAKS as unix.foo on host target?

    This gives the pathname where the LEAKS bundle is installed. "foo" represents the user name, and "target" is the name of the target machine. Type "Y" and press Enter.

    You'll be reminded to create the /.rhosts file. Since that was done in an earlier step, type "Y" at the "Ready to continue?" prompt and press Enter. The system will display a series of informational messages. If errors occur, user equivalency is not set up correctly.

    If the installation is successful, the following message is displayed:

    Configuration merge complete in
    /etc/conf.unix.foo
    Ready to idbuild kernel? __

    The /etc/conf.unix.foo directory contains the files extracted from the bundle.Z file. Set the $ROOT environment variable to this directory on the target machine for subsequent idbuild commands. Alternately, you can use the -R /etc/conf.unix.foo option to idinstall and other utilities in /etc/conf/bin.

  5. If the /etc/conf directory on the target machine contains the DSP for the driver to be installed (compiled with the same flags as the kstuff'ed bundle you are using), you can idbuild the kernel and reboot the system. See the kstuff.cmpflgs.txt document included in this /info directory for information about the compile flags used for each bundle type.

    If your driver is not installed on the target system, compile it with the same flags used by the bundle you are using and install the driver into the /etc/conf directory with the following command:

    idinstall -a -k -R /etc/conf.unix.foo driver_name

    If $ROOT is set correctly on the target machine, run idbuild on the target machine. Alternately, you can issue the following command from the source machine:

    kstuff -I target

    You may want to use the kstuff -Y command to explicitly define the path for subsequent installs. See the kstuff(1) manual page that is provided in this directory for more information.

  6. When you idbuild the kernel, messages are displayed giving the progress. The final messages displayed are:
    Target will now be rebooted
    Ready to continue? __

    Enter y. The target machine runs init 6 to shutdown and reboot. After it reboots, you should edit the /stand/boot file to make the /stand/unix.foo the standard kernel for reboot.

    Alternately, you can intervene in the boot process each time by pressing Enter at the animated boot login until the boot screen is displayed. Enter b unix.foo to boot from the /stand/unix.foo kernel.

    Additional messages are displayed when you boot the system on a kstuff'ed kernel and the system runs slower because of the additional checks the kernel is performing, but otherwise, the system works as it normally does.

  7. For initial driver testing, it is best to set initstate=s. Enable the second processor on the target machine with the psradm(1M) command when you go to single-user mode; the second processor is automatically enabled when running in multiuser mode. Running the driver in single-user state means that there are fewer processes executing and makes it easier to concentrate on the specific issues with your driver.

  8. All subsequent modadmin commands will also use this new kernel. Whenever you boot from unix.foo, the kernel goes to the /etc/conf.unix.foo/mod.d to load the DLKM files.

  9. To debug system and driver startup, create the /stand/kdb.rc file with two blank lines. When you boot, specify initstate=S, FILEST=kdb.rc, and b unix.foo or whatever the name of the kstuff'ed kernel is. This puts you into kdb before most of the kernel has loaded, so you can set breakpoints for your driver's installation or single-step through system initialization.

Known limitations

Note the following limitations for this release:

  • A kstuffed kernel must be built from the production kernel that will be used. PTFs that are added to the Release 7.1 kernel are not reflected in this kernel.

  • You may experience a lock hierarchy violation panic when running a kstuff'ed kernel and more than one DEBUG driver installed. This occurs when both drivers are compiled with DEBUG and both use the same hierarchy(D5) values, typically starting with 0. The solution is to use the non-DEBUG version of the driver that is not being tested.

For more information

Additional information about debugging UnixWare 7 and OpenServer drivers can be found at Driver testing and debugging.

This package includes the following documentation about using the UnixWare 7 Release 7.1 Kstuff'ed kernel:

kstuff_kdb.txt
List of special kdb commands that are available only in the kstuffed kernels.

kstuff.cmpflgs.txt
Information about the compile flags used to create the kstuff'ed bundles.

kstuff(1)
Manual page for kstuff and kbundle commands.

For more information, contact your SCO representative or write to hdkinfo@sco.com.

Customers with UnixWare 7 source code can create their own kstuffed kernels that include any desired functionality. Instructions are given in the kstuff(1) manual page