Intel(R) PRO/Wireless 2100 Driver for Linux in support of:

Intel(R) PRO/Wireless 2100 Network Connection

Copyright (C) 2003-2006, Intel Corporation

README.ipw2100

Version: git-1.1.5
Date   : January 25, 2006

Index
-----------------------------------------------
0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER
1. Introduction
2. Release git-1.1.5 Current Features
3. Command Line Parameters
4. Sysfs Helper Files
5. Radio Kill Switch
6. Dynamic Firmware
7. Power Management
8. Support
9. License


0.   IMPORTANT INFORMATION BEFORE USING THIS DRIVER
-----------------------------------------------

Important Notice FOR ALL USERS OR DISTRIBUTORS!!!!

Intel wireless LAN adapters are engineered, manufactured, tested, and
quality checked to ensure that they meet all necessary local and
governmental regulatory agency requirements for the regions that they
are designated and/or marked to ship into. Since wireless LANs are
generally unlicensed devices that share spectrum with radars,
satellites, and other licensed and unlicensed devices, it is sometimes
necessary to dynamically detect, avoid, and limit usage to avoid
interference with these devices. In many instances Intel is required to
provide test data to prove regional and local compliance to regional and
governmental regulations before certification or approval to use the
product is granted. Intel's wireless LAN's EEPROM, firmware, and
software driver are designed to carefully control parameters that affect
radio operation and to ensure electromagnetic compliance (EMC). These
parameters include, without limitation, RF power, spectrum usage,
channel scanning, and human exposure.

For these reasons Intel cannot permit any manipulation by third parties
of the software provided in binary format with the wireless WLAN
adapters (e.g., the EEPROM and firmware). Furthermore, if you use any
patches, utilities, or code with the Intel wireless LAN adapters that
have been manipulated by an unauthorized party (i.e., patches,
utilities, or code (including open source code modifications) which have
not been validated by Intel), (i) you will be solely responsible for
ensuring the regulatory compliance of the products, (ii) Intel will bear
no liability, under any theory of liability for any issues associated
with the modified products, including without limitation, claims under
the warranty and/or issues arising from regulatory non-compliance, and
(iii) Intel will not provide or be required to assist in providing
support to any third parties for such modified products.

Note: Many regulatory agencies consider Wireless LAN adapters to be
modules, and accordingly, condition system-level regulatory approval
upon receipt and review of test data documenting that the antennas and
system configuration do not cause the EMC and radio operation to be
non-compliant.

The drivers available for download from SourceForge are provided as a
part of a development project.  Conformance to local regulatory
requirements is the responsibility of the individual developer.  As
such, if you are interested in deploying or shipping a driver as part of
solution intended to be used for purposes other than development, please
obtain a tested driver from Intel Customer Support at:

http://www.intel.com/support/wireless/sb/CS-006408.htm

1. Introduction
-----------------------------------------------

This document provides a brief overview of the features supported by the
IPW2100 driver project.  The main project website, where the latest
development version of the driver can be found, is:

	http://ipw2100.sourceforge.net

There you can find the not only the latest releases, but also information about
potential fixes and patches, as well as links to the development mailing list
for the driver project.


2. Release git-1.1.5 Current Supported Features
-----------------------------------------------
- Managed (BSS) and Ad-Hoc (IBSS)
- WEP (shared key and open)
- Wireless Tools support
- 802.1x (tested with XSupplicant 1.0.1)

Enabled (but not supported) features:
- Monitor/RFMon mode
- WPA/WPA2

The distinction between officially supported and enabled is a reflection
on the amount of validation and interoperability testing that has been
performed on a given feature.


3. Command Line Parameters
-----------------------------------------------

If the driver is built as a module, the following optional parameters are used
by entering them on the command line with the modprobe command using this
syntax:

	modprobe ipw2100 [<option>=<VAL1><,VAL2>...]

For example, to disable the radio on driver loading, enter:

	modprobe ipw2100 disable=1

The ipw2100 driver supports the following module parameters:

Name		Value		Example:
debug		0x0-0xffffffff	debug=1024
mode		0,1,2		mode=1   /* AdHoc */
channel		int		channel=3 /* Only valid in AdHoc or Monitor */
associate	boolean		associate=0 /* Do NOT auto associate */
disable		boolean		disable=1 /* Do not power the HW */


4. Sysfs Helper Files
---------------------------
-----------------------------------------------

There are several ways to control the behavior of the driver.  Many of the
general capabilities are exposed through the Wireless Tools (iwconfig).  There
are a few capabilities that are exposed through entries in the Linux Sysfs.


----- Driver Level ------
For the driver level files, look in /sys/bus/pci/drivers/ipw2100/

  debug_level

	This controls the same global as the 'debug' module parameter.  For
        information on the various debugging levels available, run the 'dvals'
	script found in the driver source directory.

	NOTE:  'debug_level' is only enabled if CONFIG_IPW2100_DEBUG is turn
	       on.

----- Device Level ------
For the device level files look in

	/sys/bus/pci/drivers/ipw2100/{PCI-ID}/

For example:
	/sys/bus/pci/drivers/ipw2100/0000:02:01.0

For the device level files, see /sys/bus/pci/drivers/ipw2100:

  rf_kill
	read -
	0 = RF kill not enabled (radio on)
	1 = SW based RF kill active (radio off)
	2 = HW based RF kill active (radio off)
	3 = Both HW and SW RF kill active (radio off)
	write -
	0 = If SW based RF kill active, turn the radio back on
	1 = If radio is on, activate SW based RF kill

	NOTE: If you enable the SW based RF kill and then toggle the HW
  	based RF kill from ON -> OFF -> ON, the radio will NOT come back on


5. Radio Kill Switch
-----------------------------------------------
Most laptops provide the ability for the user to physically disable the radio.
Some vendors have implemented this as a physical switch that requires no
software to turn the radio off and on.  On other laptops, however, the switch
is controlled through a button being pressed and a software driver then making
calls to turn the radio off and on.  This is referred to as a "software based
RF kill switch"

See the Sysfs helper file 'rf_kill' for determining the state of the RF switch
on your system.


6. Dynamic Firmware
-----------------------------------------------
As the firmware is licensed under a restricted use license, it can not be
included within the kernel sources.  To enable the IPW2100 you will need a
firmware image to load into the wireless NIC's processors.

You can obtain these images from <http://ipw2100.sf.net/firmware.php>.

See INSTALL for instructions on installing the firmware.


7. Power Management
-----------------------------------------------
The IPW2100 supports the configuration of the Power Save Protocol
through a private wireless extension interface.  The IPW2100 supports
the following different modes:

	off	No power management.  Radio is always on.
	on	Automatic power management
	1-5	Different levels of power management.  The higher the
		number the greater the power savings, but with an impact to
		packet latencies.

Power management works by powering down the radio after a certain
interval of time has passed where no packets are passed through the
radio.  Once powered down, the radio remains in that state for a given
period of time.  For higher power savings, the interval between last
packet processed to sleep is shorter and the sleep period is longer.

When the radio is asleep, the access point sending data to the station
must buffer packets at the AP until the station wakes up and requests
any buffered packets.  If you have an AP that does not correctly support
the PSP protocol you may experience packet loss or very poor performance
while power management is enabled.  If this is the case, you will need
to try and find a firmware update for your AP, or disable power
management (via `iwconfig eth1 power off`)

To configure the power level on the IPW2100 you use a combination of
iwconfig and iwpriv.  iwconfig is used to turn power management on, off,
and set it to auto.

	iwconfig eth1 power off    Disables radio power down
	iwconfig eth1 power on     Enables radio power management to
				   last set level (defaults to AUTO)
	iwpriv eth1 set_power 0    Sets power level to AUTO and enables
				   power management if not previously
				   enabled.
	iwpriv eth1 set_power 1-5  Set the power level as specified,
				   enabling power management if not
				   previously enabled.

You can view the current power level setting via:

	iwpriv eth1 get_power

It will return the current period or timeout that is configured as a string
in the form of xxxx/yyyy (z) where xxxx is the timeout interval (amount of
time after packet processing), yyyy is the period to sleep (amount of time to
wait before powering the radio and querying the access point for buffered
packets), and z is the 'power level'.  If power management is turned off the
xxxx/yyyy will be replaced with 'off' -- the level reported will be the active
level if `iwconfig eth1 power on` is invoked.


8. Support
-----------------------------------------------

For general development information and support,
go to:

    http://ipw2100.sf.net/

The ipw2100 1.1.0 driver and firmware can be downloaded from:

    http://support.intel.com

For installation support on the ipw2100 1.1.0 driver on Linux kernels
2.6.8 or greater, email support is available from:

    http://supportmail.intel.com

9. License
-----------------------------------------------

  Copyright(c) 2003 - 2006 Intel Corporation. All rights reserved.

  This program is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License (version 2) as
  published by the Free Software Foundation.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  more details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 59
  Temple Place - Suite 330, Boston, MA  02111-1307, USA.

  The full GNU General Public License is included in this distribution in the
  file called LICENSE.

  License Contact Information:
  James P. Ketrenos <ipw2100-admin@linux.intel.com>
  Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497

Intel(R) PRO/Wireless 2915ABG Driver for Linux in support of:

Intel(R) PRO/Wireless 2200BG Network Connection
Intel(R) PRO/Wireless 2915ABG Network Connection

Note: The Intel(R) PRO/Wireless 2915ABG Driver for Linux and Intel(R)
PRO/Wireless 2200BG Driver for Linux is a unified driver that works on
both hardware adapters listed above. In this document the Intel(R)
PRO/Wireless 2915ABG Driver for Linux will be used to reference the
unified driver.

Copyright (C) 2004-2006, Intel Corporation

README.ipw2200

Version: 1.1.2
Date   : March 30, 2006


Index
-----------------------------------------------
0.   IMPORTANT INFORMATION BEFORE USING THIS DRIVER
1.   Introduction
1.1. Overview of features
1.2. Module parameters
1.3. Wireless Extension Private Methods
1.4. Sysfs Helper Files
1.5. Supported channels
2.   Ad-Hoc Networking
3.   Interacting with Wireless Tools
3.1. iwconfig mode
3.2. iwconfig sens
4.   About the Version Numbers
5.   Firmware installation
6.   Support
7.   License


0.   IMPORTANT INFORMATION BEFORE USING THIS DRIVER
-----------------------------------------------

Important Notice FOR ALL USERS OR DISTRIBUTORS!!!!

Intel wireless LAN adapters are engineered, manufactured, tested, and
quality checked to ensure that they meet all necessary local and
governmental regulatory agency requirements for the regions that they
are designated and/or marked to ship into. Since wireless LANs are
generally unlicensed devices that share spectrum with radars,
satellites, and other licensed and unlicensed devices, it is sometimes
necessary to dynamically detect, avoid, and limit usage to avoid
interference with these devices. In many instances Intel is required to
provide test data to prove regional and local compliance to regional and
governmental regulations before certification or approval to use the
product is granted. Intel's wireless LAN's EEPROM, firmware, and
software driver are designed to carefully control parameters that affect
radio operation and to ensure electromagnetic compliance (EMC). These
parameters include, without limitation, RF power, spectrum usage,
channel scanning, and human exposure.

For these reasons Intel cannot permit any manipulation by third parties
of the software provided in binary format with the wireless WLAN
adapters (e.g., the EEPROM and firmware). Furthermore, if you use any
patches, utilities, or code with the Intel wireless LAN adapters that
have been manipulated by an unauthorized party (i.e., patches,
utilities, or code (including open source code modifications) which have
not been validated by Intel), (i) you will be solely responsible for
ensuring the regulatory compliance of the products, (ii) Intel will bear
no liability, under any theory of liability for any issues associated
with the modified products, including without limitation, claims under
the warranty and/or issues arising from regulatory non-compliance, and
(iii) Intel will not provide or be required to assist in providing
support to any third parties for such modified products.

Note: Many regulatory agencies consider Wireless LAN adapters to be
modules, and accordingly, condition system-level regulatory approval
upon receipt and review of test data documenting that the antennas and
system configuration do not cause the EMC and radio operation to be
non-compliant.

The drivers available for download from SourceForge are provided as a
part of a development project.  Conformance to local regulatory
requirements is the responsibility of the individual developer.  As
such, if you are interested in deploying or shipping a driver as part of
solution intended to be used for purposes other than development, please
obtain a tested driver from Intel Customer Support at:

http://support.intel.com


1.   Introduction
-----------------------------------------------
The following sections attempt to provide a brief introduction to using
the Intel(R) PRO/Wireless 2915ABG Driver for Linux.

This document is not meant to be a comprehensive manual on
understanding or using wireless technologies, but should be sufficient
to get you moving without wires on Linux.

For information on building and installing the driver, see the INSTALL
file.


1.1. Overview of Features
-----------------------------------------------
The current release (1.1.2) supports the following features:

+ BSS mode (Infrastructure, Managed)
+ IBSS mode (Ad-Hoc)
+ WEP (OPEN and SHARED KEY mode)
+ 802.1x EAP via wpa_supplicant and xsupplicant
+ Wireless Extension support
+ Full B and G rate support (2200 and 2915)
+ Full A rate support (2915 only)
+ Transmit power control
+ S state support (ACPI suspend/resume)

The following features are currently enabled, but not officially
supported:

+ WPA
+ long/short preamble support
+ Monitor mode (aka RFMon)

The distinction between officially supported and enabled is a reflection
on the amount of validation and interoperability testing that has been
performed on a given feature.



1.2. Command Line Parameters
-----------------------------------------------

Like many modules used in the Linux kernel, the Intel(R) PRO/Wireless
2915ABG Driver for Linux allows configuration options to be provided
as module parameters.  The most common way to specify a module parameter
is via the command line.

The general form is:

% modprobe ipw2200 parameter=value

Where the supported parameter are:

  associate
	Set to 0 to disable the auto scan-and-associate functionality of the
	driver.  If disabled, the driver will not attempt to scan
	for and associate to a network until it has been configured with
	one or more properties for the target network, for example configuring
	the network SSID.  Default is 0 (do not auto-associate)

	Example: % modprobe ipw2200 associate=0

  auto_create
	Set to 0 to disable the auto creation of an Ad-Hoc network
	matching the channel and network name parameters provided.
	Default is 1.

  channel
	channel number for association.  The normal method for setting
        the channel would be to use the standard wireless tools
        (i.e. `iwconfig eth1 channel 10`), but it is useful sometimes
	to set this while debugging.  Channel 0 means 'ANY'

  debug
	If using a debug build, this is used to control the amount of debug
	info is logged.  See the 'dvals' and 'load' script for more info on
	how to use this (the dvals and load scripts are provided as part
	of the ipw2200 development snapshot releases available from the
	SourceForge project at http://ipw2200.sf.net)

  led
	Can be used to turn on experimental LED code.
	0 = Off, 1 = On.  Default is 1.

  mode
	Can be used to set the default mode of the adapter.
	0 = Managed, 1 = Ad-Hoc, 2 = Monitor


1.3. Wireless Extension Private Methods
-----------------------------------------------

As an interface designed to handle generic hardware, there are certain
capabilities not exposed through the normal Wireless Tool interface.  As
such, a provision is provided for a driver to declare custom, or
private, methods.  The Intel(R) PRO/Wireless 2915ABG Driver for Linux
defines several of these to configure various settings.

The general form of using the private wireless methods is:

	% iwpriv $IFNAME method parameters

Where $IFNAME is the interface name the device is registered with
(typically eth1, customized via one of the various network interface
name managers, such as ifrename)

The supported private methods are:

  get_mode
	Can be used to report out which IEEE mode the driver is
	configured to support.  Example:

	% iwpriv eth1 get_mode
	eth1	get_mode:802.11bg (6)

  set_mode
	Can be used to configure which IEEE mode the driver will
	support.

	Usage:
	% iwpriv eth1 set_mode {mode}
	Where {mode} is a number in the range 1-7:
	1	802.11a (2915 only)
	2	802.11b
	3	802.11ab (2915 only)
	4	802.11g
	5	802.11ag (2915 only)
	6	802.11bg
	7	802.11abg (2915 only)

  get_preamble
	Can be used to report configuration of preamble length.

  set_preamble
	Can be used to set the configuration of preamble length:

	Usage:
	% iwpriv eth1 set_preamble {mode}
	Where {mode} is one of:
	1	Long preamble only
	0	Auto (long or short based on connection)


1.4. Sysfs Helper Files:
-----------------------------------------------

The Linux kernel provides a pseudo file system that can be used to
access various components of the operating system.  The Intel(R)
PRO/Wireless 2915ABG Driver for Linux exposes several configuration
parameters through this mechanism.

An entry in the sysfs can support reading and/or writing.  You can
typically query the contents of a sysfs entry through the use of cat,
and can set the contents via echo.  For example:

% cat /sys/bus/pci/drivers/ipw2200/debug_level

Will report the current debug level of the driver's logging subsystem
(only available if CONFIG_IPW2200_DEBUG was configured when the driver
was built).

You can set the debug level via:

% echo $VALUE > /sys/bus/pci/drivers/ipw2200/debug_level

Where $VALUE would be a number in the case of this sysfs entry.  The
input to sysfs files does not have to be a number.  For example, the
firmware loader used by hotplug utilizes sysfs entries for transferring
the firmware image from user space into the driver.

The Intel(R) PRO/Wireless 2915ABG Driver for Linux exposes sysfs entries
at two levels -- driver level, which apply to all instances of the driver
(in the event that there are more than one device installed) and device
level, which applies only to the single specific instance.


1.4.1 Driver Level Sysfs Helper Files
-----------------------------------------------

For the driver level files, look in /sys/bus/pci/drivers/ipw2200/

  debug_level

	This controls the same global as the 'debug' module parameter



1.4.2 Device Level Sysfs Helper Files
-----------------------------------------------

For the device level files, look in

	/sys/bus/pci/drivers/ipw2200/{PCI-ID}/

For example:
	/sys/bus/pci/drivers/ipw2200/0000:02:01.0

For the device level files, see /sys/bus/pci/drivers/ipw2200:

  rf_kill
	read -
	0 = RF kill not enabled (radio on)
	1 = SW based RF kill active (radio off)
	2 = HW based RF kill active (radio off)
	3 = Both HW and SW RF kill active (radio off)
	write -
	0 = If SW based RF kill active, turn the radio back on
	1 = If radio is on, activate SW based RF kill

	NOTE: If you enable the SW based RF kill and then toggle the HW
  	based RF kill from ON -> OFF -> ON, the radio will NOT come back on

  ucode
	read-only access to the ucode version number

  led
	read -
	0 = LED code disabled
	1 = LED code enabled
	write -
	0 = Disable LED code
	1 = Enable LED code

	NOTE: The LED code has been reported to hang some systems when
	running ifconfig and is therefore disabled by default.


1.5. Supported channels
-----------------------------------------------

Upon loading the Intel(R) PRO/Wireless 2915ABG Driver for Linux, a
message stating the detected geography code and the number of 802.11
channels supported by the card will be displayed in the log.

The geography code corresponds to a regulatory domain as shown in the
table below.

					  Supported channels
Code	Geography			802.11bg	802.11a

---	Restricted			11 	 	 0
ZZF	Custom US/Canada		11	 	 8
ZZD	Rest of World			13	 	 0
ZZA	Custom USA & Europe & High	11		13
ZZB	Custom NA & Europe    		11		13
ZZC	Custom Japan			11	 	 4
ZZM	Custom 				11	 	 0
ZZE	Europe				13		19
ZZJ	Custom Japan			14	 	 4
ZZR	Rest of World			14	 	 0
ZZH	High Band			13	 	 4
ZZG	Custom Europe			13	 	 4
ZZK	Europe 				13		24
ZZL	Europe				11		13


2.   Ad-Hoc Networking
-----------------------------------------------

When using a device in an Ad-Hoc network, it is useful to understand the
sequence and requirements for the driver to be able to create, join, or
merge networks.

The following attempts to provide enough information so that you can
have a consistent experience while using the driver as a member of an
Ad-Hoc network.

2.1. Joining an Ad-Hoc Network
-----------------------------------------------

The easiest way to get onto an Ad-Hoc network is to join one that
already exists.

2.2. Creating an Ad-Hoc Network
-----------------------------------------------

An Ad-Hoc networks is created using the syntax of the Wireless tool.

For Example:
iwconfig eth1 mode ad-hoc essid testing channel 2

2.3. Merging Ad-Hoc Networks
-----------------------------------------------


3.  Interaction with Wireless Tools
-----------------------------------------------

3.1 iwconfig mode
-----------------------------------------------

When configuring the mode of the adapter, all run-time configured parameters
are reset to the value used when the module was loaded.  This includes
channels, rates, ESSID, etc.

3.2 iwconfig sens
-----------------------------------------------

The 'iwconfig ethX sens XX' command will not set the signal sensitivity
threshold, as described in iwconfig documentation, but rather the number
of consecutive missed beacons that will trigger handover, i.e. roaming
to another access point. At the same time, it will set the disassociation
threshold to 3 times the given value.


4.   About the Version Numbers
-----------------------------------------------

Due to the nature of open source development projects, there are
frequently changes being incorporated that have not gone through
a complete validation process.  These changes are incorporated into
development snapshot releases.

Releases are numbered with a three level scheme:

	major.minor.development

Any version where the 'development' portion is 0 (for example
1.0.0, 1.1.0, etc.) indicates a stable version that will be made
available for kernel inclusion.

Any version where the 'development' portion is not a 0 (for
example 1.0.1, 1.1.5, etc.) indicates a development version that is
being made available for testing and cutting edge users.  The stability
and functionality of the development releases are not know.  We make
efforts to try and keep all snapshots reasonably stable, but due to the
frequency of their release, and the desire to get those releases
available as quickly as possible, unknown anomalies should be expected.

The major version number will be incremented when significant changes
are made to the driver.  Currently, there are no major changes planned.

5.  Firmware installation
----------------------------------------------

The driver requires a firmware image, download it and extract the
files under /lib/firmware (or wherever your hotplug's firmware.agent
will look for firmware files)

The firmware can be downloaded from the following URL:

    http://ipw2200.sf.net/


6.  Support
-----------------------------------------------

For direct support of the 1.0.0 version, you can contact
http://supportmail.intel.com, or you can use the open source project
support.

For general information and support, go to:

    http://ipw2200.sf.net/


7.  License
-----------------------------------------------

  Copyright(c) 2003 - 2006 Intel Corporation. All rights reserved.

  This program is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License version 2 as
  published by the Free Software Foundation.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  more details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 59
  Temple Place - Suite 330, Boston, MA  02111-1307, USA.

  The full GNU General Public License is included in this distribution in the
  file called LICENSE.

  Contact Information:
  James P. Ketrenos <ipw2100-admin@linux.intel.com>
  Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497

sb1000 is a module network device driver for the General Instrument (also known
as NextLevel) SURFboard1000 internal cable modem board.  This is an ISA card
which is used by a number of cable TV companies to provide cable modem access.
It's a one-way downstream-only cable modem, meaning that your upstream net link
is provided by your regular phone modem.

This driver was written by Franco Venturi <fventuri@mediaone.net>.  He deserves
a great deal of thanks for this wonderful piece of code!

-----------------------------------------------------------------------------

Support for this device is now a part of the standard Linux kernel.  The
driver source code file is drivers/net/sb1000.c.  In addition to this
you will need:

1.) The "cmconfig" program.  This is a utility which supplements "ifconfig"
to configure the cable modem and network interface (usually called "cm0");
and

2.) Several PPP scripts which live in /etc/ppp to make connecting via your
cable modem easy.

   These utilities can be obtained from:

      http://www.jacksonville.net/~fventuri/

   in Franco's original source code distribution .tar.gz file.  Support for
   the sb1000 driver can be found at:

      http://web.archive.org/web/*/http://home.adelphia.net/~siglercm/sb1000.html
      http://web.archive.org/web/*/http://linuxpower.cx/~cable/

   along with these utilities.

3.) The standard isapnp tools.  These are necessary to configure your SB1000
card at boot time (or afterwards by hand) since it's a PnP card.

   If you don't have these installed as a standard part of your Linux
   distribution, you can find them at:

      http://www.roestock.demon.co.uk/isapnptools/

   or check your Linux distribution binary CD or their web site.  For help with
   isapnp, pnpdump, or /etc/isapnp.conf, go to:

      http://www.roestock.demon.co.uk/isapnptools/isapnpfaq.html

-----------------------------------------------------------------------------

To make the SB1000 card work, follow these steps:

1.) Run `make config', or `make menuconfig', or `make xconfig', whichever
you prefer, in the top kernel tree directory to set up your kernel
configuration.  Make sure to say "Y" to "Prompt for development drivers"
and to say "M" to the sb1000 driver.  Also say "Y" or "M" to all the standard
networking questions to get TCP/IP and PPP networking support.

2.) *BEFORE* you build the kernel, edit drivers/net/sb1000.c.  Make sure
to redefine the value of READ_DATA_PORT to match the I/O address used
by isapnp to access your PnP cards.  This is the value of READPORT in
/etc/isapnp.conf or given by the output of pnpdump.

3.) Build and install the kernel and modules as usual.

4.) Boot your new kernel following the usual procedures.

5.) Set up to configure the new SB1000 PnP card by capturing the output
of "pnpdump" to a file and editing this file to set the correct I/O ports,
IRQ, and DMA settings for all your PnP cards.  Make sure none of the settings
conflict with one another.  Then test this configuration by running the
"isapnp" command with your new config file as the input.  Check for
errors and fix as necessary.  (As an aside, I use I/O ports 0x110 and
0x310 and IRQ 11 for my SB1000 card and these work well for me.  YMMV.)
Then save the finished config file as /etc/isapnp.conf for proper configuration
on subsequent reboots.

6.) Download the original file sb1000-1.1.2.tar.gz from Franco's site or one of
the others referenced above.  As root, unpack it into a temporary directory and
do a `make cmconfig' and then `install -c cmconfig /usr/local/sbin'.  Don't do
`make install' because it expects to find all the utilities built and ready for
installation, not just cmconfig.

7.) As root, copy all the files under the ppp/ subdirectory in Franco's
tar file into /etc/ppp, being careful not to overwrite any files that are
already in there.  Then modify ppp@gi-on to set the correct login name,
phone number, and frequency for the cable modem.  Also edit pap-secrets
to specify your login name and password and any site-specific information
you need.

8.) Be sure to modify /etc/ppp/firewall to use ipchains instead of
the older ipfwadm commands from the 2.0.x kernels.  There's a neat utility to
convert ipfwadm commands to ipchains commands:

   http://users.dhp.com/~whisper/ipfwadm2ipchains/

You may also wish to modify the firewall script to implement a different
firewalling scheme.

9.) Start the PPP connection via the script /etc/ppp/ppp@gi-on.  You must be
root to do this.  It's better to use a utility like sudo to execute
frequently used commands like this with root permissions if possible.  If you
connect successfully the cable modem interface will come up and you'll see a
driver message like this at the console:

         cm0: sb1000 at (0x110,0x310), csn 1, S/N 0x2a0d16d8, IRQ 11.
         sb1000.c:v1.1.2 6/01/98 (fventuri@mediaone.net)

The "ifconfig" command should show two new interfaces, ppp0 and cm0.
The command "cmconfig cm0" will give you information about the cable modem
interface.

10.) Try pinging a site via `ping -c 5 www.yahoo.com', for example.  You should
see packets received.

11.) If you can't get site names (like www.yahoo.com) to resolve into
IP addresses (like 204.71.200.67), be sure your /etc/resolv.conf file
has no syntax errors and has the right nameserver IP addresses in it.
If this doesn't help, try something like `ping -c 5 204.71.200.67' to
see if the networking is running but the DNS resolution is where the
problem lies.

12.) If you still have problems, go to the support web sites mentioned above
and read the information and documentation there.

-----------------------------------------------------------------------------

Common problems:

1.) Packets go out on the ppp0 interface but don't come back on the cm0
interface.  It looks like I'm connected but I can't even ping any
numerical IP addresses.  (This happens predominantly on Debian systems due
to a default boot-time configuration script.)

Solution -- As root `echo 0 > /proc/sys/net/ipv4/conf/cm0/rp_filter' so it
can share the same IP address as the ppp0 interface.  Note that this
command should probably be added to the /etc/ppp/cablemodem script
*right*between* the "/sbin/ifconfig" and "/sbin/cmconfig" commands.
You may need to do this to /proc/sys/net/ipv4/conf/ppp0/rp_filter as well.
If you do this to /proc/sys/net/ipv4/conf/default/rp_filter on each reboot
(in rc.local or some such) then any interfaces can share the same IP
addresses.

2.) I get "unresolved symbol" error messages on executing `insmod sb1000.o'.

Solution -- You probably have a non-matching kernel source tree and
/usr/include/linux and /usr/include/asm header files.  Make sure you
install the correct versions of the header files in these two directories.
Then rebuild and reinstall the kernel.

3.) When isapnp runs it reports an error, and my SB1000 card isn't working.

Solution -- There's a problem with later versions of isapnp using the "(CHECK)"
option in the lines that allocate the two I/O addresses for the SB1000 card.
This first popped up on RH 6.0.  Delete "(CHECK)" for the SB1000 I/O addresses.
Make sure they don't conflict with any other pieces of hardware first!  Then
rerun isapnp and go from there.

4.) I can't execute the /etc/ppp/ppp@gi-on file.

Solution -- As root do `chmod ug+x /etc/ppp/ppp@gi-on'.

5.) The firewall script isn't working (with 2.2.x and higher kernels).

Solution -- Use the ipfwadm2ipchains script referenced above to convert the
/etc/ppp/firewall script from the deprecated ipfwadm commands to ipchains.

6.) I'm getting *tons* of firewall deny messages in the /var/kern.log,
/var/messages, and/or /var/syslog files, and they're filling up my /var
partition!!!

Solution -- First, tell your ISP that you're receiving DoS (Denial of Service)
and/or portscanning (UDP connection attempts) attacks!  Look over the deny
messages to figure out what the attack is and where it's coming from.  Next,
edit /etc/ppp/cablemodem and make sure the ",nobroadcast" option is turned on
to the "cmconfig" command (uncomment that line).  If you're not receiving these
denied packets on your broadcast interface (IP address xxx.yyy.zzz.255
typically), then someone is attacking your machine in particular.  Be careful
out there....

7.) Everything seems to work fine but my computer locks up after a while
(and typically during a lengthy download through the cable modem)!

Solution -- You may need to add a short delay in the driver to 'slow down' the
SURFboard because your PC might not be able to keep up with the transfer rate
of the SB1000. To do this, it's probably best to download Franco's
sb1000-1.1.2.tar.gz archive and build and install sb1000.o manually.  You'll
want to edit the 'Makefile' and look for the 'SB1000_DELAY'
define.  Uncomment those 'CFLAGS' lines (and comment out the default ones)
and try setting the delay to something like 60 microseconds with:
'-DSB1000_DELAY=60'.  Then do `make' and as root `make install' and try
it out.  If it still doesn't work or you like playing with the driver, you may
try other numbers.  Remember though that the higher the delay, the slower the
driver (which slows down the rest of the PC too when it is actively
used). Thanks to Ed Daiga for this tip!

-----------------------------------------------------------------------------

Credits:  This README came from Franco Venturi's original README file which is
still supplied with his driver .tar.gz archive.  I and all other sb1000 users
owe Franco a tremendous "Thank you!"  Additional thanks goes to Carl Patten
and Ralph Bonnell who are now managing the Linux SB1000 web site, and to
the SB1000 users who reported and helped debug the common problems listed
above.


					Clemmitt Sigler
					csigler@vt.edu