ROCK-Plug

ROCK-Plug aims to replace the original hotplug package and the current
hardware detection technology of ROCK Linux, called hwscan. It is
designed with the KISS principle in mind, fitting in the existing ROCK
Linux framework (although we have to admit, that the task by definition
is not really compatible with KISS). It features both scanning
cold-plugged devices (present during bootup) and real hotplug events
generated for devices plugged into a running system. 


Contents
========

1. Licence
2. Configuration
  2.1 System init
  2.2 Sub-systems
    2.2.1 PCI
    2.2.2 ISAPNP 
    2.2.3 PCMCIA 
    2.2.4 USB
    2.2.5 MACIO
    2.2.6 IEEE1394
    2.2.7 NET
    2.2.8 SCSI
  2.3 Scripts
3. Developer info
  3.1 Overview of linux kernel interaction
    3.1.1 Cardbus/PCI subsystem
    3.1.2 USB subsystem
    3.1.3 IEEE1394
    3.1.4 NET
    3.1.5 SCSI

=============================================================================
1. Licence
=============================================================================

NOTE: Parts of the hotplugging code resp. ideas are taken from hotplug
originally written by Greg K-H (available at
http://sourceforge.net/projects/linux-hotplug/). The files did not
contain explicit copyright statements, however its README file state
its release is covered by the GPL.

Copyright (C) 2003 Juergen "George" Sawinski <george@mpimf-heidelberg.mpg.de>
                   Rene Rebe <rene@rocklinux.org>
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 as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

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, USA.

=============================================================================
2. Overview
=============================================================================

Note: Some of the features described in the following document may not
be implemented yet. See additional information in the TODO file. 

ROCK-Plug is intergrating hardware detection and hotplugging
capabilities for the Linux kernel. ROCK-Plug does it's job in two
stages, the first stage (system init) is done as long as the root file
system is read-only. The second step, which is the actual hardware
detection mechanism, requires write access.

The second step consists of the following initialisation steps:
-PCI/CardBus
-ISAPNP
-PCMCIA
-USB
-IEEE1394 (FireWire)
-MACIO (MAC specific modules)

Furthermore, hotplugging is supported by the kernel for the following
sub-systems: 
-PCI
-USB
-NET
-IEEE1394
-SCSI (kernel 2.5 and above only)

=============================================================================
2. Configuration
=============================================================================

This section is arranged in three sections. First, we deal
with the system or early hardware init (modules that should be loaded
prior to any hardware detection and before filesystems are mounted
read-write). Second, the configuration of each sub-system and third
scripts, that may be called class or vendor/device or module specific.

User resp. administrator configurable variables have generally the
form ${PREFIX}_MODULES for modules, that are loaded on system
initialization and ${PREFIX}_SKIP_MODULES for modules, that are
generally skipped. Other variables may also be set depending on the
sub-system (the repective prefixes in lower-case: pci, isapnp, pcmcia,
usb, net, ieee1394, macio, scsi). All variables are a list of
space-sperated modules unless otherwise noted.

[...note about modules given in *_MODULES are probed in given order,
relevant e.g for USB_HC[DI]...]

-------------------------------------------------------
2.1 System init
-------------------------------------------------------

The system resp. "early hardware" init takes place before the
file-system is mounted read-write. At this stage, no hardware
detection is done at all.

Configuration file: /etc/conf/hardware (@FIXME okay?)
Variables: 
  SYSINIT_MODULES 


-------------------------------------------------------
2.2 Sub-systems
-------------------------------------------------------

2.2.1 PCI/CardBus

PCI and CardBus (not PCMCIA!) are detected on boot and the kernel
issues hotplug events (see 3.1.1). 


Configuration file: /etc/conf/pci:
Variables:
  PCI_MODULES
  PCI_SKIP_MODULES

Configuration file: /etc/conf/sound
  SOUND_SYSTEM      either "OSS" or "ALSA"

It should be noted, the usb drivers are currently skipped in the PCI
detection due to the diversity of host controller interfaces
resp. drivers (see 2.2.4). Here, we followed exactly the 2002 hotplug
implementation and will keep it until the authors get aware of
hotpluggable USB cards. 


2.2.2 ISAPNP 

[Note: the auto-detection is currently not implemented]

Configuration: /etc/conf/isapnp
Variables:
  ISAPNP_MODULES
  ISAPNP_SKIP_MODULES


2.2.3 PCMCIA 

[... not implemented yet ...]


2.2.4 USB

USB devices and hubs are detected on boot and the kernel
issues hotplug events (see 3.1.1). 

Configuration file: /etc/conf/usb:
Variables:
  USB_HCD   module list of host controller drivers
            possible drivers are: ehci-hcd ohci-hcd uhci-hcd
  USB_HCI   set this to the preferred host controller interface,
            possible drivers are: usb-ohci usb-uhci uhci
  USB_MODULES
  USB_SKIP_MODULES

Note: For X11-3.3.6, add "mousedev" and "input" to the USB_MODULES list.


2.2.5 MACIO

Configuration file: /etc/conf/macio
Variables:
  MACIO_MODULES


2.2.6 IEEE1394

Configuration file: /etc/conf/ieee1394
Variables:
  IEEE1394_MODULES
  IEEE1394_SKIP_MODULES


2.2.7 NET

Networking is highly administration dependant and therefore no
configuration is done in the hotplug and hardware detection context. 


2.2.8 SCSI

Configuration file: /etc/conf/scsi
Variables:
  SCSI_MODULES
  SCSI_SKIP_MODULES


-------------------------------------------------------
2.3 Scripts and usermaps
-------------------------------------------------------

[... conf/{pci,usb,...}.usermap -> user scripts ...]


===========================================================================
3. Developer info
=============================================================================

-------------------------------------------------------
3.1 Overview of linux kernel interaction
-------------------------------------------------------

On a hotplug event, the kernel executes /sbin/rockplug 
(the executable can be set via /proc/sys/kernel/hotplug)
with pci,usb,ieee1394,net or scsi as argument and passes all
relevant information via environment variables. The hotplug
script then calls the respective plugger script.

3.1.1 Cardbus/PCI subsystem

Parameters passed on a "pci" hotplug event:
	
	ACTION=%s [add|remove]
	PCI_CLASS=%06X
	PCI_ID=%04X:%04X
	PCI_SLOT_NAME=%s
	PCI_SUBSYS_ID=%04X:%04X

If /proc is mounted, /proc/bus/pci/$PCI_SLOT_NAME is almost the name
of the binary device descriptor file ... just change ':' to '/'.

3.1.2 USB subsystem

Parameters passed on a "usb" hotplug event:
	
	ACTION=%s [add|remove]
	PRODUCT=%x/%x/%x
	INTERFACE=%d/%d/%d
	TYPE=%d/%d/%d

And if usbfs (originally called usbdevfs) is configured, also:

	DEVFS=/proc/bus/usb
	DEVICE=/proc/bus/usb/%03d/%03d

3.1.3 IEEE1394

Parameters passed on a "ieee1394" hotplug event:
       
       ACTION=%s       [add|remove]
       VENDOR_ID=%x    (24 bit vendor id)
       GUID=%x         (64 bit globally unique id)
       SPEFICIER_ID=%x (24 bit id of owner of specification)
       VERSION=%x      (version of specification)

See IEEE1212 for details on these parameters.

3.1.4 NET

Parameters passed on a "net" hotplug event:

	ACTION=%s [add|remove]
	INTERFACE=%s (interface name, eg. eth0)

3.1.5 SCSI

The "scsi" hotplug event was introduced in the 2.5 kernel series.

Parameters passed on a "scsi" hotplug event:

       ACTION=add
       DEVPATH=%s  (format: devices/scsi0/0:0:0:0)

-------------------------------------------------------
3.2 Implementations
-------------------------------------------------------
3.2.1 /sbin/rockplug
3.2.2 /sbin/rockscan
3.2.3 /etc/rockplug/functions
3.2.4 /etc/rockplug/{pci,usb,[...]}.{config,functions,init,plug}

