
 ================================================================
          COMPILING DRIVERS, for Linux Newbies

This text provides a very minimal introduction to compiling drivers,
particularly WinModem drivers under Linux.  All points are covered in
much more detail in the Linux Kernel-HOWTO which is likely included
in the documentation set, installed within /usr/share/doc/ folders.

All that follows can be summarised in a few steps/actions:
  Install a kernel_source package representing your kernel.
  As it will match only one of several kernels that could have been installed
  and NOT necessarily yours, clean out any remnants of earlier usages with:
  	make mrproper
  Copy in your kernel's configuration file and have if read with:
	make oldconfig
  Edit if necessary the fourth line of the Makefile, which completes
  specification of where drivers will be installed to.
  FileName.h encoding dependencies between cogent code parts will next be assembelled by:
	make dep
  which for the 2.6.n kernel releases is instead automatically included in:
  	make bzImage
  With kernel_source thus Correctly configured, the modem driver compilation and installation
  proceeds within its own resource package,with the included README providing these details;
  quite commonly there are only commands:
	make clean
	make DriverName
	make install
   which will compile the drivers and install them properly.
   The remainder of this text just expands on these issues and steps.


WinModem driver packages commonly include:
1) a readible Open Source component, which can be readily debugged by
experts in code. This component provides "wrappers" to common
kernel functions for an already complied, or BINARY format, component of the modem code.

2) A Closed Source component compiled into the bianry form, in which
proprietary information is encrypted. This will include the copyrighted Vn.nn compression algorithms.
In 2004, pre-compiled modem drivers are beginning to be included
for a few winmodems by some Linux distributions.
But the binary format precludes incorporation of the modem drivers in some Linux distributions
for legal reasons, practical reasons, and/or reasons of principle.

Since almost all the newer PCs are now equipped with WinModems,
many users will have to compile their own linux modem drivers.
Exceptions are the more expensive modems with Controller chipsets,
characteristic of the earliest modems.
They are supported by Open Source serial code included in Linux
distributions (Distros hereafter).

Winmodems are less expensive because of greatly reduced hardware costs.
They lack Controller chips and may additionally lack Digital Signal Processor (DSP) chips.
Some of the functions of the older Controller based chipsets are replaced
by a combination of software code and/or other System hardware.

Modems without a controller chip are referred to as "controllerless modems" and
modems lacking both a DSP and controller chips are referred to as "soft modems".
With faster central processor units (CPU), some processing tasks are performed
by the CPU for the HCF (host controller free) modems. The CPU does nearly all
the signal processing for soft modems. They are most often subsystems under
an AC'97 or MC97 modem controller, which could host one of a variety of softmodems.
There are however also soft PCI modems without such controllers, which still utilize
the common ac97_modem.o driver.  Additionally, each softmodem chipset type will have
a chipset specific driver, which YOU will in general have to compile from downloaded resources.

COMPILING is the process of converting human readable source code
into compact binary code that the Operating System (OS) uses most quickly.
For winmodems, code components from the modem chipset provider
are combined with KERNEL-HEADERS, thus generating one or more binary modem drivers.
They are commonly compiled as ModuleNames.o for 2.4.n kernels and ModuleNames.ko
for 2.6.n kernels.  They are installed into sub-folders of:
   /lib/modules/kernel-version/
Therefrom they can be dynamically inserted into the boot kernel of the
Operating System (OS) when needed, sometimes with auxiliary instructions from
   /etc/modules.conf
They can be removed from the kernel when no longer serving,
thus economizing on System resources.

Modem related resources may not have been installed during the primary Linux installation,
as WinModem hardware is often NOT recognized.  Search your Distro's package
descriptions for "modem" to reveal the status of related resources.  Read
the package description to determine whether pre-compiled modem drivers were provided.
RESOURCES of a few types are needed to get on line. Do PREFERABLE use your System's
package maintenance system for the installation. This should guarantee that
any DEPENDENT packages will be called into the installation process. As a preliminary
1) Install your distributions package providing the KPPP, WVDIAL and MINICOM dialer utilities.
Dependencies within such packages will also drive the unpacking of ppp related modules
from compressed to a functional form :
   module.o.gz --> modules.o
or for 2.6.n kernels
   module.ko.gz --> module.ko
In addition these dialers will later aiding testing and configuration,
which is to be performed only AFTER, the modem's drivers are installed.

2) Download if necessary and modem driver package specific to your modem hardware.
3a) Install your distrbution's kernel-source package, necessary for preparing kernel-headers.
Or for Debian style distributions,
3b) install the kernel-header-2.4.25-marv1.deb package matching your kernel version 2.4.25-marv1.

The KERNEL-HEADERs have FileNames.h can can be read with a text browser.
Some are installed to
  /usr/include/
For systems with RPM package managers, they are provided by a package
  kernel-headers-SomeVersion.rpm
They specify:
 1) code bits to be incorporated by various of your installed programs, and
 2) the dependencies within the set of FileNames.h
However the whole set of   /usr/include/FileNames.h are  TOO FEW to support compiling.
The kernel-header-version.deb packages of Debian style Distros/
are designed to support compiling and are installed to /usr/src/kernel-headers-version/

A KERNEL-SOURCE package must more generally be installed,
and processed to produce needed kernel headers.
The kernel-source is some 20-30 MB now even in compressed form.
The kernel-source package provided by your Linux Distro SHOULD preferentially be used.
It will usually have some differences from that initially released at http://www.kernel.org .
Typically the installation process will set two symbolic links:
  /lib/modules/2.4.25-marv1/build -->  PATH_to/kernel-source-version/
  /usr/src/linux --> PATH_to/kernel-source-version/
They enable access to the kernel-headers needed during the modem driver compiling. Check with:
  ls -l /lib/modules/2.4.25-marv1/build
  ls -l /usr/src/linux
The former link is more usefull for Systems with alternative boot kernels,
and is mandatory for some modem compiler packages.

IMPORTANT: the kernel-source as installed in generally does NOT
represent your current kernel version, EVEN if the kernel-version is the same.
Only one of several possible kernels was installed on your System,
and the unpacked kernel-source needn't represent it exactly!!!
For example, in the RedHat Distro there is a set of kernel-configuration files within
   /usr/src/linux/configs/
Each is specialized for a different CPU (i586, i686, K6, etc),
Yet each will be represented by the VERY SAME version name: "uname -r" .
!!!! Thus a PROPER CONFIGURATION MUST BE DONE by You, before any usage of kernel-source !!!!

CONFIGURATION is started by moving into the kernel-source folder with one of:
  cd  /lib/modules/2.4.25-marv1/build
  cd /usr/src/linux

 There is a Makefile on your System at:  /lib/modules/2.4.25-marv1/build/Makefile
 with first few lines:

VERSION = 2
PATCHLEVEL = 4
SUBLEVEL = 25
EXTRAVERSION = 


For your current kernel, the four line should be
   EXTRAVERSION = -marv1
where -marv1 has been read from your current kernel version: 2.4.25-marv1.
But it this does not match what is Actually in the Makefile,
then it represents a Different kernel-header set then that of your kernel!!!

For Mandrake Linux their will generally be an included "mdk", such as:
 EXTRAVERSION = -3.1mdk
SuSE 9.0 had:
 EXTRAVERSION = -99-default
The first four makefile lines specify that:
a)  the compiled kernel modules/drivers will have encoded version labels such as:
   2.4.21-3.1mkd  OR   2.4.21-99-default
b)  such modules including modem drivers are installed into sub-folders of
   /lib/modules/2.4.21-3.1mkd/
   /lib/modules/2.4.21-99-default/
The major points are that compiled drivers must be both
kernel-release (the 2.4.21) AND EXTRAVERSION matched with the installed kernel.
Otherwise they may be installed uselessly and not be detected by the kernel
OR there will be a failure upon attempted insertion, with message including:
  a list of "unresolved symbols ".

Some  kernel-headers from a prior usage may be resident from a prior usage of the kernel-source/.
Check with:
  ls include/linux/
which may display abundant FileNames.h
The version of these headers will be in the UTS line displayed by
  cat include/linux/version.h
     #define UTS_RELEASE "2.4.21-3.1mdk" (as an example)

Next, list completely the contents of the kernel-source  with:
  ls -a
Where the " -a " additionally reveals ".dot-prefixed-confguration-files" such as
    .config  .hdepend .depends
which may be left over from the prior usage of the kernel-source. Below is an example:
 -------------------
    .config  .hdepend .depends
COPYING        Makefile        Rules.make    init    mm
CREDITS        README          arch        drivers  ipc     net
Documentation    conf.vars   fs       kernel  scripts
MAINTAINERS    REPORTING-BUGS  crypto      include  lib

Configuration of the kernel-source is where almost all the Mistakes occur!!!
Here is a way to do it correctly (but read through EXCEPTIONAL CASES below).
1)Within kernel-source/ folder, browse the README file for general guidance.
It will relate that the command:
#    make mrproper
cleans up leftovers from any previous usage .dot-files and the include/linux/ folder.
Additionally you may need to do an edit within Makefile, but ONLY that 4th line.
2) If necessary to edit, FIRST make a backup:
  cp Makefile Makefile.backup
then edit ONLY the 4th line of Makefile to match the EXTRAVERSION of 2.4.25-marv1
   EXTRAVERSION = -8.1enterprise
NEVER change anything else within the Makefile.

3) Set the dependencies of the current kernel.
For SuSE 9.0 and later, there is a command which does the following steps
#  make cloneconfig && make dep
Also in the browse the excellent README.SuSE in the kernel-source/ folder
For other Distros, the following steps are necessary, within the kernel-source/ folder
  copy the kernel-config file to  .config
          and DO SPECIFY that " . "
But where is it? For many Distros, it will be the file like
   /boot/config-2.4.25-marv1
matching the output of:
  uname -r
Or it may be the target of a symbolic link:  /boot/config -->
So
  cp /boot/config-2.4.25-marv1 .config
For SuSE 8.0 and earlier versions it is:
  cp /boot/vmlinuz.config  .config
PLEASE do not omit that "." in  .config as it is crucially necessary.
View .config with a text browser.
It is simply a listing of the code components used in the kernel and its modules:
  #
  # Automatically generated make config: don't edit
  #
  CONFIG_X86=y
  # CONFIG_SBUS is not set
  CONFIG_UID16=y
etc.

4) The  .config file will be read during
#  make oldconfig
which feeds its specifications through a process specifying
the SAME inter-dependencies previously used in compiling your kernel,
and generating fresh .dot-config files . They can be displayed with:
#   ls -al

5) Though it may be redundant after "make mrproper", it will do no harm to:
   make clean
5a) For the SuSe Linux versions 8.0 and previous , there will exist files:
  /boot/vmlinuz.autoconf.h
  /boot/vmlinuz.version.h
They MUST be copied as:
  cp /boot/vmlinuz.autoconf.h  /usr/src/linux/include/linux/autoconf.h
  cp /boot/vmlinuz.version.h    /usr/src/linux/include/linux/version.h

6) Now build kernel-headers with:
   make dep
7) Check for result FileNames.h with:
   ls  include/linux/
and
   cat include/linux/version.h
to verify the version.

EXCEPTIONAL CASES
For Distros with a Debian style package management system,
a kernel-header-Version.deb package matched with your kernel-version is available.
If may suffice to set a symbolic link:
  ln -s /usr/src/kernel-header-Version /lib/modules/2.4.25-marv1/build
and then compile the modem drivers.  If a custom kernel is to be compiled,
the kernel-package.deb software will GREATLY simplify the task.
Here is a typical command line:
   make-kpkg --revision 2:test.1 --append_to_version -MySpecial --arch_in_name --initrd kernel_headers kernel_image
wherein "--append_to_version -MySpecial" replaces the need for an edit of the Makefile 4th line:  EXTRAVERSION =

For the 2.4.nn kernels, a symbolic link is set during initial module installations:
  /lib/modules/kernel-version/build --> /usr/src/linux
The driver resources from Intel, SmartLink (and others?) have a modem Makefile using this build link.
So if your compile fails, check with:
  ls -l /lib/modules/kernel-version/build
Then establish the build link if necessary with:
  ln -s PATH-To/kernel-source or headers folder/ /lib/modules/kernel-version/build
Do NOT forget the "-s" for symbolic, or you will Duplicate folder contents

As already mentioned above, for SuSE distributions before 9.0, there may be files:
  version.h   autoconfig.h
located in the /boot/ folder.  Before beginning a compile,
they should be copied to /usr/src/linux/include/linux/
Someone reported that a critical header file:  modversions.h
is written to /usr/src/linux/include/linux  ONLY if the
kernel-source package has been installed with the YaST package manager.

COMPILING the MODEM DRIVERS can now finally be done.
Unpack the compiler kit for your modem drivers,
cd into its folder, read any README files,
   make clean
FINALLY, your modem drivers will compiled by a command like
   make ModuleName
or perhaps
   make all
During this process, some of the kernel-header code with be joined
with the supplied modem specific code, and utils/s.o will be produced.
Follow and further instructions in the modem code resource
to install the drivers, often with:
   make install ModemDriver

