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
There are two types of kstuff kernels:
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").
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
To see a listing of bundles for currently supported releases,
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
The original installed kernel is not affected,
nor is its /etc/conf tree.
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.
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.
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.
Documentation references on this page link to the
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.
Create a user account.
This document refers to that account as user "ktest".
any account will do.
Login under the user account you created.
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,
or .bashrc file to make this change permanent.
Download and run the
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.
The SETUP.sh script provided downloads the kstuff tools to
the documentation files to $HOME/doc,
and the bundles to $HOME/bundles.
it sets up corresponding $HOME/bin/.kstuff.rc and $HOME/bin/catalog
The user is then ready to use kstuff immediately with
the SCO bundles (provided that $HOME/bin is in the user's PATH).
if you cannot use SETUP.sh,
then you will need to perform some of these steps manually as described
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.
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.
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:
download the kstuff documentation files
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.
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.
Configure a NIC and install TCP/IP on both the source and target machines.
Do not configure PPP and SLIP on these machines.
Install kdb on the target machine.
You will use special kdb functions to study the system while running the
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"
If your target is a UnixWare system, you may wish to add the
following two lines to the end of /stand/boot:
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
Make sure nslookup(1Mtcp) is able to resolve your machine name:
nslookup `uname -n`
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
- 188.8.131.52 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
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
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]
Enter Kernel Number:
Select the number of the kernel you want to kstuff.
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?
"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.
- 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
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,
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.
- 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,
and then append a line such as the following (to instruct the boot loader
to load /stand/unix.ktest instead of /stand/unix):
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
The system runs slower because of the additional checks the kernel is
The leaks kernel does not display the extra messages,
plus it runs a bit faster.
kstuff kernels do not support USB devices or UDI device drivers.
any third part non-conforming device driver that might have been added
to the installed kernel will not appear in the kstuff kernel.
For initial device driver testing,
it is best to enter maintenance modes (obtained either by typing
ENTER or b unix.ktest at the boot
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
you can exit from the maintenance shell to continue the boot process.
This will start all processors and the usual set of system daemons.
- 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.
- 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).
kstuff kernels do not support USB devices or UDI device drivers.
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:
List of special kdb commands that are available
only in the kstuff kernels.
Information about the compile flags
used to create the kstuff bundles.
Manual page for kstuff and kbundle commands.
For more information, contact your SCO representative
or write to
Document version 7.1.4
17 June 2008