Linux STREAMS (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.16 (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.16 (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.

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.

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.

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.

Kernel version 2.0.x is no longer supported and the LiS installation will fail if Configure detects this kernel version.

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.

LiS Module Location

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.

Parameter Passing Conventions

The 2.6 Linux kernel can be compiled in a manner that causes parameters to subroutines to be passed in registers instead of the stack. Some distributions built around 2.6 are compiled this way by default.

If your driver calls kernel routines directly it must be compiled in the same manner as the kernel, either register parameters or stack parameters. A mismatch will almost certainly lead to system crashes.

When the kernel is compiled for register passing the C compiler command line option "-mregparm=3" is included by the kernel makefiles. Omitting this option yields the default stack passing code.

When the LiS Configure script is run, usually implicitly via the initial "make", it senses how the kernel was compiled and sets up the LiS compilation to include the regparm option, or not.

In order to preserve STREAMS driver interface compatibility across different versions of the Linux kernel, LiS declares all functions that are called across the LiS/driver interface to use either stack parameter passing (the default) or register passing (see below) irrespective of the conventions used by the kernel.

Thus, to take the default case, the kernel can use register parameters but LiS will have all of its driver interface routines compiled so as to use stack parameters. This means that your STREAMS driver can be compiled for stack passing and can run with either convention in the kernel, without recompiling your driver.

You can use register passing conventions in your driver as well, if you like. As of this writing this feature is untesed. To do so, run the Configure script and pass the following option:

Configure --regparm=3

This sets the LiS/STREAMS-driver parameter passing interface independently of that used by the kernel. If you do this, be sure to compile your STREAMS driver using "-mregparm=3".

The STREAMS driver interface routines that are called by LiS are:

• open, close, put and service routines called via the queue structures.
• timeout and bufcall call-back routines.
• driver initialization and termination routines.
• driver interrupt service routines registered via LiS.

The functions in LiS that are called by STREAMS drivers, and which also conform to the selected parameter passing convention, are all enumerated in the LiS file exports.c.

Choice of Compiler

The LiS Configure script checks to see which compiler version was used to compile your kernel. It then attempts to locate a C compiler of the same version to use for compiling LiS. The script will print a message if it cannot find such a compiler.

A common situation, during the transition to the 2.6 kernel, is to run a 2.6 kernel on top of a 2.4 distribution such as Red Hat 9. The 2.6 kernel needs gcc version 3.3.3 to comple it and that compiler is not part of the RH9 distribution. Thus, in order to properly compile the 2.6 kernel you also need to download the correct C compiler, compile and install it on your system.