Cleaned up README and added diagnostic output

Signed-off-by: Manohar Vanga <manohar.vanga@cern.ch>

README

 Self-describing Wishbone Specification
 Author: Manohar Vanga
-Email: manohar dot vanga at organization-with-worlds-biggest-particle-collider dot com
+Email: manohar dot vanga at organization-with-worlds-biggest-particle-collider dot ch
+
+This folder contains the specification document for the self-describing
+wishbone bus.
+
+The 'simulation' folder contains the driver and example simulation of a
+wishbone bus.

simulation/README

@@ -8,7 +8,7 @@ latest git kernel). The hard disk image has been made using debootstrap.
 
 Please send any bugs/comments/criticism/flames/free-cookies to
 
-	manohar.vanga at gmail dot com
+	manohar dot vanga at cern dot ch
 
 
    Compiling
@@ -22,3 +22,50 @@ to build against. You can set it in the LINUX environment variable:
 The default is  $(HOME)/linux-for-wbonesim  so you can just make a symlink
 to the real place and forget about it.
 
+    Running
+    -------
+
+Install the wishbone.ko module:
+
+	insmod wishbone.ko
+
+Install the fake wishbone device drivers:
+
+	insmod fakeadc.ko
+	insmod fakedac.ko
+
+Install the fake Wishbone bus driver:
+
+	insmod fake_wb_bus.ko
+
+You can additionally specify the device and vendor to use for loading the
+firmware file. The firmware file name is formatted as fakespec-VVVVVVVV-DDDD,
+where V is vendor and D is device. The default device and vendor have been
+set in the fake bus to 0xbabe, so the default firmware file is:
+
+	firmware-0000babe-babe
+
+To change, use the spec_vendor and spec_device module parameters of the fake_wb_bus
+driver. Remember to name the firmware to load accordingly.
+
+Generating Firmware
+===================
+
+To generate a Wishbone memory map, we can use the wb_addrgen tool found
+in the simulation/fw/ directory.
+
+To generate a firmware file (the wishbone memory space):
+
+$ ./wb_addrgen wbone.def firmware.bin
+
+The wbone.def file specifies the devices that should be attached
+to the Wishbone bus. The format for specifying devices can be seen
+in the example wbone.def file at simulation/fw/wbone.def.
+
+Installing Firmware
+===================
+
+The generated firmware file should be 4KB in size. Copy the firmware
+file into /lib/firmware/NAME where NAME is as specified above.
+
+	$ cp firmware.bin /lib/firmware/firmware-0000babe-babe

simulation/fw/README

-Generating Firmware
-===================
-
-To generate a Wishbone memory map, we assume that all devices
-are at 1KB addresses. This can be changed easily later.
-
-To generate the firmware file for the spec board:
-
-$ ./wb_addrgen wbone.def firmware.bin
-
-The wbone.def file looks like this:
-
-$ cat wbone.def 
-#Vendor Device Subdevice Priority Class Version
-      1      2         3        4     5       6
-     10     11        12       13    14      15
-
-Installing Firmware
-===================
-
-The generated firmware file should be 4KB in size.
-copy the firmware file into /lib/firmware/NAME
-NAME is as specified in the driver
-
-For the spec driver, the firmware name is expected to be 
-"fakespec-VENDORID-DEVICEID".
-
-Default Vendor ID (4 bytes): 0x0000babe
-Default Device ID (2 bytes): 0xbabe
-
-$ cp firmware.bin /lib/firmware/fakespec-0000babe-babe

simulation/fw/wb_addrgen.c

@@ -125,10 +125,13 @@ int main(int argc, char *argv[])
 	id = sdwb_create_id();
 
 	fin = fopen(argv[1], "r");
-	if (!fin)
+	if (!fin) {
+		printf("Unable to open wishbone device specification file: %s\n", argv[1]);
 		return 1;
+	}
 	fout = fopen(argv[2], "w");
 	if (!fout) {
+		printf("Unable to open output firmware file for writing: %s\b", argv[2]);
 		fclose(fin);
 		return 1;
 	}
@@ -169,5 +172,7 @@ int main(int argc, char *argv[])
 	fclose(fin);
 	fclose(fout);
 
+	printf("Successfully generated firmware file: %s\n", argv[2]);
+
 	return 0;
 }

simulation/fw/wbone.list

+# DEVICE SPECIFICATION FORMAT
+# ===========================
+
 # Major Minor Vendor Device Base Size Flags Class Version Date
 # VName
 # DName
 
 # Device 1
-1 0 0 1 0x10000000 0x1000 0 0 1 0x20111225
+# Major Minor Vendor Device Base         Size   Flags Class Version Date
+  1     0     0      1      0x10000000   0x1000 0     0     1       0x20111225
 CERN
 fake-adc
 
 # Device 2
-1 0 0 2 0x20000000 0x1000 0 0 3 0x20120101
+# Major Minor Vendor Device Base         Size   Flags Class Version Date
+  1     0     0      2      0x20000000   0x1000 0     0     3       0x20120101
 CERN
 fake-dac