Documentation/networking/device_drivers/cable/sb1000.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===================
   4 SB100 device driver
   5 ===================
   6
   7 sb1000 is a module network device driver for the General Instrument (also known
   8 as NextLevel) SURFboard1000 internal cable modem board.  This is an ISA card
   9 which is used by a number of cable TV companies to provide cable modem access.
  10 It's a one-way downstream-only cable modem, meaning that your upstream net link
  11 is provided by your regular phone modem.
  12
  13 This driver was written by Franco Venturi <fventuri@mediaone.net>.  He deserves
  14 a great deal of thanks for this wonderful piece of code!
  15
  16 Needed tools
  17 ============
  18
  19 Support for this device is now a part of the standard Linux kernel.  The
  20 driver source code file is drivers/net/sb1000.c.  In addition to this
  21 you will need:
  22
  23 1. The "cmconfig" program.  This is a utility which supplements "ifconfig"
  24    to configure the cable modem and network interface (usually called "cm0");
  25
  26 2. Several PPP scripts which live in /etc/ppp to make connecting via your
  27    cable modem easy.
  28
  29    These utilities can be obtained from:
  30
  31       http://www.jacksonville.net/~fventuri/
  32
  33    in Franco's original source code distribution .tar.gz file.  Support for
  34    the sb1000 driver can be found at:
  35
  36       - http://web.archive.org/web/%2E/http://home.adelphia.net/~siglercm/sb1000.html
  37       - http://web.archive.org/web/%2E/http://linuxpower.cx/~cable/
  38
  39    along with these utilities.
  40
  41 3. The standard isapnp tools.  These are necessary to configure your SB1000
  42    card at boot time (or afterwards by hand) since it's a PnP card.
  43
  44    If you don't have these installed as a standard part of your Linux
  45    distribution, you can find them at:
  46
  47       http://www.roestock.demon.co.uk/isapnptools/
  48
  49    or check your Linux distribution binary CD or their web site.  For help with
  50    isapnp, pnpdump, or /etc/isapnp.conf, go to:
  51
  52       http://www.roestock.demon.co.uk/isapnptools/isapnpfaq.html
  53
  54 Using the driver
  55 ================
  56
  57 To make the SB1000 card work, follow these steps:
  58
  59 1. Run ``make config``, or ``make menuconfig``, or ``make xconfig``, whichever
  60    you prefer, in the top kernel tree directory to set up your kernel
  61    configuration.  Make sure to say "Y" to "Prompt for development drivers"
  62    and to say "M" to the sb1000 driver.  Also say "Y" or "M" to all the standard
  63    networking questions to get TCP/IP and PPP networking support.
  64
  65 2. **BEFORE** you build the kernel, edit drivers/net/sb1000.c.  Make sure
  66    to redefine the value of READ_DATA_PORT to match the I/O address used
  67    by isapnp to access your PnP cards.  This is the value of READPORT in
  68    /etc/isapnp.conf or given by the output of pnpdump.
  69
  70 3. Build and install the kernel and modules as usual.
  71
  72 4. Boot your new kernel following the usual procedures.
  73
  74 5. Set up to configure the new SB1000 PnP card by capturing the output
  75    of "pnpdump" to a file and editing this file to set the correct I/O ports,
  76    IRQ, and DMA settings for all your PnP cards.  Make sure none of the settings
  77    conflict with one another.  Then test this configuration by running the
  78    "isapnp" command with your new config file as the input.  Check for
  79    errors and fix as necessary.  (As an aside, I use I/O ports 0x110 and
  80    0x310 and IRQ 11 for my SB1000 card and these work well for me.  YMMV.)
  81    Then save the finished config file as /etc/isapnp.conf for proper
  82    configuration on subsequent reboots.
  83
  84 6. Download the original file sb1000-1.1.2.tar.gz from Franco's site or one of
  85    the others referenced above.  As root, unpack it into a temporary directory
  86    and do a ``make cmconfig`` and then ``install -c cmconfig /usr/local/sbin``.
  87    Don't do ``make install`` because it expects to find all the utilities built
  88    and ready for installation, not just cmconfig.
  89
  90 7. As root, copy all the files under the ppp/ subdirectory in Franco's
  91    tar file into /etc/ppp, being careful not to overwrite any files that are
  92    already in there.  Then modify ppp@gi-on to set the correct login name,
  93    phone number, and frequency for the cable modem.  Also edit pap-secrets
  94    to specify your login name and password and any site-specific information
  95    you need.
  96
  97 8. Be sure to modify /etc/ppp/firewall to use ipchains instead of
  98    the older ipfwadm commands from the 2.0.x kernels.  There's a neat utility to
  99    convert ipfwadm commands to ipchains commands:
 100
 101         http://users.dhp.com/~whisper/ipfwadm2ipchains/
 102
 103    You may also wish to modify the firewall script to implement a different
 104    firewalling scheme.
 105
 106 9. Start the PPP connection via the script /etc/ppp/ppp@gi-on.  You must be
 107    root to do this.  It's better to use a utility like sudo to execute
 108    frequently used commands like this with root permissions if possible.  If you
 109    connect successfully the cable modem interface will come up and you'll see a
 110    driver message like this at the console::
 111
 112          cm0: sb1000 at (0x110,0x310), csn 1, S/N 0x2a0d16d8, IRQ 11.
 113          sb1000.c:v1.1.2 6/01/98 (fventuri@mediaone.net)
 114
 115    The "ifconfig" command should show two new interfaces, ppp0 and cm0.
 116
 117    The command "cmconfig cm0" will give you information about the cable modem
 118    interface.
 119
 120 10. Try pinging a site via ``ping -c 5 www.yahoo.com``, for example.  You should
 121     see packets received.
 122
 123 11. If you can't get site names (like www.yahoo.com) to resolve into
 124     IP addresses (like 204.71.200.67), be sure your /etc/resolv.conf file
 125     has no syntax errors and has the right nameserver IP addresses in it.
 126     If this doesn't help, try something like ``ping -c 5 204.71.200.67`` to
 127     see if the networking is running but the DNS resolution is where the
 128     problem lies.
 129
 130 12. If you still have problems, go to the support web sites mentioned above
 131     and read the information and documentation there.
 132
 133 Common problems
 134 ===============
 135
 136 1. Packets go out on the ppp0 interface but don't come back on the cm0
 137    interface.  It looks like I'm connected but I can't even ping any
 138    numerical IP addresses.  (This happens predominantly on Debian systems due
 139    to a default boot-time configuration script.)
 140
 141 Solution
 142    As root ``echo 0 > /proc/sys/net/ipv4/conf/cm0/rp_filter`` so it
 143    can share the same IP address as the ppp0 interface.  Note that this
 144    command should probably be added to the /etc/ppp/cablemodem script
 145    *right*between* the "/sbin/ifconfig" and "/sbin/cmconfig" commands.
 146    You may need to do this to /proc/sys/net/ipv4/conf/ppp0/rp_filter as well.
 147    If you do this to /proc/sys/net/ipv4/conf/default/rp_filter on each reboot
 148    (in rc.local or some such) then any interfaces can share the same IP
 149    addresses.
 150
 151 2. I get "unresolved symbol" error messages on executing ``insmod sb1000.o``.
 152
 153 Solution
 154    You probably have a non-matching kernel source tree and
 155    /usr/include/linux and /usr/include/asm header files.  Make sure you
 156    install the correct versions of the header files in these two directories.
 157    Then rebuild and reinstall the kernel.
 158
 159 3. When isapnp runs it reports an error, and my SB1000 card isn't working.
 160
 161 Solution
 162    There's a problem with later versions of isapnp using the "(CHECK)"
 163    option in the lines that allocate the two I/O addresses for the SB1000 card.
 164    This first popped up on RH 6.0.  Delete "(CHECK)" for the SB1000 I/O addresses.
 165    Make sure they don't conflict with any other pieces of hardware first!  Then
 166    rerun isapnp and go from there.
 167
 168 4. I can't execute the /etc/ppp/ppp@gi-on file.
 169
 170 Solution
 171    As root do ``chmod ug+x /etc/ppp/ppp@gi-on``.
 172
 173 5. The firewall script isn't working (with 2.2.x and higher kernels).
 174
 175 Solution
 176    Use the ipfwadm2ipchains script referenced above to convert the
 177    /etc/ppp/firewall script from the deprecated ipfwadm commands to ipchains.
 178
 179 6. I'm getting *tons* of firewall deny messages in the /var/kern.log,
 180    /var/messages, and/or /var/syslog files, and they're filling up my /var
 181    partition!!!
 182
 183 Solution
 184    First, tell your ISP that you're receiving DoS (Denial of Service)
 185    and/or portscanning (UDP connection attempts) attacks!  Look over the deny
 186    messages to figure out what the attack is and where it's coming from.  Next,
 187    edit /etc/ppp/cablemodem and make sure the ",nobroadcast" option is turned on
 188    to the "cmconfig" command (uncomment that line).  If you're not receiving these
 189    denied packets on your broadcast interface (IP address xxx.yyy.zzz.255
 190    typically), then someone is attacking your machine in particular.  Be careful
 191    out there....
 192
 193 7. Everything seems to work fine but my computer locks up after a while
 194    (and typically during a lengthy download through the cable modem)!
 195
 196 Solution
 197    You may need to add a short delay in the driver to 'slow down' the
 198    SURFboard because your PC might not be able to keep up with the transfer rate
 199    of the SB1000. To do this, it's probably best to download Franco's
 200    sb1000-1.1.2.tar.gz archive and build and install sb1000.o manually.  You'll
 201    want to edit the 'Makefile' and look for the 'SB1000_DELAY'
 202    define.  Uncomment those 'CFLAGS' lines (and comment out the default ones)
 203    and try setting the delay to something like 60 microseconds with:
 204    '-DSB1000_DELAY=60'.  Then do ``make`` and as root ``make install`` and try
 205    it out.  If it still doesn't work or you like playing with the driver, you may
 206    try other numbers.  Remember though that the higher the delay, the slower the
 207    driver (which slows down the rest of the PC too when it is actively
 208    used). Thanks to Ed Daiga for this tip!
 209
 210 Credits
 211 =======
 212
 213 This README came from Franco Venturi's original README file which is
 214 still supplied with his driver .tar.gz archive.  I and all other sb1000 users
 215 owe Franco a tremendous "Thank you!"  Additional thanks goes to Carl Patten
 216 and Ralph Bonnell who are now managing the Linux SB1000 web site, and to
 217 the SB1000 users who reported and helped debug the common problems listed
 218 above.
 219
 220
 221                                         Clemmitt Sigler
 222                                         csigler@vt.edu