Revised 3 November 1999 UnixWare 7 Release 7.1 Kstuff'ed kernels 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 should have two or more CPUs with corresponding licenses but will work with only one CPU. It is possible to use a single system as both the source and the target system(where the target system is "localhost"), but this is not recommended or supported. 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 Caldera Product Documentation (http://www.caldera.com/support/docs/). 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, if $HOME is /home/foo: mkdir -p $HOME/i386at/etc/conf/kstuff.d NOTE: You can put both bundles on the source system at one time, but you can only use 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. In some cases you cannot install kdb after initial system load(ISL) so you may need to reinstall the target machine and explictly select the kdb and osmp (if you have multiple CPUs) packages at that time. 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. Assuming $HOME is /home/foo, 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 one of the bundle.Z files to the appropriate directory. mkdir -p $HOME/i386at/etc/conf/kstuff.d cp /cdrom/info/kstuff/LEAKS.bundle.Z $HOME/i386at/etc/conf/kstuff.d/bundle.Z OR cp /cdrom/info/kstuff/debug.bundle.Z $HOME/i386at/etc/conf/kstuff.d/bundle.Z Depending on which bundle you want to use. 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. Extract the scripts.tar file in a directory in your PATH: mkdir -p $HOME/bin cd $HOME/bin tar -xvf /cdrom/info/kstuff/scripts.tar PATH=$PATH:$HOME/bin:/usr/sbin:. You must add the above PATH line in your .profile too. 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 this directory as well as ".". 5. mkdir -p $HOME/i386at/etc/conf/pack.d 6. 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 0. Make sure nslookup(1Mtcp) is able to resolve your machine name: nslookup `uname -n` 1. Create root 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 should return the output from the date command. Be sure and change the permissions of /.rhosts: chmod 600 /.rhosts 2. On the source machine, set the $ROOT environment variable to the path of the bundle to be used. The file $ROOT/etc/conf/kstuff.d/bundle.Z must always exist. ROOT=$HOME export ROOT You must add these lines to your .profile too. 3. Run the kstuff binary from the local directory: cd $HOME/bin ./kstuff -v target where target is the name of the target machine. A menu similar to the following is displayed: Available Kernel Trees: 1) /home/foo q) quit Enter Kernel Number: Select option 1. 4. You will be prompted with a string such as the following: Install the /home/foo as unix.foo on host target? This gives the pathname where the bundle.Z 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, FILES+=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 started, 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 Caldera representative or write to hdkinfo@caldera.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 _________________________________________________________________ Document version 7.1.0c 03 November 1999 (c) 2001 Caldera International, Inc. All rights reserved.