PREREQUISITES

HOPE
----------------------------------------------
This kit will provide support for many
modems with Lucent chipsets, under a variety
of modem brand names. To simply test for a supported
PCI card modem, run:
$ ./scanmodem
Much additional information on modem chipset identification
is at: http://linmodems.technion.ac.il/ and
http://linmodems.org wherefrom there can be 
accessed the newslist and archives of discuss@linmodems.org

Hopeless
------------------------------------------------
This kit will FAIL to support currently known 
winmodems with chipsets produced by Conexant, Motorola, Intel
and US Robotics. AMR modems from Lucent/Agere and other
manufacturers and not suppoorted by this driver pair. 

For Returnees
-----------------------------------------------------
If the previous versions ltmodem-SomeVersion.tar.gz worked for you,
it is OK to just do it again:
$  ./build_module
             and follow through.       
Report problems through: discuss@linmodems.org
Send bug fixes  through: discuss@linmodems.org
Gratitude too,  through: discuss@linmodems.org

The installation sequence:
  ./build_module -> ./ltinst2 -> ./autoload
suffices to prepare and install ready-for-use modem drivers.
But YOU must still configure dialout scripts.

The commands ./build_rpm or ./build_deb are supplemental,
for use by more Advanced Users. They package the modem drivers
into installers. Such installers do bring the Benefits of
registering the drivers with software Package maintenance systems. 
If ./build_module succeeds, it will do no harm whatsover to try them.
Success is however dependent upon auxilliary packaging software.

First time users
-----------------------------------------------------
If your PC is now under a DOS or Microsoft Windows
operating system, STOP NOW!!!
Scripts (action files) herein are corrupted by DOSsy stops.
Reboot your PC under Linux.  Copy the kit into a Linux
workspace, say within /root or some /home/User folder.
     tar zxvf ltmodem-version.tar.gz
opens it. Move in with:
     cd ltmodem-version/
Start with:   1ST-READ. Eventually also browse
with DOCs/ Ltmodem.html and the other files as MUCH 
useful information is contained therein.
 
Apologies for being a bit pedantic herein. But the
guidance below incorporates LESSONS LEARNED with the
predecessor kits. More experienced Linux users
do FINE without this Lengthy blurb. BUT,
discuss@linmodems.org has been kept too busy dealing 
with some simpler issues/errors. Most Users will be
able to skip through sections of this text.

The kit contains specific modem "driver" code, to be
combining with external resources, producing a driver pait
   lt_modem.o and lt_serial.o
matched with your current Linux kernel. Your acting kernel
version is displayed by:
#	uname -r
First the external resources must be arranged and checked.
Examples of expected diagnostic responses are given below.
Your's may differ slightly, depending upon version
differences in utilities and hardware.  

Checks for modem identity
--------------------------------------------------------
SKIP this section if ./scanmodem reported a supported modem.
Hopefully there is a documentation assuring you that your
modem is of the Lucent chipset variety.  If you are 
guessing/hoping, there are some effective diagnostic tests
for the PCI class of hardware, including some modems. The supporting
software is commonly part of a "pcituils" installation package.
Diagnostics replies including "Lucent" or "Xircom" may be returned by:
#	lspci -v
00:0a.0 Communication controller: Lucent Microelectronics 56k WinModem (rev 01)
        Subsystem: Lucent Microelectronics LT WinModem 56k Data+Fax+Voice+Dsvd
        Flags: bus master, medium devsel, latency 0, IRQ 12
        Memory at da800000 (32-bit, non-prefetchable) [size=256]
        I/O ports at b800 [size=8]
        I/O ports at b400 [size=256]
        Capabilities: [f8] Power Management version 2  

Note the lead designation like " 00:0a.0 ".
Next look for the information block beginning with  00:0a.0 ,
when querying again with:
#	lspci -nv
00:0a.0 Class 0780: 11c1:0440 (rev 01)
        Subsystem: 11c1:0440
        Flags: bus master, medium devsel, latency 0, IRQ 12
        Memory at da800000 (32-bit, non-prefetchable) [size=256]
        I/O ports at b800 [size=8]
        I/O ports at b400 [size=256]
        Capabilities: [f8] Power Management version 2  
 
The modems known to be supported by the ltmodem.o driver have
ID number pairs shown in the following Table. Ignore the leading 0x. 
The id pair          11c1:0442 
is within the range: 11c1:0440-045c
and hence should (and is in this case) be supported by ltmodem.o.

Name 		vendor_id	device id range
-----------------------------------------------
LUCENT		0x11c1		0x0440-0x045c	
XIRCOM		0x115d		0x0000-0x000F	
XIRCOM		0x115d		0x0440-0x045c	
XIRCOM  	0x115d          0x0010-0x03ff  some/all? ids	

This information indicates that the modem has the Lucent
DSP (digital sound processing) chipset and predicts that
a driver compiled with this kit should serve well.
SKIP to the section "Utilities Versions".
 	
However there are ISA type Lucent modems, such as
that in some Compaq 1500 series (and many other) laptops,
which will not in general provide such explicit information. 

Read up on identifying modem hardware at:
http://linmodems.technion.ac.il/
Note that a success in compiling the drivers is 
NOT at all diagnostic. The compiling itself 
has no dependence at all on your modem hardware.

Utilities Versions.
---------------------------------------------------------
If you are using a 2.2.nn version kernel, SKIPping this
section is OK on your first trial. SKIP down to section:
  REQUIRED kernel-headers or kernel-source
But read and check carefully if you encounter problems, 
or will use a 2.4.nn series kernel.

The version requirements table below are for kernel-version
2.2.16 or lower, but should suffice through the 2.2.nn kernels:

Utility    lowest Version suggested    version test
+++++++++++++++++++++++++++++++++++++++++++++++++
Kernel modutils        2.1.121    ; insmod -V
Gnu C                  2.7.2.3    ; gcc --version
Gnu make               3.79.1     ; make --version
Binutils               2.8.1.0.23 ; ld -v
patch                  2.54       ; patch --version
Linux libc6 C Library  2.0.7pre6  ; ls -l /lib/libc*
Dynamic Linker (ld.so) 1.9.9      ; ldd --version
Linux C++ Library      2.7.2.8    ; ls -l /usr/lib/libg++.so.*
Procps                 2.0.3      ; ps --version
Psmisc                 17         ; pstree -V
Net-tools              1.52       ; hostname -Vld
Sh-utils               1.16       ; basename --v
Bash                   1.14.7     ; bash -version
PPP                    2.3.10     ; pppd --version
Util-linux             2.9z       ; mkfs --version
Pcmcia-cs              3.0.14     ; cardmgr -V
    The last is needed only for pcmcia card modems.

To compile under kernel 2.4.0 version sources,
the following additional requirements are recommended:
Gnu C                  2.91.66    # gcc --version
Gnu make               3.77       # make --version
binutils               2.9.1.0.25 # ld -v
patch                  2.5        # patch --version
util-linux             2.10o      # mkfs --version
modutils               2.4.0      # insmod -V
e2fsprogs              1.19       # tune2fs --version
pcmcia-cs              3.1.21     # cardmgr -V
PPP                    2.3.11     # pppd --version

REQUIRED kernel-headers or kernel-sources
----------------------------------------------------
The easiest and smallest satisfactory resource is a
kernel-header package with download size of about 1.5 Mb.
Kernel-header roles are explained in DOCs/ForNewbies.
They can be obtained from repositories for your Linux
distribution.  Its version must match that of the your
current kernel as displayed by:
$	uname -r

Some Linux distros are now providing alternative install kernels.
For them this next step is CRITICAL. 
You must identify on your own System, 
a config file specifying the contents of your kernel. For some Linux
Distros, it will be at:
  /boot/config-version
For RedHat there is a /usr/src/linux/configs directory.
The version IS same as that displayed by:
$ uname -r
and the start if the file is like:
===============
#
# Automatically generated make config: don't edit
#
CONFIG_X86=y
CONFIG_ISA=y
# CONFIG_SBUS is not set

Get the matching kernel-header package from your install CD or
download from your Linux repository. Install it with
whatever tools your distribution provides.  The common 
installation folder is:
   /usr/src/kernel-headers-version#/
At this point try running:
$  ./build_module
It all works, just follow through with included instructions.
Also see the explanation of build_rpm and build_deb below.

In the case of build_module failure, read on.
A symbolic link may be  necessary, made with:
  ln -s PATHto/kernel-headers-version /usr/src/linux
Test with:
#       ls /usr/src/linux/include/linux
802_11.h           fd1772.h                loop.h
a.out.h            fddidevice.h            lp.h  
ac97_codec.h       fdreg.h                 lvm.h 
acct.h             file.h                  major.h
acpi.h             filter.h                malloc.h
adb.h              fs.h                    matroxfb.h
adb_mouse.h        fs_struct.h             mc146818rtc.h
and MANY more.  These are the desired kernel-header files.
Some will compiled with the modem specific codes in this packages
SKIP to FINALLY

For the More Experienced planning to compile kernels, the
sources download size will be some 15 Mb. Reading a KERNEL-HowTo
is a MUST if you have not worked with such sources before.
Be sure that your Linux PC installation includes files: 	
	/usr/bin/nm86
	/usr/bin/size86
	/usr/bin/objdump86
which are commonly part of bin86 package of Linux distibutors.

After installation of the sources folder somewhere, set the
following MANDATORY symbolic link as Root, and with the
text on one line:
#	ln -sf /PATHtoFolderWith/kernel-sources-version/
		/usr/src/linux
This linkage is Necessary both for compiling ltmodem.o
through its own Makefile, and for compiling custom kernels.
Check with:
#	 ls -l /usr/src/linux
lrwxrwxrwx    1 root   src   17 Jan 25 21:24 /usr/src/linux
-> /Some//Folder/linux-2.2.16 and further with:
# 	ls  /usr/src/linux
COPYING        Makefile        arch     include  lib      scripts
CREDITS        README          debian   init     mm       
Documentation  REPORTING-BUGS  drivers  ipc      modules  
MAINTAINERS    Rules.make      fs       kernel   net      

If you have not yet run a configuration, the command:
#	ls /usr/src/linux/include/linux
will NOT yet return a Monster list of *.h header files.
These are produced after a few steps. Move to the sources
folder:
#	cd /usr/src/linux
Clean up of old debris:
#	make clean
Please check that building of modversions.h is enabled:
# 	grep MODVERSIONS /usr/src/linux/.config
should output:
		CONFIG_MODVERSIONS=y
If not, set up the configuration appropriate to your PC
within /usr/src/linux, with:
#	make menuconfig OR make xconfig
Lastly, get some coffee, while setting the dependencies
which build the header files:
#	make dep
When "make dep" is completed, check with:
#	ls /usr/src/linux/include/linux/modversions.h
/usr/src/linux/include/linux/modversions.h
AND to see even more headers:
#	ls /usr/src/linux/include/linux
802_11.h           fd1772.h                loop.h              
a.out.h            fddidevice.h            lp.h               
ac97_codec.h       fdreg.h                 lvm.h              
acct.h             file.h                  major.h            
acpi.h             filter.h                malloc.h           
adb.h              fs.h                    matroxfb.h        
adb_mouse.h        fs_struct.h             mc146818rtc.h     
and MANY more.  These are the desired kernel-header files  
needed in the compile


FINALLY
----------------------------------------------------
WITHOUT opening the inner source.tar.gz
     ./build_module
will compile drivers matching your current kernel.
Should there be a failure, first read DOCs/Compile_fail.txt
If ./build_module generates the drivers
    ./ltinst2
will install them, Lastly
    ./autoload
will prepare your system for demand loading of the drivers.
They are NOT loaded on boot up, but are autoloaded 
when modem usage is initiated. Do read DOCs/LastAdvice
if you have not previously used these drivers. 
Also browse the other DOCs files to be aware of what 
assistance they way provide for special problems.
The ltmodem Maintainer and Tester groups wish you 
good service on the Internet.

Report problems through: discuss@linmodems.org
Send bug fixes  through: discuss@linmodems.org
Gratitude too,  through: discuss@linmodems.org   


Build_rpm and build_deb
------------------------------------------------------
Once you have confirmed functionality, a final
step is to properly register the software, to gaurantee easy
upgrade and/or removal with your particular Linux
distributions package management tools.  For distributions
using a rpm package maintenance system.  This is aided  by
the command:

#   ./build_rpm
which if System requirements are met, will output a
    ltmodem-version.rpm
The whole installation will then be redone with the command
#  rpm -i version.rpm  
but this time, WITH Proper Registration of the package.
A report of a typeical ./build_rpm run is in DOCs/


Similarly, it your Linux distribution utilizes Debian style
package maintenance.  Construct an installer with:
$  ./build_deb
and run the installation with:
$  dpkg -i ltmodem-version.deb


Installed Components
------------------------------------------------------------
1) The modem driver pair are installed in the standard 
kernel modules path. 

2) There is a block with the file /etc/modules.conf 

# lt_drivers: autoloading and insertion parameter usage
alias char-major-62 lt_serial
alias /dev/tts/LT0 lt_serial
alias /dev/modem lt_serial
# The next line is a syntax example, rarely needed, to automate parameter
usage during lt_drivers insertion. See documentation for details 
# options lt_modem vendor_id=0x115d device_id=0x0420 Forced=3,0x130,0x2f8
# section for lt_drivers ends

3) If an rpm installer was used, the DOCs/ and utils/ are copied into:
  /usr/share/DOC/ltmodem-ver#/

4) If your system is using the device file system, there is a file:
  /etc/devfs/conf.d/ltmodem  
or lines are appended to:
  /etc/devfsd.conf
  

Removal of Installed Components 
-------------------------------------------------------------------
If installation was accomplished through:
  ./build_module
  ./ltinst2
  ./autoload
The installed components are cleaned out with:
  ./ltuninst2
  ./cleanup

If Debian or RPM installers were used,
then use the corresponding package removal tools.


FINI
========
Updated 04March2002 by Marv Stodolsky