$Id: README,v 1.7 2002/12/02 19:40:29 dbrownell Exp $

WHAT DO WE HAVE HERE?
---------------------
Hotplugging scripts that should work on 2.2 and 2.4 kernels, and which
understand some of the 2.5 hotplugging updates.

This particular version won't work on test versions of the 2.4 kernels,
which (NOTE!) need modutils 2.4.2 or later; for your two letter country
code (cz, jp, tw, us, etc) use this FTP site:

    ftp://ftp.COUNTRY.kernel.org/pub/linux/utils/kernel/modutils/v2.4/

Linux kernel hotplugging support relies on kernels to be configured with
HOTPLUG; and, for loading modular drivers, MODULES.  Configure USB, NET, and
PCI (for Cardbus support) as appropriate for your environment.

On 2.5 kernels, module support is changing, and you'll probably need new
module tools (check Documentation/Changes).

For more information about Linux hotplugging:

    http://linux-hotplug.sourceforge.net/

These tools are are GPL'd, and are available at the web site above.



NOTES ABOUT THIS VERSION
------------------------
There's partial support for some of the new 2.5 hotplug features,
like SCSI hotplugging.  There's more hotplug-related work yet to
be done as part of the 2.5 series; a 2.6 update will be required.

File layout is the same, with a new /var/log/hotplug directory.
USB setup scripts can have their own "usermaps".

    /etc/hotplug/ ... holds scripts
	*.agent ... for usb, pci, net, scsi and other events
	usb/*.usermap ...
	usb/*, pci/* ... device setup scripts
	*.rc ... subsystem init during startup

    /etc/rc.d/init.d/hotplug ... consistently start up usb, pci, etc

    /sbin/hotplug ... invoked by kernel on add/remove/... events

    /var/log/hotplug/ ... OPTIONAL, for recording events etc
	*.events
	events

Some of the 2.5 related changes may cause trouble on 2.2 kernels,
or even on older 2.4 kernels.

Setup scripts should now be invoked correctly (after any kernel
module had a chance to load) even when the script uses the same
name as its kernel module (and there's no USB "usermap" entry).


INSTALLING
----------
For all hotplug-enabled 2.2 and 2.4 kernels, try to use a fully modular
USB configuration.  With 2.5, that's easier:  start with "make allmod".

Since most folk now install these scripts from an RPM or a DEB, these
instructions assume you got the tree from CVS or a tarball.

 (1)  Make the root directory of that tree (with this file)
      be the working directory for your root shell.

 (2)  Install:

	# make install

 (3)  To collect ascii event logs for events that aren't handled
      by some /etc/hotplug/*.agent (optional):

	# touch /var/log/hotplug/events

      Or touch /var/log/hotplug/input.events to filter out just
      the unhandled "input" events.  (Similarly for other kinds
      of hotplug events.)

 (4)  Make sure modules are loaded, and device setup scripts are
      run, for devices that were present while the system was
      booting but which weren't handled by the initrd.  On RedHat:

	# chkconfig --add hotplug

These scripts aren't intentionally specific to RedHat; let us know if
we accidentally create a problem.  Derived versions of hotplug tools
are available from SuSE and Debian.   If distros started to converge
the interfaces their init and config tools provide to hotplug, such
problems could go away.

There are updates to the "usbutils-0.7" package to incorporate a new
"usbmodules" command, and to "pciutils-2.1.8" to incorporate a similar
"pcimodules".  See the website above for more information, or search
the web (list, rpmfind) for RPM or APT support.  Those programs help
support "cold plugging".

For 2.5, we're eliminating the "usbmodules" and "pcimodules" commands;
but you may still want them when you run 2.4 kernels.  (2.5 coldplugging
still needs updates.)


"COLD" PLUGGING AT BOOT TIME
----------------------------
Initializing devices that are present at boot time is easy to handle if
you install the "usbmodules" or "pcimodules" commands, and package most
kernel components (such as "usbcore") as dynamically linked modules.
(RedHat 7.1 handles this problem using "Kudzu" instead, which works more
selectively than "pcimodules".)

"Cold" plugging is different from hotplugging in that it happens while
the system is still warming up ("booting").  That means module loading
may not yet be possible when devices are first detected ... so these
scripts may need to scan the busses later, and synthesise hotplug events
to force the modules to load.  This is a particular issue for drivers
that are statically linked into the system kernel (perhaps so that they
can be used during system booting in some configuration).  Even in
cases with an "initrd" setup, important moduels or other system resources
may not be available until much later in the boot sequence.

If coldplugging isn't working for you (some device present at boot
time isn't properly set up), first try to unplug it and replug it.
If that works (you hotplugged it) it was a coldboot-only problem.

(Distributions won't necessarily use "hotplug" startup script, since
that relates to system administration toolsets.)


USB MICE AND KEYBOARDS
----------------------
If you need to use a USB mouse with X11, the X server needs to be able to
open "/dev/input/mice".  That means you can't hotplug a mouse you plan
to use with X11; it needs some modules preloaded.  If you haven't compiled
them into your kernel, try putting this line into /etc/sysconfig/usb:

    X11_USBMICE_HACK=true

If you're booting with a USB keyboard and/or mouse, and want to defend
against boot failures like missing modules, you should probably use
static linking for the "hid", "keybdev" (and/or "mousedev"), "input",
"usbcore", and USB Host Controller modules. 

(Different Linux distributions may handle this in other ways, such as
hard-wiring parts of USB initialization into an initrd or into scripts
that init runs very early.)


SELECTIVELY DISABLING HOTPLUGGING
---------------------------------
You can disable any particular kind of agent by marking it non-executable:

    # chmod -x /etc/hotplug/pci.agent

If you enabled event logging in /var/log/hotplug by creating the
generic "events" file, or the pci-specific "pci-events" file, then
those events will not be recorded in that file if there's an agent
to handle the event.  The log files can help debug hotplug problems.


SPECIALIZED USB DEVICE OR DRIVER SUPPORT
----------------------------------------
Devices often need specialized support, and this package is intended to
support that in the same way for Linux 2.2, 2,4, and 2.5 systems.  The
idea is that applications should be able to rely on the administrative
conventions established by this package.

Some of the mechanisms available are:

    - For kernel drivers that don't have MODULE_DEVICE_TABLE hotplug
      support add entries to /etc/hotplug/usb.handmap using the syntax
      of /lib/modules/`uname -r`/modules.usbmap

	  EXAMPLE:  With the 2.4.0 kernel, most HID devices (joysticks,
	  tablets, etc) need such support.  Until 2.4.1, so did the
	  usb-storage devices.

	  (On 2.5 systems, an input.agent should eventually handle
	  input drivers that aren't statically linked.)
    
    - Drivers may provide a per-device setup script that's invoked after
      they modprobe:  /etc/hotplug/usb/MODULENAME is called for USB
      devices, CardBus devices use /etc/hotplug/pci, and so on:

	  EXAMPLE:  When you connect your USB PDA, you might want to
	  automatically start its hotsync daemon.  (visor)
    
    - For usermode drivers (using /proc/bus/usb/BBB/DDD files), you can
      add entries to /etc/hotplug/usb.usermap, again using the syntax of
      "modules.usbmap".  The "module name" will just identify a setup
      script (as above); it's not modprobed.
	
	  EXAMPLE:  This has been done with Rio MP3 players and with
	  digital cameras supported by gPhoto2; a "chmod" can enforce
	  more granular security policies than "usbdevfs" mount options.
    
    - Sometimes several kernel drivers may be able to handle a given
      device, and you don't want some drivers to be automatically loaded.
      (Only the first one will really hotplug, usually in alphabetical
      order.)  Just add those driver names to /etc/hotplug/blacklist
      and they won't be modprobed by these scripts.

	  EXAMPLE:  uhci and usb-uhci; the many variants of tulip; and
	  sometimes other vendor or development versions of drivers.

If you add a new hotpluggable module to a 2.4 based system, "modutils"
will make it automatically hotplug (using MODULE_DEVICE_TABLE).  For 2.2
based systems, without such modutils support, you should add the device
to /etc/hotplug/usb.handmap in order for it to hotplug.
