hotplug.txt

采用嵌入式开发的wireless无线模组的应用开发工具

	To use Hotplug network configuration with 16 bits Pcmcia
cards, first make sure the Pcmcia subsystem is properly configured and
that cardmgr load the right driver module (in most case, it
should). Then, make sure that you don't have any configuration entries
in /etc/pcmcia/network.opts and /etc/pcmcia/wireless.opts. Make sure
that none of entries in your system network configuration use 'eth0'
or 'wlan0' (in /etc/network/interfaces for Debian users).
	Then, just follow the procedure described above for
"Configuration Using Hotplug" to configure your network cards.

	You might want a little bit of explanation on why this magic
will work (which would help in case it doesn't work).
	There are two types of Pcmcia network configuration scripts,
available as /etc/pcmcia/network. The original Pcmcia script configure
network cards using options found in /etc/pcmcia/network.opts and
/etc/pcmcia/wireless.opts. Most distributions replace it with a script
calling 'ifup'. By making sure that network.opts and wireless.opts are
"empty", we neutralise the first set of scripts. By making sure no
system configuration uses 'eth0' or 'wlan0', we neutralise the second
set of scripts, the script would call 'ifup' with the default
interface name, which is usually 'eth0', ifup would not find a
configuration for it and would just ignores it.
	The card would still be configured because hotplug network
events are generated for every interfaces, not only for devices
managed by hotplug. So, net.agent would receive an event and perform
the necessary steps to configure it.

	Personally, I'm still using the original Pcmcia scripts for my
Pcmcia cards as described in the file PCMCIA.txt, because it still
works and I will migrate my complex configurations over time.
	You can also decide to not use Hotplug for Pcmcia cards and
modify the distribution Pcmcia scripts in /etc/pcmcia/* to handle
Pcmcia cards with ifrename. You would need to modify
/etc/pcmcia/network to add 'ifrename' before 'ifup' the same way it
was done for /etc/hotplug/net.agent. But, as in the long term Pcmcia
will migrate to Hotplug, I would not bother...

MANUAL LOADING, DOCKING STATIONS
--------------------------------
	Manual loading is used for built-in network interfaces that
are only use at specific time, and that you want disabled the rest of
the time. We assume that you still use modules so that when the
interface is not used you can remove the driver from the kernel.

	First, you need to set the configuration for those interfaces,
the same way it's done for other network interfaces. The main
difference is that you need to specify that those interfaces should
not be enabled at boot time. It's also a good idea to disable Hotplug
init scripts.
	With Debian, you just need to make sure that the 'auto"
keyword doesn't apply to this interface.

--------- /etc/network/interfaces -----------
# AMD AMD PCnet LANCE PCI card
iface eth4 inet dhcp
---------------------------------------------

	If you use driver statically built in the kernel, you can just
enable and disable those interfaces with 'ifup ethX' and 'ifdown ethX'.

	If you use both a modular system and 'ifrename', you will need
to change your habits when enabling those devices. The classical 'ifup
ethX' won't work.
	If you don't use Hotplug, you need to do :
-----------------------------------
modprobe eth4
ifrename
ifup eth4
-----------------------------------
	If you use hotplug, you only need to do :
-----------------------------------
modprobe eth4
-----------------------------------

	On the other hand, disabling the interface has not changed :
-----------------------------------
ifdown eth4
modprobe -r eth4
-----------------------------------
	Using "modprobe -r" make sure that if the driver is composed
of multiple module all the modules are unloaded.

	Docking stations for laptops may contain built-in
interfaces. My previous laptop had one, and Linux had no support for
it. To be able to simply manage my docking station, I had created two
little scripts to enable and disable my network interface.
	After docking, you would run :
-------- /sbin/dock ----------------------------
#!/bin/sh
modprobe eth4
ifrename
ifup eth4
------------------------------------------------
	And prior to undocking, you would run :
-------- /sbin/undock ----------------------------
#!/bin/sh
ifdown eth4
modprobe -r eth4
------------------------------------------------
	Thanks to 'ifrename', the network interface in your dock will
always be properly configured regardless of if you have a Pcmcia
network card in the Pcmcia slot or not.

SCHEMES (MULTI-CONFIG)
----------------------
	Most Ethernet cards will only connect to a single network, or
can use DHCP to be auto-configured. With Wireless Cards, it's much
more likely that you will need multiple configurations, for example at
work, at home and on-the-go.

	Most distributions have various level of support for such
schemes. Some distributions offer simple network schemes, while other
offer "overall" schemes changing the whole configuration. I document
the support for schemes in various distributions in the file
DISTRIBUTIONS.txt.

	You can also use tools such as ifplugd, waproamd or
wlandetect. Those tools are a kind of "wireless-DHCP", they attempt to
automatically detect the proper wireless configuration and apply
it. Most will also attempt to detect network changes.
	The main limitation of those tools is that they offer very
little manual control. If two valid alternatives are possible, you
can't switch between them. If a configuration can't be detected, they
usually fail.
	That's the same concept as using DHCP versus Static IP
addresses. Some people are very happy with DHCP, my style is Static IP
addresses.

	If you use Debian and want to use simple manual schemes, these
are the things you need to do.
	1) Make sure that 'ifscheme' and 'ifscheme-mapping' are
installed on the system. You may find them in a separate tar file on
my web site.
	2) Check the path for 'ifscheme-mapping' (using whereis).
	3) Modify you /etc/network/interface to add proper mapping and
configuration.

------- /etc/network/interfaces ----------------------
# Enable Hotplug support (Sarge and later)
mapping hotplug
    script echo

# SMC 2835W wireless CardBus card
mapping prism0
    script /sbin/ifscheme-mapping

iface prism0-any inet dhcp
    wireless-essid any
    wireless-mode managed

iface prism0-adhoc inet static
    address 10.0.1.2
    network 10.0.1.0
    netmask 255.255.255.0
    broadcast 10.0.1.255
    wireless-essid THE_ESSID
    wireless-mode ad-hoc
    wireless-channel 5

iface prism0-other inet static
    address 10.10.10.2
    network 10.10.10.0
    netmask 255.255.255.0
    broadcast 10.10.10.255
    wireless-essid ANOTHER_ESSID
    wireless-mode ad-hoc
    wireless-key "s:secure"
------------------------------------------------------

FIRMWARE LOADING
----------------
	A lot of modern wireless card don't have built in firmware and
need firmware loading. Recent kernel (2.6.X) have a firmware
loader. These are a few notes on how to use it.

	First, read the documentation coming with your driver, because
each driver has specificities (like the name of the firmware file it
requires).

	You need to compile your kernel with firmware loading
(CONFIG_FW_LOADER in "Generic Driver Options"). If your driver was
built from the kernel, chances are that it enabled this feature
already. Make sure you boot from this new kernel.

	The 'sysfs' file system must be mounted. The easiest is to
mount it at boot time, add a line for it in /etc/fstab :

-------- /etc/fstab ------------------------------
sysfs		/sys	      sysfs  defaults                   0      0
--------------------------------------------------

	Then, you add the firmware file in the directory where it's
expected, which is /usr/lib/hotplug/firmware/ in most cases.

	Most distributions nowadays have a version of the Hotplug
scripts that knows how to deal with firmware. If it is not the case,
just grab the 'firmware.agent' file from an alternate source and copy
it into your /etc/hotplug directory (make sure it's executable).
	You can try the canonical version :
		http://linux-hotplug.sourceforge.net/
	Or Debian's version :
		http://packages.debian.org/unstable/admin/hotplug

	Note that firmware loading will usually only work with
interfaces that are fully managed by Hotplug. This is the only way to
ensure the that proper sequence of action is happening in the right
order every time. Firmware loading will usually not work properly for
interfaces configured in the init scripts.
	This means that if you have a built-in interface that require
firmware loading, you should just use manage those interfaces like
removable interfaces (see section above). However, interface
configuration need to be explicitely triggered at boot time.

	One possibility is to set-up Hotplug to be run from the init
script at boot time. This is usually an option for recent
distributions (it's not the case for Hotplug in Debian 3.0). But, we
have seen that this has some issues.
	The other possibility is to use an hybrid between the init
script method and the hotplug method. First, you need to add an alias
for the driver in /etc/modprobe.conf. Then, you need to specify a
mapping for this interface in /etc/iftab, and specify a configuration
for this interface and that that it is enabled at boot time. Lastly,
you make sure that the network init scripts run 'ifrename
-p'. 'Ifrename' will trigger the module to load, and all the Hotplug
events will be generated properly to configure the interface.

DEVICES WITH MULTIPLE NAMES
---------------------------
	Some wireless drivers offer multiple network interfaces for
the same device. A classical example is the Aironet driver that
creates a 'ethX' and 'wifiY' for each card.

	'ifrename' allow you a finer selection of interfaces than
'nameif'. For example, to only rename the pseudo-Ethernet network
interface name of the Aironet driver, you would do :

--------- /etc/iftab -----------------------
# Cisco Aironet 350 wireless Pcmcia card
airo*		mac 00:07:0E:* arp 1
---------------------------------------------

	After that, your device would be available through 'eth0' and
'wifi0'.

	You can rename both interfaces. You just need to remember that
'ifrename' start matching from the last line of the file, so you would
do :
--------- /etc/iftab -----------------------
# Cisco Aironet 350 wireless Pcmcia card
wifi*		mac 00:07:0E:*
airo*		mac 00:07:0E:* arp 1
---------------------------------------------

	The current version of 'ifrename' support only the most useful
selectors, and is architectured such as adding selectors is relatively
trivial. If you find a case that 'ifrename' can't handle, you should
just extend it.

DEVICES WITHOUT MAC ADDRESSES
-----------------------------
	Most Ethernet and Wireless devices have a fixed and unique MAC
address, and it is therefore advised to name them based on this
criteria. However, there is also network interfaces that don't have a
fixed and unique MAC address, for example Ethernet over USB, IP over
FireWire, PPP and tunnel interfaces.
	The driver for those devices create the interface with a name
specific to the driver, such as ppp* for PPP interfaces and usb* for
Ethernet over USB, and therefore they are easy to identify and
configure, and few users feel the need to rename them. Moreover, some
of them, such as PPP, have their own configuration scripts and
methodology addressing their unique needs.

	There is a few cases where you might want to rename interfaces
withour MAC addresses. One example is two Ethernet over USB
dongles. The way to do this is to use alternate ifrename
selectors. Choosing the right selector depend on what you want to
achieve.
	A quick theoretical example to illustrate :
--------- /etc/iftab -----------------------
# All other usbnet devices
usb*		driver usbnet
# Specific usbnet devices
usb-p		firmware "Prolific PL-2301/PL-2302"
usb-4		bus-info usb-00:02.0-1.4
---------------------------------------------

TROUBLESHOOTING
---------------
	If your interface doesn't show up as expected with ifconfig,
you will need to find out why. First, you need to be familiar with the
sequence of actions in the system and find which one did not happen.

	You need to check that the driver module(s) was loaded using
'lsmod'.

	You need to check if the interface was properly renamed with
'ifrename'. You can use 'ifrename -D -V' to debug your /etc/iftab.
	Get the the list of interfaces on your system with 'cat
/proc/net/dev', and check if an interface is using the name you
assigned or 'eth0'. Check any suspicious interfaces with 'ifconfig
eth0', and check its MAC address. Note that some rare drivers don't
have a proper MAC address before brought up, which fools ifrename.
	Verify that no line in /etc/iftab matches the all-zero MAC
address. The all-zero MAC address matches the loopback interface 'lo'
and various pseudo network devices, renaming the loopback interface is
highly discouraged.

	You need to check which configuration was given to the
interface using 'ifconfig' and 'iwconfig'.

	The Hotplug subsystem has also good debugging facilities.
	To enable Hotplug debugging, just make sure the variable DEBUG
is defined in /sbin/hotplug :
--------- /sbin/hotplug ------------------------------
--- /sbin/hotplug-old      Tue Mar 26 09:00:20 2002
+++ /sbin/hotplug       Fri Feb 20 18:40:38 2004
@@ -22,7 +22,7 @@
 cd /etc/hotplug
 . hotplug.functions
 
-# DEBUG=yes export DEBUG
+DEBUG=yes export DEBUG
 
 if [ "$DEBUG" != "" ]; then
     mesg "arguments ($*) env (`env`)"
------------------------------------------------------
	Then, you can check your message logs for Hotplug events with
'tail -f /var/log/messages'. Verify that the various Hotplug events
happen as expected (pci, firmware, net...), and verify the log
messages from 'net.agent'.


	Have fun...

	Jean