Linux STREAMS (LiS)

Installation of LiS

Installation of LiS is performed using a configuration script and then running "make". If you run "make" with no configuration file present, the makefile will run the configuration script automatically.

For the installation to proceed to its conclusion you must be logged in as "root". However, you can install LiS using a non-privileged user id. In this case the compilation of LiS will proceed but the installation of the resulting module will likely fail due to permission problems.

The easiest way to install LiS is to proceed as follows.

cd /usr/src/LiS-2.12 (Or wherever you installed the files)
make
make install

The version number in the above example is used for illustrative purposes only. Use the version number of the package that you downloaded.

The makefile will automatically run the LiS Configure script. You will be asked a series of questions by the configuration script and then the build will proceed. If your intent is to install and run LiS on your currently running Linux kernel then you are safe in answering all questions by hitting the Enter key, that is, using default answers.

The configuration script will make a symbolic link from /usr/src/LiS to whatever directory the Configure script was run from. This makes it easy to refer to the directory containing the latest installed version of LiS. This symbolic link will only be made if the Configure script (or initial "make") is run under "root".

Once the "make" is complete, enter make install to install the LiS utility programs in their proper places on your system.

If you want to uninstall LiS, enter make very-clean. When it completes you can then do rm -rf /usr/src/LiS-2.12 (or whatever version of LiS you are removing). For more information about uninstalling LiS, click here.

Configuration

The configuration is extremely simple for the most common case of using LiS. This case occurs when you intend to run LiS as a loadable module installed in the directory /lib/modules/kernel-version/misc and your kernel source resides in the directory /usr/src/linux. For this case you can simply hit Enter/Return to select the default answer for each question and proceed quickly to the compilation phase.

If at any time you think that the configuration process has taken a wrong turn, you can terminate it by typing Ctrl-C (or your equivalent "intr" character). You can then start over from the beginning.

Re-Configuration

You can re-configure LiS by running the Configure script again at any time. The defaults for a re-configuration are the settings arrived at by the most recent previous run of Configure.

If you get your configuration hopelessly out of whack, just remove the file config.in and run Configure (or make). This will start over just as for a fresh installation.

When you change the configuration parameters it is a good idea to do a "make clean" before doing a "make".

Making LiS

You can make LiS by typing "make; make install" in the LiS installation directory.

The following make targets are defined.

Default target Compile LiS plus binary drivers into streams.o. Copy to modules directory if configured to do so. Compile utility programs.
install Makes the LiS library routines and utilities. Installs utilities in their proper directories. Runs strmakenodes to make /dev entries for STREAMS drivers.
uninstall Removes the STREAMS utility programs and the files created in the /dev directory.
clean Remove all object code and utility programs. Leave configuration file in place.
realclean Like "clean" except remove configuration files as well.
very-clean This is equivalent to "make uninstall clean realclean".
dep Make dependencies. Done automatically by default target.
all Like default target except skip steps requiring root login.

Utility Programs Made

In addition to the file streams.o, which contains LiS and any STREAMS drivers linked with it, the build procedure also makes the following utility programs. These programs are copied to the indicated directory if the "make" uses the default make target and if you are logged in as "root". These programs are documented separately.

/usr/sbin/streams Prints out statistics from running LiS. Sets debug mask for LiS.
/usr/sbin/strconf Interprets STREAMS driver Config file and generates corresponding config.h and makenodes.c files.
/usr/sbin/strmakenodes Program to make /dev entries for STREAMS drivers. The result of compiling makenodes.c.
/usr/local/bin/strtst A comprehensive test program for STREAMS.
/usr/local/bin/timetst Times round-trip delay from user application to STREAMS loopback driver.

Of these programs, only strmakenodes and strconf are essential to the operation of LiS. Strmakenodes must be run prior to attempting to use any STREAMS application programs to make the proper entries in the /dev directory for STREAMS files.

The strconf program is needed for the build of LiS itself. However, the LiS build executes the program from the local LiS installation directory. Thus it is not necessary to copy this program to /usr/sbin in order to make streams.o.

Configuration Procedure

The following sections describe the steps of the Configure script.

User or Kernel

The first question posed by the Configure script is the type of environment that LiS is to run in. The default is to build LiS to run in the Linux kernel. You can also build a user-space version of LiS that can be used for "laboratory" testing. The QNX alternative is not useful.

Module or Kernel

The next question posed by the Configure script is whether you want to run LiS as a separate loadable module or link it into the kernel. The default is to run as a separate module. It used to be useful to link LiS into the kernel when you wanted to use GDB to debug kernel based STREAMS drivers. However, the kernel GDB tools are now sophisticated enough that it is just as easy to debug LiS as a loadable module.

Kernel Source Location

Configure asks you for the location of your kernel source tree. The default is /usr/src/linux and likely suffices for the vast majority of cases. Once Configure has this information it can determine the version of the kernel for which you are compiling LiS. The kernel version makes a difference in the amount of patching that must go into the kernel. Older (2.0) kernels require patching, new ones (2.2 and 2.4) do not.

If you are compiling for the kernel located in /usr/src/linux and the kernel version is 2.0.36 or 2.2.0 or later there is no patching of the kernel required to install LiS as a module. To link directly with the kernel, the "make" of LiS will insert a small patch into the kernel to cause LiS to be linked into the kernel and to arrange to call the LiS initialization routine at boot time.

We recommend that you use kernel version 2.0.36 or 2.2.x for installing the latest version of LiS. This latest version of LiS has been tested with 2.2 kernels only. It may not install or run properly on older kernels.

If your kernel source has not had "menuconfig" run on it yet, Configure will propose doing so at this time automatically.

Likewise, if you have not done a "make dep" on your kernel source yet, Configure will propose doing so at this time automatically.

Kernel Version Verification

The LiS Configure script discovers the version of your kernel by looking in several places in your kernel source directory. If it cannot determine your kernel version the LiS configuration will terminate. The Configure script cannot proceed without this information.

The Configure script then asks for your verification of the kernel version for which LiS is to be compiled. Note, that the kernel for which you are compiling LiS does not have to be the kernel version on which your system is running. If you gave Configure a pathname to your intended kernel source version in the previous step this could be a different kernel version than the one that is running on your machine.

You can also enter a kernel version other than the one found in version.h at this time. However, entering such a version may cause the subsequent "make" to make unverified assumptions about your kernel version. So be careful about answering this question with anything other than an Enter/Return.

If the kernel version displayed does not match your idea of the version of the kernel that resides at the indicated location on disk, it is probably best to terminate the Configure program at this point and investigate rather than end up compilation or module loading errors.

Kernel Option Verification

The Configure script will ask you if you intend to run LiS on the same kernel that is running on the installation machine. This is the most common case of installing LiS, so the default answer is "yes."

If you answer "yes" to this question then the Configure script will verify that the kernel version in you kernel source directory matches the stated version of your running kernel. It will also verify that the kernel options of SMP and module versions are the same between the two kernel locations. If any discrepencies are found the installation of LiS will terminate.

It is important for the correct operation of LiS, and the STREAMS drivers that utilize LiS, that these options be in agreement between the running kernel and the kernel source. If they are not, the consequences can be anything from unresolved externals when attempting to load LiS all the way to system hangs on multi-CPU systems because of having the SMP option set incorrectly.

Therefore, it is important that you correct these problems and bring the kernel source and running kernel into agreement before installing LiS.

One common source of error is to recompile your kernel in /usr/src/linux and run lilo, but fail to copy the kernel executable to one of the kernel locations specified in /etc/lilo.conf. In this case you may think that you have successfully compiled and booted a new kernel when, in fact, you are running on your old kernel.

Automatic Kernel Building

If you answered the first question posed by Configure by indicating that you wish to have LiS linked directly in with the kernel, Configure now offers you the option of having a "make" in the LiS directory also proceed to a "make" in your indicated kernel directory. The default, selected by hitting Enter/Return, is not to do so.

If you elected to have an LiS build perform a kernel build automatically then Configure will now ask you which kernel build target you would like to have used. The default is bzImage, the theory being that you may be installing large STREAMS drivers into the kernel and therefore will need a "big" kernel image. LiS will add about 85K of code and data to your kernel size. The default is not bzlilo based on the idea that you likely are using this machine as a development machine and intend to run the resulting LiS module on a different system.

In any case, you can select the kernel "make" target that suits your needs.

LiS Module Location

If you have elected to build LiS as an installable module, rather than to link directly into the kernel, you will be asked whether or not you wish the "make" to copy the resulting streams.o file to the modules directory associated with your selected kernel version. The alternative is to have "make" build streams.o in the LiS directory and simply leave it there for manual copying later.

If you are intending to run LiS on the machine that you are using for the compilation you will probably want to answer this question with a "y". If you are intending to compile on this machine and copy the result to another machine for testing, then "n" is the appropriate answer here.

Debugging

If you intend to link LiS directly into the kernel and use GDB for kernel level debugging then you will likely want LiS to be compiled using the -g option. Configure asks you about this so that you can control whether to compile using -g or not.