	Murasaki 0.6.11	(another HotPlug)

			Shuu Yamaguchi <shuu@dotAster.com>

Murasaki automatically loads and unloads modules for USB,Cardbus,network,etc
 using new feature "Hotplug" in Linux 2.4.
Now kernel supports USB,Cardbus,network and IEEE1394.
Kernel 2.5.7 and later provide ACPI hotplug function which call 
/sbin/poweroff to turn off a PC. But murasaki is not called.

[Requires]
	* Kernel 2.4.0 or later
		If you use kernel 2.4.0, you need to get the patch
		against 2.4.0 and rebuild your kernel.
		The patch "patch-2.4.0-hotplug.bz2" is on the URL where
		modutils is.
	* modutils 2.4.1 or later
	* Support for hot-pluggable devices on General setup Menu 
		in kernel configuration

[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.net ------- network Agent program
		"hotplug.murasaki" calls this when a network device is
		registerd or unregisterd.
		This sets up network environment using an script at '[net]'
		line in murasaki.call.
		[See murasaki.call]

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

	* murasaki_init.usb -- USB initialize program
		This call USB Agent program for USB devices which have
		already connected to a PC when 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 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.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]

	* murasaki.sticky --- not unloaded modules file
		The modules listed in this are NOT unload
		when the hotplug device is removed.
		The format of this equal to 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

[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 /etc/murasaki/bin
		for net device event.
		(Note)
		    Please enclose device name with '[' and ']'
		
	The Agent looks at /etc/murasaki/bin first of all when it searches
	executable script. 
	You should put executable script on /etc/murasaki/bin 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"
		INTERFACE
			"%s"
			Interface name
			Ex.) eth0

