<!doctype linuxdoc system>

<!--

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Changelog:
081600 - created first version, including lucent info
081700 - change to mini-howto, reorganize somewhat
081900 - ESScom
082200 - Point to modem howto, add troubleshooting
082300 - Finally got info on PCTel.  The installation recipes
section can be combined for all of them, methinks.
082400 - Reorganization, refined combined installation recipes
082500 - ppp2214.o link, post-install and pctel, module alignment is discretionary
082800 - MarvS patches, cleanup, some FAQ entries
083100 - Werner Heuser's/Mobilix suggestions: 3Com MiniPCI RFC, older kernels, setserial, 
       - MarvS's fixscript cleanup
090300 - Pavel says open source lucent driver is no longer under development.
         Small other fixes.
092200 - Back to work:  add in fixed fixscript
                        fix up FAQ quite a bit
092800 - Added conexant section
       - added link to homepage for recent version
       - fixed second ESS link
       - fixscript fixed for esscom.  Not pretty; hope to have a cleaner version
         from Mark soon.
102000 - MarvS version with Mark ppp fix info 
110400 - fix info about tty.h patch
111500 - small fixes
112100 - MarvS version
113000 - Intel is Ambient is Cirrus: HaM; new Lucent package; big overhaul
120500 - overhaul nearly complete
022401 - updates
 -->


<article>


<title>Linmodem-HOWTO   <!-- insert your title here -->
<author>Sean Walbran <tt/sean(at)walbran.org/ and Marvin Stodolsky <tt/stodolsk(at)erols.com/
<date>v0.43, 24 February 2001           <!-- always have a version number
and a date -->
<abstract>                          <!-- the abstract: a short and precise description -->
<nidx>template</nidx>    <!-- add indexing keywords as you go along -->
                         <!-- nidx means the indexed word is not in output of main text, only in the index -->

This document describes Linmodem (winmodem hardware) support under
Linux.  While such support is limited (almost exclusively
in the form of manufacturer-created, but unsupported, binary kernel modules),
the number of chipsets with some form of support is growing rapidly.

</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->


<sect>Introduction

<p>
<nidx>template!introduction</nidx>   <!-- here introduction is a sub entry of template, exclamationamrk is separator -->
This is the Linux Linmodem HOWTO document. It is intended as
a quick reference to help you find out if there is a way to get your (so-called) winmodem
working under Linux, and, if so, how to do it.  You should understand
from the outset that there may well be <em>no</em> support for your winmodem:
there is limited support for such modems, often in the form of vendor-created
but vendor-unsupported, binary-only kernel modules (though a small number of open-source
projects exist).  
<p>
To emphasize: your best bet under Linux is <em>certainly</em> to get 
a true hardware modem.  However, if you're stuck with a winmodem, perhaps
this document can help.
<p>
For the most up-to-date information about available Linmodem drivers,
visit  
<url url="http://www.idir.net/~gromitkc/winmodem.html#drivers" name="Rob Clark's site">,
<url url="http://walbran.org/sean/linux/stodolsk" name="our small resources page">,
and the Linmodems.org
<url url="http://linmodems.org/cgi-bin/ezmlm-cgi/1"  name="mailing list archives">.
General modem issues, such as IRQ settings and dialup scripts, are
dealt with much more thoroughly in the more general 
<url url="http://www.linuxdoc.org/HOWTO/Modem-HOWTO.html" name="Modem-HOWTO">,
<url url="http://www.linuxdoc.org/HOWTO/Serial-HOWTO.html" name="Serial-HOWTO">,
<url url="http://www.linuxdoc.org/HOWTO/PPP-HOWTO/index.html" name="PPP-HOWTO">,
and other related HOWTOs available at the <url url="http://www.linuxdoc.org/" 
name="Linux Documentation Project"> site and elsewhere.

<sect1>Copyright

<!--
This HOWTO is copyrighted 2000,2001 Sean Walbran, Marvin Stodolsky

Unless otherwise stated, Linux HOWTO documents are copyrighted by their
respective authors. Linux HOWTO documents may be reproduced and distributed
in whole or in part, in any medium physical or electronic, as long as
this copyright notice is retained on all copies. Commercial redistribution
is allowed and encouraged; however, the author would like to be notified of
any such distributions.

All translations, derivative works, or aggregate works incorporating
any Linux HOWTO documents must be covered under this copyright notice.
That is, you may not produce a derivative work from a HOWTO and impose
additional restrictions on its distribution. Exceptions to these rules
may be granted under certain conditions; please contact the Linux HOWTO
coordinator at the address given below.

The ideal situation would be that code for Linmodem drivers would be open-sourced,  
making this particular HOWTO completely unnecessary.  
This ideal being currently far from reality, we wish to promote dissemination 
of this information through as many channels as possible. 
However, we do wish to retain copyright on the
HOWTO documents, and would like to be notified of any plans to redistribute
the HOWTOs.

If you have questions, please contact
at linux-howto(at)metalab.unc.edu via email.

-->
<p>
Copyright (c) 2000,2001 by Sean Walbran, Marvin Stodolsky
<P>
Please freely copy and distribute (sell or give away) this document in
any format.  It's requested that corrections and/or comments be fowarded
to the document maintainer. You may create a derivative work and distribute
it provided that you:

<itemize>
<item>
Send your derivative work (in the most suitable format such as
sgml) to the LDP (Linux Documentation Project) or the like for posting
on the Internet.  If not the LDP, then let the LDP know where it is
available.
<item>
License the derivative work with this same license or use GPL.
Include a copyright notice and at least a pointer to the license used.
<item>
Give due credit to previous authors and major contributors.
</itemize>

  <P>
If you're considering making a derived work other than a translation,
it's requested that you discuss your plans with the current maintainer.



<sect1>Disclaimer
<p>

Use the information in this document at your own risk. We disavow any
potential liability for the contents of this document. Use of the
concepts, examples, and/or other content of this document is entirely
at your own risk.

All copyrights are owned by their owners, unless specifically noted
otherwise.  Use of a term in this document should not be regarded as
affecting the validity of any trademark or service mark.
In particular, since the term "Winmodem" is a trademark of US Robotics/3Com, 
we use the term "winmodem" here as does Rob Clark: to be read as "Winmodems(tm),
host-based modems, HCF-modems, HSP-modems, and all similar
modem-like hardware."  Linux is a trademark of Linus Torvalds.

Naming of particular products or brands should not be seen as endorsements.

It are strongly recommended to make a backup of important and/or
relevant files before any installation procedure.

<sect1>Credits
<p>
Most individual credits are given in the body of the text where appropriate.
<p>
A large amount of information contained in this document comes a variety
of great sources such as
<url url="http://www.idir.net/~gromitkc/winmodem.html" name="Rob Clark's site">,
the <url url="http://www.linmodems.org/" name="Linmodems.org">, 
mailing lists, and
Werner Heuser's <url url="http://mobilix.org" name="Mobilix"> pages.
<p>
Special thanks to Mark Spieth (mark(at)digivation.com.au) for
discussions, advice, and multiple and ongoing contributions.
<p>
This document itself was created using the SGML HOWTO template
created by Stein Gojen, as described in the 
<url url="http://www.linuxdoc.org/LDP/LDP-Author-Guide/index.html" name="HOWTO-HOWTO">.
site.
<p>
<sect1> Updates and Corrections
<p>
The most recent HTML version of this document is available at
<url url="http://walbran.org/sean/linux/linmodem-howto.html">,
as a single HTML file at
<url url="http://walbran.org/sean/linux/linmodem-howto-all.html">,
with source SGML at <url url="http://walbran.org/sean/linux/linmodem-howto.sgml">.
<p>
The old version of this document was getting huge and unwieldy, so this
rewrite seemed necessary.  To avoid the total loss of that information,
a copy of the old version is maintained at
<url url="http://walbran.org/sean/linux/linmodem-howto-old.html">.
<p>
Do you have a Linmodem which works, but is not described here?  Are you
developing a driver?  Do you think something in this document is incorrect
or misleading?  Do you think that your or someone else's work has been
used here but not appropriately credited?  Please don't hesitate to
email me at <tt/sean(at)walbran.org/ with corrections and suggestions. 
<p>
<!--
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 -->


<sect>Linmodems
<p>
<sect1> What is a Linmodem?
<p>
A Linmodem is the Linux implementation of a "winmodem" (see disclaimer).
These devices are 'less than' a modem in the sense that they depend
on software to perform, to a greater or lesser extent, the functions traditionally
handled by modem hardware.  The rationale for this is, of course,
that software is cheaper than hardware, and can be
upgraded/expanded/improved without
the use of screwdrivers (usually); however, for the modem to
function at all, one requires software that can
run on one's preferred operating system.
<p>
<sect1> Which Linmodem hardware is supported?
<p>
An ever-growing number of winmodems will work under
Linux.  Each chipset for which a driver is known to exist has a
section in this document, below, describing its installation.  
Any other chipset has <em>no known support</em> under Linux
(at least, not known to us).
<p>

<sect1> How can I find out if my GeeWhiz 9.8.7 Modem / Laptop has one of these chipsets?
<p>
<sect2> Information from the system
<p>

The information about installed hardware using commands such as:
<itemize>
<item> PCI: <tt> cat /proc/pci </tt> and <tt> lspci </tt>
<item> ISA: <tt> pnpdump </tt> and <tt> isapnp </tt>
<item> Internal PCMCIA: <tt> cardctl ident </tt>
<item> General: <tt> dmesg | more </tt> and <tt> cat /proc/interrupts </tt>
</itemize>
<p>
MarvS notes that the Device Manager under Windows can provide similar information, 
but it should be
noted that a manufacturer will often simply put its brand name on a built-in modem, so
this information may not be as useful as you might hope (e.g., what chipset does
a "Compaq Internal 56k" modem have?).  Additional information may sometimes be
obtained by making a modem log, implemented under MS Windows as a check box
option within the Dial Up Networking menus.  The file produced is 
<tt>C:\WINDOWS\MODEM.LOG</tt>.  It will contain the modem initialization strings, 
and perhaps also the name of the modem configuration file, which may also contain 
other useful information.
<p>
<sect2> Modem names and identification numbers
<p>
If you know the precise name of your modem, you can try searching
the large Linux Modem Compatibility
<url url="http://www.idir.net/~gromitkc/winmodem.html#Database" name="Database">
at
<url url="http://www.idir.net/~gromitkc/winmodem.html" name="Rob Clark's site">.
The color/letter code on the left side of the table will indicate if
your modem is known to function or not under Linux.  The code "LM" indicates
a Linmodem, and the modem notes should indicate which driver you need.
A "WM" means it's a winmodem, but no Linux support is known to exist.
Be careful not to assume that modems with similar names will contain
the same chipsets, or will necessarily behave similarly whatsoever!  
Your WhizBang LX56
and your friend's WhizBang GT56 could have entirely different innards. 
<p>
If you do not know the precise name of your modem, you can search based
on the identification number of the modem (
on every modem there must be printed a registration number,
which may either be the board producer's designation, or,
alternatively, an FCC registration number.
An example photo of such an ID number on a modem board can be found at
<url url="http://www.idir.net/~gromitkc/fcc1.jpg"> on 
<url url="http://www.idir.net/~gromitkc/winmodem.html" name="Rob Clark's site">.)
Use your web browser's "Find in Page" to search his
<url url="http://www.idir.net/~gromitkc/winmodem.html#Database" name="table">
of modems and FCC ID's 
to obtain chipset/driver information.  Alternatively, you can directly
search the US Federal Communications Commission (FCC) database at
<url url="http://www.fcc.gov/oet/fccid/">.
Read the directions carefully, and be careful not to confuse O (the letter)
with 0 (the number), and other possible mixups.
<p>
<sect2> Laptops with internal modems
<p>
You may not be able to obtain the FCC ID number if you have a laptop
which you prefer not to open up, or are looking to buy a particular
machine and the vendor has not been polite enough to provide you
with the information nor a sample box for you to take apart and play with.  In these
cases, you might try: 
<itemize>
<item>
Kenneth Harker's <url url="http://www.cs.utexas.edu/users/kharker/linux-laptop/"
name="Linux on Laptops"> site indexes a large number of user-created sites
describing their experiences with Linux on particular laptop models.
<item>
Werner Heuser's <url url="http://mobilix.org/modem_linux.html" 
name="Mobilix: Linux Modems"> and <url url="http://mobilix.org/minipci_linux.html"
name="Mobilix: Linux Mini-PCI"> pages include lists of specifications for laptops
with internal modems and NIC's, as well as useful tips for obtaining more
information in case the model is not listed there.
<item> The computer vendor's manual, web site, or (horrors!) technical support.
<item> <url url="http://www.google.com">
<p>
</itemize>
<p>
<!--
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 -->
<sect> General Setup and Kernel Module Issues
<p>

<sect1> Kernel Module Support
<p>
All of the kernel drivers listed here are released as kernel modules; therefore,
you must be sure to have a kernel which supports modules.  In addition, 
"module version" support should be enabled to aid the use of 
kernels and modules which are not version matched, as described further below.
If you use a kernel from a reasonably recent Linux distribution, such module support
is most likely already enabled.  If you're compiling the kernel yourself, then you
should already be aware of how to enable modules, via the 
<url url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html" name="Kernel HOWTO">.  
In any case, you can check to make sure that the following
settings exist in your kernel configuration  file
(which is usually found under <tt>/usr/src/linux</tt>):
<verb>
CONFIG_MODULES=y
CONFIG_MODVERSIONS=y
</verb>
<p>

<sect1> ISA Plug-n-Play
<p>
If you have an ISA Plug-n-Play modem, you will most likely 
need to use isapnptools to allocate resources to the modem card.
For this, you need to have isapnptools installed and have an entry in 
the <tt>/etc/isapnp.conf</tt> file
 for the modem.  You should read the manual pages and the 
<url url="http://www.linuxdoc.org/HOWTO/Plug-and-Play-HOWTO.html"
 name="Plug-and-Play-HOWTO">, but if you have no other 
ISA devices you're concerned about, basically all you need to do is:
<enum>
<item> If possible, configure your BIOS to "Non-PNP OS."
<item> As root, run <tt>pnpdump</tt> to generate a prototype isapnp.conf
file based on probed cards and your system's current resource usage.
<item> Look for your modem in this output, and uncomment the lines
corresponding to the (otherwise unused) IRQ you wish to use for the
modem.  For example, Sean's <tt>isapnp.conf</tt> for a Thinkpad i1411 with
a Lucent LT modem includes:
<p>
<verb>
(CONFIGURE ACRd119/1 (LD 0                   
  (INT 0 (IRQ 11 (MODE +E)))                   
  (IO 1 (SIZE 8) (BASE 0x0100) (CHECK))       
  (NAME "ACRd119/1[0]{LT Win Modem        }") 
# (ACT Y)                                    
))                                           
</verb>
Strangely, in this case at least, it was necessary to leave
 the <tt>#(ACT Y)</tt> commented out.  If it doesn't work for you one way,
try it the other.
<item> Copy the file to <tt>/etc/isapnp.conf</tt>
<item> Reboot.  You should see a message along the lines of 'Initializing
ISA PNP devices...OK' on booting.  If it fails, you have probably selected
an IRQ/DMA setting which is already in use; try another of the options
given in the <tt>pnpdump</tt> output.
(Note that it is probably not necessary to reboot, if you run <tt>isapnp</tt>
with the right flags.  However, it's easiest for the beginner to simply reboot
at this point.)
</enum>
<p>

<sect1> PCI Modems
<p>   
If you wish to know more about your PCI modem
 than <tt>cat /proc/pci</tt> gives, utilities within the software package
<tt>pciutils</tt> are useful, such as <tt>scanpci</tt> and <tt>lspci</tt>.
In particular, <tt>lspci -vv</tt> gives lots of nice, useful information.
<p>

<sect1> Module tools
<p>
The following commands are useful when dealing with modules.  Many
require root priveleges.  See the manual pages (e.g., <tt>man insmod</tt>)
for more detailed information on these commands.
<p>
<sect2> insmod, insmod -f, and modprobe
<p>
A version-matched kernel module should usually be inserted using the command 
<tt>modprobe</tt> <em>module_name</em>; <tt>modprobe</tt> will try to
insert any other modules on which your module depends (as determined
by <tt>depmod</tt>, described below). 
<p>
A single module can be inserted (without those modules on which it depends)
using the command <tt>insmod</tt> <em>module_name</em>.  
If the module were compiled under a different kernel than the current one,
<tt>insmod</tt> would report the version mismatch and refuse load the module.
One can, however, pass a flag to force the module to load despite the mismatch:
<tt>insmod -f</tt> <em>module_name</em>.  If the kernel interface the
module uses did not actually change with the kernel version, the
module will be inserted and could be to some degree functional.  
<p>
This is the case with, for example, the ESS modem module <tt>esscom.o</tt>
which, while compiled under 2.2.12, can be forcibly inserted with later kernels
and will function to a greater or lesser extent up through kernel version 2.2.14
without further changes; beyond 2.2.15, the patch to <tt>tty.h</tt> described
below is required.  However, even forcing insertion fails for kernels
from the 2.4 series.
<p>

<sect2> rmmod
<p>
A module can be unloaded (removed from the kernel) after use by issuing
the command <tt>rmmod</tt>.
<p>

<sect2> depmod
<p>
The <tt>depmod</tt> commands analyzes module dependencies.
The compatility of precompiled modules with a running kernel
can be checked with a command like:
<verb>
   depmod -e ltmodem.o
</verb>
For the specific example of the ltmodem.o module compiled under kernel 2.2.12
with a running kernel 2.2.17, the returned information includes:
<itemize>
<item> depmod: *** Unresolved symbols in ltmodem.o
<item> depmod: 	bh_mask
<item> depmod: 	schedule_timeout
<item> depmod: 	request_region
<item> depmod: 	pcibios_read_co
<item>  and many others.
</itemize>
Using a module with unresolved symbols can be a dangerous thing, as described
below.
<p>

<sect> Tips and Tricks for Precompiled Modules with different Kernel Versions 
<p>
Many of the linmodem drivers are only available as precompiled, binary kernel modules.
Generally, modules/binaries
transparently function only with the kernel against which they were co-compiled.  Therefore,
getting a precompiled linmodem driver to work with your particular kernel could be a challenge.
<p>
Since the Linux kernel is a dynamically changing beast, it is very unfortunate that many
modem/chip vendors have not yet chosen to release source-code versions of their 
drivers, which would ensure your and our ability to modify these drivers appropriately as 
kernel source code evolves.  Some of the binary modules have been coaxed to function 
under some later kernel versions using various tricks, as described below; however,
even though a module may be rendered functional, it is advisable to use them minimally. 
Quoting an email from Mark Spieth, 
<p>
"A driver can never work properly if there are unresolved symbols, as it means
something is not going to work. Furthermore, it means that something
that would have been called will call something else in the kernel 
and this could be anything. This is <em>very</em> bad."
<p>
Therefore, you should be careful in using binary modules with a kernel
of a different version; proceed at your own risk.  If you require above all
that your modem function, consider downgrading your kernel to match the
module - this is by no means a ridiculous prospect.  Despite these warnings,
however, many others have used mismatched binary modules and kernels with only minor
annoyances ( such as the occasional kernel panic ) using tricks and tools such as
the following.

<sect1> Fixscripting
<p>
Mark Spieth has contributed a progressively improved series of "fixscripts"
for editing a binary module so that version mismatch warnings are eliminated.
Insertion of the "fixed" module then proceeds without the forcing flag, i.e. simply
<tt>insmod</tt> <em>module_name</em>.  Later versions also rename module symbols
to match those exported by the kernel, so that "Unresolved symbols" errors
are not returned by the test <tt>depmod -e</tt>.  It must be emphasized that this 
change is almost entirely cosmetic - it is still recommended that the module be used 
minimally. 
<p>
To use the fixscript on, for example, the (now-deprecated) binary Lucent module ltmodem.o,
make a working directory such as <tt>/root/modem</tt>.  
Obtain the latest fixscript from
<url url="http://www.test.dclabs.com.au/linmodem/fixscript">. 
Save the file as <tt>fixscript</tt>.  
View it with <tt>less</tt> or your favorite text editor to check that DOS hard stops were not 
accidentally acquired. They look like bold M, underlined M, or ^M depending upon your 
viewer/editor. NOTE: the viewer <tt>more</tt> does NOT display these DOS newlines.
<p>
 Make the 
file  executable with <tt>chmod +x fixscript</tt>.  
Generate a "fixed" module with, i.e.,
<verb>
    ./fixscript ltmodem.o ltmodem2217.o
</verb>
<p>
No errors should be generated by testing the module dependencies with
<verb>
    depmod -e ltmodem2217.o
</verb>
<p>
and insertion should succeed with a simple, non-forced,
<verb>
    insmod ltmodem2217.o
</verb>
<p>
The "source code" supplied with some PCTel modules (a small C file)
performs similar masquerading
when compiled and linked with the binary libraries in those packages;
unlike the partially-open-source Lucent driver, it
does <em>not</em> compensate for any actual changes to the kernel interface.  
<p>

<p>
<sect1> Patching <tt>tty.h</tt>
<p>
In his quest to get the original, binary-only Lucent LT modem
driver (version 5.68) working with kernels later than 2.2.14, Mark Spieth noticed
that one simple change in the Linux kernel source fixed the major
incompatibilities incurred between the 2.2.14 to 2.2.16 kernel versions.
This patch is no longer necessary when using the partial source/binary
Lucent driver (version 5.78), but it remains useful for those with other
modems whose drivers are compiled against pre-2.2.15 kernels.  
<p>
The patched 2.2.17 <tt>tty.h</tt> and some 2.2.17 kernel packages compiled
with this patch are available from <url url="http://walbran.org/sean/linux/stodolsk/">.  
If you want to do the edit yourself, the line to shift is in the structure
<tt>tty_struct</tt> within <tt>include/linux/tty.h</tt>; it has an extra member 
<tt>poll_wait</tt> in later kernels.
Move this member to the bottom of the structure, so that the remaining offsets
will then be the same as those in versions earlier than 2.2.15, and thus be 
compatible with the precompiled kernel module.  You will need to recompile 
your kernel and modules after making this change to the source.  
<p>

<sect1> Using a <tt>ppp.o</tt> from Kernel 2.2.14
<p>
A trick exists for using the binary modules with kernels later than 2.2.15 which does 
not require kernel recompilation; however, following the discovery
of the <tt>tty.h</tt> patch described above, this trick is no longer necessary nor
recommended.  The trick is to
replace the <tt>/lib/modules/net/ppp.o</tt> module with one from kernel
2.2.14.   Christoph 
Hebeisen (cth(at)sfu.ca) reported that the use of ppp.o version 2.2.14 rather 
than that of version 2.2.16 with the Lucent module provided functionality
under 2.2.16 kernels.    Willie Green (willjr(at)lcc.net) confirmed that this trick works 
also with the ESS module. After simple insertion of a supporting version-matched module:
<verb>
    insmod slhc
</verb>
the mismatched ppp.o from 2.2.14 source is inserted
<verb>
    insmod -f ppp.o 
</verb>
We wish to emphasize that this trick with forced insertion is 
less stable than the easy and more effective change to the kernel source
file <tt>tty.h</tt>, as described above.
<p>

<sect> Specific Chipsets and Their Drivers
<p>

<sect1>IBM Mwave (Thinkpad 600E)
<p>
IBM has a completely open-source (GPL'ed) driver for the software modem
in their Thinkpad 600E's available
<url url="http://oss.software.ibm.com/developer/opensource/linux/projects/mwave/" name="here">.
<p>

<sect1>Lucent LT
<p>
<sect2> Overview
<p>
This modem enjoys the most support under Linux, in that there exist three different
driver packages:
<itemize>
<item>
There exists a manufacturer-unsupported, half-binary/half-open-sourced
kernel module, originally designed for Red Hat 6.2's 2.2.14-5 kernel,
but substantially reworked by Mark Spieth and others to function
with 2.2.x and 2.4.x kernels.  This is driver version 5.78(c,d,e,...), and 
is the driver you are most likely to have success using.
<item>
There exists a manufacturer-unsupported, binary-only
kernel module, compiled under Red Hat 6.0's 2.2.12-20 kernel.
This is driver version 5.68.
<item>
Some open source tools for use with Lucent modems are
available at <url url="http://www.close.u-net.com/ltmodem.html">.
Pavel Machek writes that "It is not too useful,
however: it is a hardware driver, and without a v.34 protocol stack, you
can't connect to your ISP. It is enough to turn your Lucent winmodem
into an answering machine, however." 
</itemize>
It should be noted that the binary-only driver module (from "linux568.zip") 
contains code from the  GPL'ed Linux <tt>serial.c</tt> driver, so, since 
the source code for the
modem driver is not available, trafficking in this driver is apparently
in violation of the GPL.  Distributing the partially open source driver
("i56lvp578.zip") may or may not be technically legal, since the GPL'ed 
code, though not yet linked with the closed-source code, is certainly intended
to be so.  See
<url url="http://kt.linuxcare.com/kernel-traffic/kt20000717_76_print.epl#1" 
name="this Kernel Traffic issue"> 
and a Linux-Kernel mailing list archive for the week including Dec. 3rd, 2000, 
for more details. 
<p>

<sect2> Driver v5.78(c,d,e,...) - Installation
<p>
You should obtain the most recent package for your kernel from 
<url url="http://walbran.org/sean/linux/stodolsk/"> 
and follow the up-to-date instructions given there.
<p>
<sect2> Manufacturer's driver version 5.68 - Installation
<p>
This driver is superseded by version 5.78, described above; however,
it may still be of some use in special cases.
<enum>
  <item> Obtain the package for your kernel:
     <enum>
       <item> 2.2.12 to 2.2.15 <url url="http://linmodems.org/linux568.zip">
       <item> 2.2.15 and above : same URL, but "tty.h" patch is required; see "Tips and Tricks...", above.
     </enum>
  <item> <tt>unzip linux568.zip</tt>
  <item> <tt>su</tt> (enter root password when prompted)
  <item> <tt>./ltinst</tt> (a 'file not found' error will be issued due to a flaw in
the installation script; ignore this error.)
</enum>
Your modem should now be accessible as the device <tt>/dev/modem</tt> or <tt>/dev/ttyS14</tt>.
<p>

<sect2> Open Source Tools - Installation
<p>
See the documentation with the source for instructions.
<p>

<sect1>ESS
<p>
<sect2>Overview
<p>
Binary-only drivers for ES56T-PI (PCI) and ES56V-I (ISA), compiled under RedHat 6.0's kernel
2.2.12-20, are available.  The driver has been used via forced insertion up through kernel 2.2.15,
and up through 2.2.17 using the "tty.h" patch described in the "Tips and Tricks..." section, above.
<p>

<sect2> Installation
<p>
<enum>
  <item> Obtain the package for your modem:
     <itemize>
       <item> ISA: <url url="ftp://ftp.esstech.com/pub/modem/isa/unsupported/56v-i/linux/kernel61/linux111.zip"> or
       <item> PCI: <url url="ftp://ftp.esstech.com/pub/modem/pci/unsupported/56t-pi/linux/Kernel61/111.zip">.
     </itemize>
  <item> For kernel 2.2.15 and later, apply tty.h patch (See "Tips And Tricks...," above); recompile kernel and modules. 
  <item> Unpack the package with: <tt>unzip</tt> <em>package_name</em>
  <item> Change to the root user: <tt>su</tt> (enter root password when prompted)
  <item> Create the device file: <tt>mknod /dev/esscom c 127 1 </tt>
  <item> Make convenience device: <tt>ln -s /dev/esscom /dev/modem</tt>
  <item> Make convenience device: <tt>ln -s /dev/esscom /dev/ttyS15</tt>
  <item> Set device ownership: <tt>chgrp uucp /dev/esscom </tt>
  <item> Set device permissions: <tt>chmod 666 /dev/esscom </tt>
  <item> Masquerade module version (See "Tips And Tricks...," above): <tt>./fixscript essmodem.o essmodem.fix.o</tt>
  <item> Install module file: <tt>cp essmodem.fix.o /lib/modules/`uname -r`/misc/essmodem.o</tt>
  <item> Insert module in kernel: <tt>insmod -f essmodem</tt>
  <item> (Optional) Provide for automatic module loading: add a line "alias char-major-127 essmodem" to  
the file <tt>/etc/modules.conf</tt> or <tt>/etc/conf.modules</tt>
</enum>

<sect1>PCTel
<p>
<sect2> Overview
<p>
Binary drivers can be found at 
<url url="http://www.idir.net/~gromitkc/winmodem.html#drivers">.
<p>
A Debian-style installation package for kernel 2.2.16 was made available
by Corel at
<url url="ftp://ftp.corel.com/pub/linux/CorelLinux/dists/corellinux-1.2/corel/binary-i386/utils/pctel-kernel-2.2.16-driver-cdl-v1.0_1.0.deb">, though this link appears
to now be incorrect.  A gzipped/tarred package derived from the .deb is
available <url url="http://walbran.org/sean/linux/stodolsk/" name="here">.
In addition, a driver for kernel 2.4 was contributed by Thomas Wright, and
is also available <url url="http://walbran.org/sean/linux/stodolsk/" name="here">.
Other packages, requiring the superficial compilation described below, are also
known to exist.
<p>
<sect2> Installation
<p>
There are apparently two types of PCTel module package around.  
<enum>
  <item> A package (rpm or deb) which installs
  two module files, pctel_hsp.o and pctel_pci.o, in <tt>/lib/modules/2.2.16</tt>.
  <p>
  With such a package, if you are running a kernel more recent than 2.2.16, you 
  will need to use forced insertion (insmod -f), and if you are not successful, might
  try the "fixscript" method used with the Lucent 5.68 and ESS modules above - but, note
  that this has not, to my knowledge, been tried out yet.  If you are running a kernel
  older than 2.2.16, you should consider upgrading your kernel, or else try the
  fixscripting as well (this is also not guaranteed to work).  
  Please send me a report if you get these to work.
  <p>
  <item> A package which, when unpacked, gives a set of libraries (hsp.a, etc...)
  and a small C source file (ptmodule.c), which should be in directories like lib/
  and src/module/.  If there are no directories, create them and arrange the files with: 
<verb>
mkdir lib
mkdir src
mkdir src/module
mv *.a lib/
mv Makefile *.c src/module
</verb>
    <p>
    Now go to the directory src/module and type <tt>make</tt>.  This should generate the module
    file <tt>pctel.o</tt>, which will appear back up in the directory <tt>lib</tt>.  
    (The driver module is <em>not</em> the object file <tt>ptmodule.o</tt> in <tt>src/module</tt>!)
    <p>
    The apparent version of the module generated in this way will match your current kernel version.
</enum>
<p>
With the modules in hand, proceed to install as follows:
<p>
<enum>
  <item> Change to the root user: <tt>su</tt> (enter root password when prompted)
  <item> Create the device file: <tt>mknod /dev/pctel c 62 79 </tt>
  <item> Make convenience device: <tt>ln -s /dev/pctel /dev/modem</tt>
  <item> Make convenience device: <tt>ln -s /dev/pctel /dev/ttyS15</tt>
  <item> Set device ownership: <tt>chgrp uucp /dev/pctel </tt>
  <item> Set device permissions: <tt>chmod 666 /dev/pctel </tt>
  <item> Install module file (only for package type 2, above):  <tt>cp pctel.o /lib/modules/`uname -r`/misc/</tt>
  <item> Insert module(s) in kernel with <tt>insmod -f</tt> <em>modulename</em>
</enum>
<p>

<sect1>Conexant/Rockwell HSF
<p>
There exist drivers for kernels 2.2.14, 2.2.16, and 2.2.17 at
<url url="http://www.olitec.com/pci56kv2.html"> 
The page is in French,
but the installation commands are given on the page in boldface red text  
(you can also use the <url url="http://babel.altavista.com/translate.dyn?urltext=http%3A%2F%2Fwww.olitec.com%2Fpci56kv2.html&#38;lp=fr_en" name="babel fish">).
Essentially, download the appropriate package, unpack it with <tt>tar -zxvf</tt>,
and run the installation script <tt>ins_all</tt>.  
<p>
This driver is a bit finicky (with the most common symptom of failure being
the "NO DIALTONE" response), but a number of people have been able to get
it to work, usually by inserting their modem's vendor ID in the modem's
.inf file, perhaps along with a change of the device major number from 254 to 253.  
See the Linmodems.org mailing list archives for details; one example of many is given
<url url="http://linmodems.org/cgi-bin/ezmlm-cgi?1:mss:2765:200102:oonhggjbpkiielnoodfa" name="here">.

<p>
<sect1> Intel (formerly Ambient Technology, formerly Cirrus Logic)
<p>
Mikhail Moreyra has written a GPL'ed driver for the CL-MD5620DT chipset
which can do up to 33.6 kbps; however, this is alpha software
and should be treated with due care.  The driver can be obtained at
<url url="http://linmodems.org/CLModem-0.3.0.tar.gz">. 
Gabriel Gambetta (ggambett(at)internet.com.uy) issued a patched
version of the driver to allow standard AT modem commands;
you can get this version at Rob Clark's site
<url url="http://www.idir.net/~gromitkc/clm/CLModem-0.3.0+gg.tar.gz" name="here">. 
<p>
A driver for the HaM modem was beta-tested in early 2001 and is
expected to be released quite soon.
<p>

<sect1>3Com
<p>
<sect2> 56k
<p>
An rpm package with a driver for the 3Com MDP3900V-U modem 
(apparently found in the Dell Dimension L733r) was 
posted to the Linmodems.org mailing list
(<url url="http://linmodems.org/cgi-bin/ezmlm-cgi?1:mss:2942:200102:lminaknocblpmkfcnobi" name="click here"> for more information), and is mirrored
<url url="http://walbran.org/sean/linux/stodolsk/" name="here">.
<p>
<sect2> Mini-PCI
<p>
  A request for comments was posted by a 3Com official
about the possible demand for a binary-only driver for their miniPCI combination
NIC/winmodem <url url="http://linmodems.org/cgi-bin/ezmlm-cgi?1:msp:1229:cilpipdmolabpbbbibgd"
name="here"> on the Linodems.org mailing list; please respond to the address
given, linmodem@new-n-used.com, and not to the mailing list.
Though to my knowledge no driver has yet been
released, Werner Heuser's <url url="http://mobilix.org/minipci_linux.html" name="miniPCI page"> has more information and links.
<p>

<sect1>AMR
<p>
Ian Stewart 
<url url="http://linmodems.org/cgi-bin/ezmlm-cgi?1:mss:2768:200102:edbonibpdjfpnfhbmhel" name="reports">
that he is working on a "mid-level driver" for the AC97 codec.
<p>
<!--
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 -->
<sect>Troubleshooting
<p>
So you've read through this document, the 
<url url="http://www.linuxdoc.org/HOWTO/Modem-HOWTO.html" name="Modem-HOWTO">,
and the
<url url="http://www.linuxdoc.org/HOWTO/PPP-HOWTO/index.html" name="PPP Howto">,
are pretty sure that your modem matches one of the drivers available,
but it still doesn't work?  There are a number of points in
the process at which something could break down.  
<p>
Linux generally maintains records of networking connections which are
very useful in troubleshooting problems.  Their particular filenames
vary with both the Linux distribution and Dial-in software,
but
the system log files <tt>/var/log/messages</tt>, <tt>/var/log/syslog</tt>,
etcetera, should provide at least some information.
<p>
For both
your own trouble shooting and queries for help to a list, it will be
useful if you accumulate the information requested below. As root, 
change to the directory in which the modem
install scripts are located, and 
start a
script record as shown below.  After this script is terminated
with "exit," copy it out of your Linux partition for transmission to the
list which may aid you. 
<p>
(Below, # are explanatory comments.)
<verb>
# start the recording,
script ModemTest.txt 
# type in as much info on your Modem card as you have
echo winmodem name, manufacturer, designation, and chip if possible
# this gives your current kernel version
uname -r
# this gives information on your serial ports
setserial -agv /dev/ttyS*
# this information on your interrupts (irq)
cat /proc/interrupts
# show the contents of your module installation script (insert script name):
cat ScriptName
# Check if your script is executable:
ls -l ScriptName
# a response is OK if it has "x" such as below:
# -rwxrw-rw-  1 root     root  654 Jan  6  2000 ltinst
# otherwise make it executable with:
chmod o+x ScriptName
# verify with
ls -l ScriptName
# if ScriptName has not been successfully run before under this kernel
# run it with:
./ScriptName
# what is the symbolic link /dev/modem set to:
ls -l /dev/modem
# What is the DeviceName specified in the ScriptName (/dev/ttyS14 or ...?)
echo DeviceName
# what is your modem driver name? Something like DriverName.o
# with the ".o" indicating it is a compiled binary
echo This is my DriverName.o
# if should have been inserted in the Modules Path
# Try to display it there with:
find /lib/modules | grep DriverName
# Is DriverName among the modules installed in the running kernel?
lsmod
# if not try a simple insertion:
insmod ./DriverName.o
# or if it was in the Modules Path, the following will suffice:
insmod DriverName
# check for insertion:
lsmod
# if not inserted, try forcing:
insmod -f ./DriverName
# list your inserted modules again.
lsmod
# If DriverName is NOT listed, 
# their is an incompatibility between modem hardware, driver and kernel.
# Further effort will be of No use.
# If DriverName is listed, let's do a bit more information.
# You may first wish to rerun the configuration utility 
# used to setup dial-in connections for your Linux installation.
# Remember to edit your PassWord from this record later.
# You will probably be queried for the following information 
# which you should have ready:
#Port to be used (/dev/modem or /dev/ttySn),Dial-inNumber, UserName, PassWord. 
# Run your configuration utility.
YourSetUpConf
# To stop recording 
exit
</verb>
<p>
If dialin was not successfull, append to this a record from your log file.
As an example, a section of a /var/log/syslog from a Debian
Linux system is below. 

<!--
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 -->
<sect>FAQ
<p>
<sect1>I have a winmodem.  Will it work under Linux?
<p>
Probably not.  Please see the section "Which Linmodem hardware is supported?" above,
and check the Linux Modem Compatibility
<url url="http://www.idir.net/~gromitkc/winmodem.html#Database" name="database">
at
<url url="http://www.idir.net/~gromitkc/winmodem.html" name="Rob Clark's site">.
<p>
<sect1> I get "NO DIALTONE".
<p>
Try setting your BIOS option from "PNP OS" to "non-PNP OS",  from "Windows"
to "Other OS", or the equivalent.
<p>
Conexant users: See the Conexant section, above.
<p>
<sect1> I get a "device or resource busy" error.
<p>
<itemize>
<item> If you have an ISA modem, did you use the isapnptools to allocate IRQ and DMA
resources to the card?  See "ISA Plug-n-Play", above, for more information.
<item> Double-check that you created the device file correctly,
and try to eliminate any IRQ conflicts you might have.  If all looks well, but
it still doesn't work, check the <url url="http://Linmodems.org" name="Linmodems.org">
 mailing list to see if someone
else has (and has perhaps fixed) the same problem, or try to fix it yourself
and inform others of your results.
</itemize>
<p>
<sect1> I get unresolved symbols when fixscripting/insmoding.
<p>
Unresolved symbols are a true danger of version mismatching and are, 
in general, bad, but are also almost inevitable with binary modules.
If the fixscript reports unresolved symbols, or the module does not
work despite the unresolved symbols, you may be out of luck with
that kernel/module combination; however,
a few common cases involve symbols like:
<itemize>
<item> <tt>slhc_xxxx</tt>:  You probably need to insmod the slhc 
module before inserting the modem/ppp modules; using modprobe
rather than insmod should also obviate this problem.
<item> <tt>printk, jiffies</tt>:  Your kernel may be compiled with
SMP enabled.  None of the binary modules are known to be SMP-safe, and will
probably only work on a single-processor machine with a single-processor
kernel, i.e. SMP disabled.  You should try recompiling your kernel or
otherwise obtaining a version with SMP disabled.  (Thanks to
Tom Reinertson (treinertson(at)uswest.net)) 
<item> <tt>tty_xxxx</tt> with esscom.o: 
Earlier fixscripts were not able to handle the version-specific symbols
in this module.  More recent versions are available at
<url url="http://www.test.dclabs.com.au/linmodem/fixscript">) 
which should be able to fix this module as well. 
</itemize>
If a module works in an unstable fashion,
it could be that, under some circumstances, you are avoiding those
symbols, while in others, you slam up against them.  Try out different
ppp dialup programs (wvdial, kppp), which call a different set of functions
under similar conditions.  It is also possible that the fixscript, which
was designed for the lucent module, is not "fixing" the symbols used
in your module.  If you find no combination that works, consider "downgrading"
to a kernel which has a closer version match to that of the module.
<p>
<sect1> My PCTel modem doesn't work.
<p>
<itemize>
<item> Do you need to give the module a country code parameter?  See the appendix.
<item> Are you using the right driver module?  There are a few PCTel drivers
around (see the section "Which Linmodem hardware is supported?" above).
You might try one of the others and see if that helps.
</itemize>
<p>
<sect1> The modem dials and connects fine, but then it drops the connection.
<p>
This is an often-reported problem that may have a few, or no, solutions:
<enum>
<item>It is possible that the module is installed correctly and is working,
but that you have a problem with your ppp configuration.
In particular, if you find an error in the log along the lines 
of "peer is not authorized," try changing "auth" to "noauth"
in  /etc/ppp/options, and/or commenting out "auth" and "lock" (by
placing a '#' at the beginning of the line).  Corel has a FAQ entry at 
<url url="http://linux.corel.com/support/html/9314.htm"> about
this.
<item>
It has been reported that, with some kernel/module mismatches, a program
like <tt>kppp</tt> will give this error, while an alternative like <tt>wvdial</tt>
does not, for the same modules and hardware.  You may wish to try a different
ppp dialer and see if that helps. 
<item>
Lastly, there is the potential relationship with sound support.
Comparing functionality of ltmodem.o with/without sound
support in the kernels, dial-in is OK, but ppp is NOT achieved for the kernel
without sound support.  
<p>
Most Linux distributions do deposit a kernel configuration file along
with the kernel.  For Debian related distributions, it is the file   
<verb>
  /boot/config-version
</verb>
The positive choices can be quickly displayed with:
<verb>
  grep SOUND /boot/config-version |grep -v not
</verb>
For the specific example of a 2.2.17 version:
<p>
<verb>
# grep SOUND  /boot/config-2.2.17 |grep -v not
CONFIG_SOUND=m
CONFIG_SOUND_OSS=m
CONFIG_SOUND_SB=m
CONFIG_SOUND_MPU401=m
CONFIG_SOUND_YM3812=m
CONFIG_SOUND_VMIDI=m
CONFIG_SOUND_YMPCI=m
CONFIG_LOWLEVEL_SOUND=y
</verb>
<p>
Either CONFIG_SOUND=m or CONFIG_SOUND=yes would show that the kernel
has sound support (as would simple sound output).
<p>
If none of these helps, you may wish to consider trying to use a kernel version which
is closer to the module.  Otherwise, try the mailing list at 
<url url="http://Linmodems.org" name="Linmodems.org"> for help.
</enum>
<p>
<sect1> I get a kernel panic on closing the connection or unloading the driver.
<p>
There are a couple of possible solutions to this, neither of which may work:
<itemize>
<item> Try a different ppp dialer (wvdial, kppp).
<item> Configure the module so that it stays in the kernel, i.e. so that it
is not unloaded.
</itemize>
<p>
<sect1> Nothing seems to work.  To whom can I turn for help?
<p>
<itemize>
<item> Double-check that the modem you have is actually supported by
the module you have.  See "Which Linmodem Hardware Is Supported?" above.
<item> Try to determine at which stage of the installation process
things break down.  Check the man pages on the commands used in that
stage and see if you can determine the source of the problem.
</itemize>
<p>
If all seems lost, please see the section "Troubleshooting", below , and consider sending
a message with the complete information described there to the
mailing list at <url url="http://linmodems.org" name="Linmodems.org">.
<p>
<sect1> Who wrote the driver for my winmodem, and how do I contact him/her?
<p>
If a contact address is not given above, you can in general assume
that it was probably somebody on contract to the manufacturer, who probably
does not have the
authority the update/release/change the source code, and who probably doesn't
have time to reply to your email in any case.  See, for example,
<url url="http://lwn.net/1999/1209/a/lucent.html">
<p>
<!--
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 -->
<sect> Appendix
<p>

<p>
<sect1> PCTel Module Parameters:  Country Code
<p>
The following is quoted from one of the PCTel readme files.
Thus you can choose the appropriate country code by inserting
the module with a parameter as: 
<verb>
insmod pctel.o country_code=7
</verb>
(the "7" being replaced by your country code from the list below).  
Thanks to Jonathan Emery for pointing out the correct syntax.
<p>
<verb>
Set and report country code.

This driver takes a module parameter to setup the correct country code
setting for various country's telephone networks and it also can report
back the country code been set.

Here are the two versions for country_code selection and reporting:

VERSION #1:

To set country code:
"country_sel_rep   sel   7" will sets the country code to 7.

To query the driver for the currently set country code:
"country_sel_rep   rep" returns the current country code as the exit code.

VERSION #2:

To set country code: 
"country_sel   7" to set the country code to 7.

To query the driver for the currently set country code:
"country_rep" return the current country code as the exit code.

country_code                    country_name

    1             	        USA
    2		                FRANCE
    3				GERMANY
    4				ITALY
    5				SWEDEN
    6				UK
    7				JAPAN
    8				AUSTRALIA
    9				SPAIN
   10				TAIWAN
   11				SINGAPORE
   12				KOREA
   13				SWITZERLAND
   14				NORWAY
   15				NETHERLANDS
   16				BELGIUM
   17				CANADA
   18				IRELAND
   19				PORTUGAL
   20				POLAND
   21				HUNGARY
   22				FINLAND
   23				DENMARK
   24				AUSTRIA
   25				S.AFRICA
   26				CTR21 COUNTRIES
   27				CHINA
   28				MALAYSIA
   29				LUXUMBURG
   30				GREECE
   31				ICELAND
   32				NEW ZEALAND
   33				BRAZIL
</verb>
<p>
</article>

