PnpManager is ready

The ArkLinux PnpManager is finally ready for use!

It took a long time, but I think it was worth it. We have basically three 
components now that will make ArkLinux unique. Firstly we have pclasses as a 
foundation and the main author Christian Prochnow on board, secondly there is 
PSI, our common hardware library (detection and possibly user-space drivers), 
and thirdly there is the PnpManager, which does hardware configuration 
through an event based system (coldplugging and hotplugging). All LGPL.

INSTALLING
Bero is working on rpms. For now you need to get it from CVS. the modules are:
- PSI
- PnpManager

1) You need the pclasses rpms installed (there are a few)

2) You need to compile PSI. That requires libraw1394(-devel) and 
e2fstools(-devel) (available as rpm) besides pclasses. PSI needs to be 'make 
install'. I usually install the libs in /lib and the headers in /usr/include. 
One library will be built called 'libsystem'.

3) You need to compile PnpManager. That requires pclasses and PSI, of course. 
For testing you dont need to 'make install' the PnpManager. One executable 
will be built in the /src dir of the project called 'pnpmgr' and a library 
called 'libpnp'. 


USAGE
The pnpmgr program is invoked with command line arguments (preferably as su) :

pnpmgr --scanPci
pnpmgr --scanPs2

The first will make the PnpManager to scan the PCI busses and install devices, 
the second is the same for Ps2. 
CAUTION: scanning ps2 under X can freeze the ps2 mouse. but it can be safely 
tested when you switch to a console. PCI scanning is always safe.

Here is an overview what happens when you do pnpmgr --scanPci:

- there is a device registry of all already installed devices in /etc/pnp. 
Initially its empty of course

- An ADD event for all attached PCI devices will be sent to libpnp. It will 
install the devices and make an entry for each installed device 
in /etc/pnp/devices.<profile>. The test version in CVS will not work on the 
actual config files, but create new ones with the postfix '_test' (i.e. 
modules.con_test, XF86Config_test) so you can test without screwing up your 
current system.

- A REMOVE event for all PCI devices that are still in the registry, but can 
not be found on the PCI bus anymore is sent to libpnp. The device is removed 
from the registry and the config files.

- Logically when you run pnpmgr twice it should install everything in the 
first go and create the pnp-registry, and in the second go only report that 
devices are only installed. If you unplug a pci card  and run it again it 
should remove the device.

- The pnp-registry has profiles. Genrally there is a profile for each config 
file that lists the devices that have been installed in that particular 
config file. you will probably find a devices.modules.conf, 
devices.modprobe.conf or devices.XF86Config.


DEVELOPER INFO
The center of the PnpManger is the class 'PnpManager', the abstract base class 
'PnpHandler' and the various PnpEvent and PnpData classes. It was the goal of 
the design that PnpManager will be able to perform coldplugging and 
hotplugging, so PnpManager needs to be attached to the linux hotplug system 
to receive events(not implemented yet, but relatively easy). Coldplug events 
are generated by scanning the busses ourselves, currently 
PnpManager::scanPci() and PnpManager::scanPs2().

To react very flexibe to PnpEvents the PnpManager delegates the events to a 
set of PnpHandler classes. In the PnpManager ctor, the PnpHandler are 
registered and a event is forwarded to all of them. 

Event --> PnpManager --> Handler1
                                 --> Handler2
                                 --> HandlerN

This enables us to add and remove handlers as we wish in the future without 
much hassle. For instance if we would change (bero: hypothetically) from 
XFree86 to Xorg you would only need to remove the XFree86 profile from the 
pnp-registry and the XF86ConfigPnpHandler and replce it with a new Handler. 
Other possible mouse (lets say gpm) or display adapter (maybe framebuffer) 
configurations are not affected, which is not as easily possible with kudzu 
where everyting is lumped in one system.

The PnpHandler decides if it needs to react to the event or not. The 
PnpHandler class is simple:

class PnpHandler {
	public:
		PnpHandler() {}
		virtual ~PnpHandler() {}
		virtual void event(PnpEvent& e) = 0;
		virtual const std::list<PnpData*>& installedDevices() const = 0;
};

To write a PnpHandler you need to reimplement the event handler function 
PnpHandler:.event(PnpEvent& e) and filter out the events you want to react 
to. Aslo you need to keep a list of PnpData* for the devices that your 
handler has installed and return it through PnpHandler::installedDevices(). 
The PnpRegistry is used to simplify this process, but it is also thinkable 
that the config file itself can be used as a persistent data store or that no 
installed devices are registered for instance in case of USB.

The derived handlers that currently exist for Ark are in the /src/Ark dir of 
the project. They can be distro specific (zdeems: PcLinuxOS will need their 
own handlers) As of now we have:

- FsTapPnpHandler : filters Ide and Scsi events and modifies fstab and the 
kdesktop

- ModulesConfPnpHandler : filters Pci events and modifies modules.conf. 
currently for network, soundcards, usb and firewire controllers

- ModprobeConfPnpHandler : same as ModulesConfPnpHandler for modprobe.conf

- XF86ConfigPnpHandler : filters Pci and Ps2 events and modifies XF86Config. 
works for display adapters and Mice.

The Handler classes use a few config file helper classes such as XF86Config to 
work on the config files. XF86Config parses and writes the XF86Config file. 
These helper classes are possibly interesting for other apps too, so if there 
is demand we can seperate them out into a separate lib (saintiss: still 
interested?).

INFO: The path names in the config file classes are set to the actual path 
name of the config file with the prefix '_test'. If you want to 'arm' the 
PnpManager you need to change this in the classes FsTab, ModulesConf, 
ModprobeConf and XF86Config.

FUTURE WORK
We need to add missing features to the existing handlers and expand into 
hotplugging. Hotplugging is much easier though than coldplugging, because no 
persistent data store is required and config file handling is minimal.

I hope you will enjoy using (and developing) the PnpManager,
Marc