|
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:
- 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.
-
Configure a NIC and install TCP/IP on both the source
and target machines.
Do not configure PPP and SLIP on these machines.
- Create a normal user account for yourself
on the source machine.
The examples that follow are for user "foo".
-
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.
- 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:
- Log in as root.
- Mount the CD-ROM by typing:
mount -r -F cdfs /dev/cdrom/c1b0t0l0 /cdrom
- 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.
-
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 ".".
- 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
- 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
-
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
- 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.
-
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.
- 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.
- 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.
-
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.
- 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.
- 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
|
