	Murasaki 0.8.11	(another HotPlug)

			Shuu Yamaguchi <shuu@dotAster.com>

Murasaki automatically loads and unloads modules for hotplugable devices
 using new feature "Hotplug" in Linux 2.4 and later.
Now, below devices are supported;
	- usb
	- pci(Cardbus)
	- net
	- ieee1394
	- pcmcia
	- firmware
	- input
And murasaki.generic is able to support any hotplugable devices.
But complex devices like looking map-file need a system to do that.

[Requires]
	* Kernel 2.4.1 or later
	* modutils 2.4.1 or later
	* Support for hot-pluggable devices on General setup Menu 
		in kernel configuration
[Download]
	The latest murasaki is put on 
	http://www.dotaster.com/~shuu/linux/murasaki/

[Files]
	* hotplug.murasaki --- Hotplug program
		Linux kernel calls this when a hot-pluggable device 
		is connected(registerd) or disconnected(unregisterd).
		And then, this calls an appropriate agent program for 
		a hotplug event.

	* murasaki.usb ------- USB Agent program
		"hotplug.murasaki" calls this when a USB device is connected
		into or disconnected from a USB hub.
		This loads/unloads some modules matched in usbmap. 

	* murasaki.pci ------- PCI(Cardbus) Agent program
		"hotplug.murasaki" calls this when a Cardbus device is
		connected into or disconnected from a card slot.
		This loads/unloads some modules matched in pcimap. 

	* murasaki.generic ---- generic Agent program
		"hotplug.murasaki" calls this when a device
		except ieee1394, pci and usb is connected or disconnected.
		This call a script '[a kind of generic device]'
		line in murasaki.call and murasaki.precall.
		[See murasaki.call/murasaki.precall]

	* murasaki.ieee1394 -- IEEE1394 Agent Program
		"hotplug.murasaki" calls this when a IEEE1394 device is
		connected or disconnected.
		This loads/unloads some modules matched in ieee1394map. 

	* murasaki.pcmcia_socket--PCMCIA Agent Program
		"hotplug.murasaki" calls this when a PCMCIA device is
		inserted into or remove from a card slot.
		This loads/unloads some modules matched in pcmcia_socketmap
		 and gives a device some appropriate resources. 

	* murasaki.input ----- input Agent Program
		"hotplug.murasaki" calls this when a input device is
		connected or disconnected.
		This loads/unloads some modules matched in inputmap. 

	* murasaki_init.usb -- USB initialize program
		This call USB Agent program for USB devices which have
		already connected to a PC when a PC turn on.

	* murasaki_init.pci -- PCI initialize program
		This call PCI Agent program for PCI devices which have
		already connected to a PC when a PC turn on.

	* murasaki_init.ieee1394 - IEEE1394 initialize program
		This call IEEE1394 Agent program for IEEE1394 devices
		which have already connected to a PC when a PC turn on.

	* murasaki_init.pcmcia_socket - PCMCIA initialize program
		This reserves appropriate resources (memory, I/O ports and IRQs)
		for PCMCIA devices and calls PCMCIA Agent program for
		them which have already inserted to a PC when a PC turn on..

	* murasaki.usbmap ---- USB MAP configuration file
		"murasaki.usb" looks at this to search a appropriate USB
		module name.

	* murasaki.pcimap ---- PCI MAP configuration file
		"murasaki.pci" looks at this to search a appropriate PCI
		 module name.

	* murasaki.ieee1394map IEEE1394 MAP configuration file
		"murasaki.ieee1394" looks at this to search a appropriate
		 IEEE1394 module name.

	* murasaki.pcmcia_socktmap - PCMCIA MAP configuration file
		"murasaki.pcmcia_socket" looks at this to search a appropriate
		 PCMCIA module name.
		 It is an unique format.

	* murasaki.inputmap -- input MAP configuration file
		"murasaki.input" looks at this to search a appropriate input
		 module name.

	* pcmcia_resource
		Memory, I/O ports and IRQs,which PCMCIA needs, are 
		written on this.

	* murasaki.conf ------ Control all 
		This contorl Agent programs and beep.

	* murasaki.depend ---- depending modules file
		Agent program searches depended modules or
		expands alias module name through this.
		An alias module name begins with "alias-" and expanded modules
		are loaded or unloaded by an agent program.
		[See detail of murasaki.depend]

	* murasaki.call ------ setup script file
		An Agent program uses this to setup modules.
		[See detail of murasaki.call/murasaki.precall]

	* murasaki.precall --- setup script file before loading/unloading
		Murasaki uses this such as murasaki.call, but scripts
		on this are called before loading/unloading modules.
		[See detail of murasaki.call/murasaki.precall]

	* murasaki.preload --- preloaded modules file
		RC script loads modules in this on booting.
		[See detail of murasaki.preload]

	* add.preload -------- additional modules to modules.preloaded
		The modules in this are added to modules.preload.
		[same format as murasaki.preload]

	* remove.preload -------- removal modules from modules.preloaded
		The modules in this are removed from murasaki.preload.
		[same format as murasaki.preload]

	* murasaki.sticky --- not unloaded modules file
		The modules listed in this are NOT unloaded
		when the hotplug device is removed.
		[same format as murasaki.preload]

	* murasaki.blacklist - not loaded modules file
		The modules listed in this are Not loaded
		when the hotplug device is added.
		[same format as murasaki.preload]

	* murasaki.genericlist - generic device list file
		The modules listed in this are supported by
		murasaki.generic.
		[same format as murasaki.preload]

	* auto_setup --------- preload file setup sh-script.
		This is called by RC script and write appropriate modules
		on preload file.

[How to make]
	build the Agent and HotPlug from sources.
		$ make

[How to install]
	1) Become root user
		$ su
	2) Install files
		# make install

	(Note)
	'make install' will install each file for RedHat(or compatible)
	system. If you use another system, you need add the following line
	at appropriate place in RC script.
		- On starting
			rc.murasaki start
		- On shutdowning
			rc.murasaki stop

[How to Setup]
	1) run /usr/lib/murasaki/auto_setup
	----------------------------------------
        [shuu@air]$ /usr/lib/murasaki/auto_setup
	hid
	uhci-hcd
	----------------------------------------
	2) Write all modules you want on booting into 
	   /etc/murasaki/add.preload.
	3) Write all modules you do Not want on booting into 
	   /etc/murasaki/remove.preload.

	Note: Do 2),3) as root user

[detail of murasaki.preload]
	RC script(rc.murasaki) loads modules in this.
	It forms each module per line and it can include some lines.
	It usually includes USB host controller, HID and mouse module.

	<Format>
	----------------------
	module1
	module2
	module3
	----------------------

	(My case)
	----------------------
	mousedev
	hid
	uhci
	----------------------

[detail of murasaki.depend]
	The 1st token is module's name with ':'.
	The 2nd token is depended module filename. You are able to 
	write multiple files using <space> characters before the next.

	<Format1>
	------------------------------------------------------------
	module_name: depended-filename [depended-filename2 ...]
	------------------------------------------------------------
	module_name
		module name
	depended-filename
		depended module name

		You can specify some modules which depend on 'module_name'.
		Depended modules are load/unload as 'module_name'. 

	<Format2>
	------------------------------------------------------------
	alias-name: expanded-filename [expanded-filename2 ...]
	------------------------------------------------------------
	alias-name
		alias module name
	expanded-filename
		expanded module name 

		If module name begins with 'alias-', Murasaki identify it as
		alias module and load/unload expanded modules.

[detail of murasaki.call/murasaki.precall]
	When you added a hotplug device, the script with 'start' as
	the 1st argument is called . On the other hand when you removed it, 
	the script with 'stop' as the 1st argument is called.
	The format of this file is same as murasaki.depend.

	<Format1>
	------------------------------------------------------------
	module_name: executable-filename [executable-filename2 ...]
	------------------------------------------------------------
	module_name
		module name
	executable-filename
		executable command name

		You can specify executable script name for each module event.

	<Format2>
	------------------------------------------------------------
	[device_name]: executable-filename [executable-filename2 ...]
	------------------------------------------------------------
	device_name
		device name       You can choose usb,pci,ieee1394 and net.
	executable-filename
		executable command name

		You can specify executable script name for each device event.
		Now, 'net' the executable script is put on /usr/lib/murasaki
		for net device event.
		(Note)
		    Please enclose device name with '[' and ']'
		
	The Agent looks at /usr/lib/murasaki first of all when it searches
	executable script. 
	You should put executable script on /usr/lib/murasaki to identify
	it as what only Murasaki calls.

	You can use following evironment variable for executable script.

	[usb]
		ACTION
			"add" or "remove"
		DEVFS
			"/proc/bus/usb"
		PRODUCT
			"%x/%x/%x"	(hex)
			1st: Vendor ID
			2nd: Product ID
			3rd: Device version (Binary Coded Decimal)
		TYPE
			"%d/%d/%d"	(dec)
			1st: Device Class ID
			2nd: Device SubClass ID
			3rd: Device Protocol ID
		INTERFACE
			"%d/%d/%d"	(dec)
			1st: Interface Class ID
			2nd: Interface SubClass ID
			3rd: Interface Protocol ID

	[pci]
		ACTION
			"add" or "remove"
		PCI_ID
			"%04X:%04X"	(hex)
			1st: Vendor ID
			2nd: Device ID
		PCI_SUBSYS_ID
			"%04X:%04X"	(hex)
			1st: Subsystem Vendor ID
			2nd: Subsystem Device ID
		PCI_SLOT_NAME
			"%s"
			Slot name

	[ieee1394]
		ACTION
			"add" or "remove"
		VENDOR_ID
			"%06x"		(hex)
			Vendor ID
		GUID
			"%016Lx"	(hex)
			GUID
		SPECIFIER_ID
			"%06x"		(hex)
			SPECIFIER ID
		VERSION			(hex)
			"%06x"
			Versionֹ

	[net]
		ACTION
			"register" or "unregister"
			"add" or "remove" (kernel 2.5)
		INTERFACE
			"%s"
			Interface name
			Ex.) eth0

