README












OpenServer 6/UnixWare 7 kstuff Kernels README

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

kstuff kernels are specific to the operating system and maintenance pack release. There are two types of kstuff kernels:

  • release.LEAKS.Z bundles: A kernel that is used to detect memory leaks and memory corruption. release is either an operating system release (for example, "osr600") or a release with the latest Maintenance Pack applied (for example, "uw714mp4").

  • release.DEBUG.Z bundles: Similar to the LEAKS kernel for the release/Maintenance Pack, but this kernel contains additional debugging information (such as assertion and lock checking) that is useful for general device driver development and testing.

To see a listing of bundles for currently supported releases, see the HDK test suites web page.

The kstuff usage involves systems playing two distinct roles: (1) a source system which serves as a repository for bundles, and (2) a target system on which the bundles will be installed. It is the target system which will execute the test kernel.

The operation of "kstuffing" a target system places a second and completely separate test kernel in /stand from the system installed kernel (/stand/unix). The original installed kernel is not affected, nor is its /etc/conf tree. For example, if user ktest creates a kstuff kernel, it will by default be named /stand/unix.ktest on the target system, with its "conf tree" located at /etc/conf.unix.ktest.

Ideally, target system should continue two or more CPUs (with corresponding licenses) to test MP operation. Also ideally the targets should contain more than 4 GB of memory. However, kstuff will work with only one CPU, and with any supported memory size.

It is possible to use a single system as both the source and the target system (i.e., the source system can kstuff to itself if desired).

For information about the entire UnixWare/OpenServer Hardware Developers Kit (HDK), 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 and HDKdoc packages are installed.

Setting Up a Source System

Before installing this version of the kstuff kernel package on your system, you must remove any earlier versions.

  1. Create a user account. This document refers to that account as user "ktest". However, any account will do.
  2. Login under the user account you created.

  3. Create directory $HOME/bin if it does not already exist. Add $HOME/bin to your $PATH if it's not already present. You may need to edit your .profile, .cshrc, or .bashrc file to make this change permanent.

  4. Download and run the SETUP.sh script to retrieve the files of interest.

    SETUP.sh uses curl(1) to load from the web. The /bin/curl binary is present in OpenServer 6 and UnixWare 7.1.4. It might not be present in older release.

  5. The SETUP.sh script provided downloads the kstuff tools to $HOME/bin directory, the documentation files to $HOME/doc, and the bundles to $HOME/bundles. Additionally, it sets up corresponding $HOME/bin/.kstuff.rc and $HOME/bin/catalog files. The user is then ready to use kstuff immediately with the SCO bundles (provided that $HOME/bin is in the user's PATH).

    However, if you cannot use SETUP.sh, then you will need to perform some of these steps manually as described next.

    You can download the kstuff components and tools from the HDK test suites web page. Create a bin directory and use tar to put the kstuff.tar kstuff tools in place.

    The default $HOME/bin/.kstuff contains a single catalog directive. For example: 

                    -d /u/ktest/bin/catalog

    The catalog contains lines of the following form: 

    ::/u/ktest/bundles/uw714mp4.DEBUG.Z:1:UnixWare 7.1.4 MP4 DEBUG Kernel
::/u/ktest/bundles/uw714mp4.LEAKS.Z:1:UnixWare 7.1.4 MP4 LEAKS Kernel
::/u/ktest/bundles/uw713mp5.DEBUG.Z:1:UnixWare 7.1.3 MP5 DEBUG Kernel
::/u/ktest/bundles/uw713mp5.LEAKS.Z:1:UnixWare 7.1.3 MP5 LEAKS Kernel
::/u/ktest/bundles/osr600mp4.DEBUG.Z:1:OpenServer 6.0.0 MP4 DEBUG Kernel
::/u/ktest/bundles/osr600mp4.LEAKS.Z:1:OpenServer 6.0.0 MP4 LEAKS Kernel
::/u/ktest/bundles/uw711mp5.DEBUG.Z:1:UnixWare 7.1.1 MP5 DEBUG Kernel
::/u/ktest/bundles/uw711mp5.LEAKS.Z:1:UnixWare 7.1.1 MP5 LEAKS Kernel

    See kstuff(1) for more info on how to configure kstuff.

  6. Other user accounts on the source system can make use of the kstuff facility just installed. The only requirement is to add the bin directory to the execution path. For example, a user might add the following to their .profile, .cshrc, or .bashrc file: 

    PATH=$PATH:~ktest/bin

  7. If desired, download the kstuff documentation files (kstuff(1), kstuff.cmpflgs.txt, and kstuff_kdb.txt) to a convenient location. (Setup.sh automatically downloads these files. If you did not run Setup.sh than you may want to manually retrieve these files.)

Target System requirements

This package does not have formal dependencies, although the bundles should only be installed on a system with the appropriate (if applicable) Maintenance Pack. For example, the uw714mp4.DEBUG.Z bundle should only be used on a UnixWare 7.1.4 system with Maintenance Pack 3. The osr600mp3.LEAKS.Z bundle should only be used on an OpenServer 6.0.0 system with Maintenance Pack 2.

Use of a target system with a more advanced kernel (e.g., later PTF or SLS or Maintenance Packs might work. But it can not be guaranteed, because future patches could potentially modify the system to be incompatible with the kernel provided in the kstuff bundles.

Preparing the Target System

Before you kstuff a target system.

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

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

    On earlier versions of UnixWare, in some cases you cannot install kdb after initial system load(ISL) so you may need to reinstall the target machine and explicitly select the kdb and osmp (if you have multiple CPUs) packages at that time.

    On OpenServer 6.0 you can simply run "mkdev kdb enable"

  3. If your target is a UnixWare system, you may wish to add the following two lines to the end of /stand/boot:

      AUTOBOOT=NO
      TIMEOUT=20

    This will cause the UnixWare to pend for 20 seconds before autoboot starts. This behavior is the default for OpenServer 6.

Configuring and running a kstuff kernel

  1. Make sure nslookup(1Mtcp) is able to resolve your machine name:

    nslookup `uname -n`

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

    source.my.domain.com ktest

    1.2.3.4 ktest              # 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 "ktest" on machine "source":

    rsh -l root target date

    This should return the output from the date command. Be sure and change the permissions of /.rhosts:

    chmod 600 /.rhosts

  3. Verify that $HOME/bin is in your PATH. Then execute kstuff as 

                    $ kstuff target

    where target is the name of the target machine. Or run kstuff -q target:tx where the "-q" option is for quiet mode and the ":tx" suffix creates kernel /stand/tx and conf tree /etc/conf.tx on the target system.

    A menu similar to the following is displayed: 

    Available Kernel Bundles:

   1) OpenServer 6.0.0 MP2 LEAKS Kernel [Jun 15]
   2) OpenServer 6.0.0 MP2 DEBUG Kernel [Jun 15]
   3) UnixWare 7.1.4 MP3 LEAKS Kernel [Jun 15]
   4) UnixWare 7.1.4 MP3 DEBUG Kernel [Jun 15]
   5) UnixWare 7.1.3 MP5 LEAKS Kernel [Jun 15]
   6) UnixWare 7.1.3 MP5 DEBUG Kernel [Jun 15]
   7) UnixWare 7.1.1 MP5 LEAKS Kernel [Jun 15]
   8) UnixWare 7.1.1 MP5 DEBUG Kernel [Jun 15]

   q) quit

Enter Kernel Number:

    Select the number of the kernel you want to kstuff.

  4. If you did not specify the -q option then you will be prompted with a string such as the following: 
    Install the OpenServer 6.0.0 MP2 LEAKS Kernel [Jun 15] as unix.ktest on host target?

    Here, "unix.ktest" is the name of the kernel to be install in /stand, 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.ktest

    Ready to idbuild kernel? __

    The /etc/conf.unix.ktest 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.ktest 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 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.ktest 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? __

    Before responding in the affirmative, you should obtain a root shell in another window, edit /stand/boot, and then append a line such as the following (to instruct the boot loader to load /stand/unix.ktest instead of /stand/unix): 

                    BOOTPROG=unix.ktest

    Alternately, you can intervene in the boot process, specifying explicitly the kernel you wish to load as shown here: 

    Starting SCO OpenServer Version 6...

Bootstrap Command Processor
Press  to boot into maintenance mode [? for help}

[auto boot unix 0:17] b unix.ktest

    The boot prompt is slightly different for UnixWare. But the command is the same (i.e. "b unix.ktest").

    Additional messages are displayed when you boot the system on a debug kernel. The system runs slower because of the additional checks the kernel is performing. The leaks kernel does not display the extra messages, plus it runs a bit faster.

    In general, kstuff kernels do not support USB devices or UDI device drivers. Moreover, any third part non-conforming device driver that might have been added to the installed kernel will not appear in the kstuff kernel.

  7. For initial device driver testing, it is best to enter maintenance modes (obtained either by typing ENTER or b unix.ktest at the boot prompt). At this point, only one processor is running, with a limited set of system daemons running in the background. This simplified debugging environment makes it easier to concentrate on the specific issues with your device driver.

    When you are ready, you can manually start additional processors using psradm(1M). Alternatively, you can exit from the maintenance shell to continue the boot process. This will start all processors and the usual set of system daemons.

  8. All subsequent modadmin commands will also use this new kernel. Whenever you boot from unix.ktest, the kernel goes to the /etc/conf.unix.ktest/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, FILES+=kdb.rc, and b unix.ktest or whatever the name of the kstuff 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.

    When you boot, it make sense to enter maintenance mode (obtained wither by typing ENTER or b unix.ktest at the boot prompt).

Known limitations

In general, kstuff kernels do not support USB devices or UDI device drivers. Moreover, any third part non-conforming driver that might have been added to the installed kernel will not appear in the kstuff kernel.

For more information

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

This package includes the following documentation about using the kstuff kernel:

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

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

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

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

Document version 7.1.4
17 June 2008