[docs] - added/improved intro.

README.txt

@@ -14,6 +14,7 @@ pbctl, or pb_utils
 
 COMPILE
 -------
+
 make -C /lib/modules/`uname -r`/build M=`pwd`
 
 
@@ -23,3 +24,12 @@ QUIRKS
 Because the PulseBlaster is essentially an independent device, merely powered and 
 programmed from the host, a PulseBlaster program will continue to run even when the
 kernel module is removed, or when the host is rebooted!
+
+
+EXAMPLE
+-------
+
+doc/flash.bin is a pulseblaster executable to flash all the outputs at 2Hz
+
+To program it, copy this to /sys/class/pulseblaster/pulseblaster0/program
+Then echo 1 > /sys/class/pulseblaster/pulseblaster0/start

doc/raw.txt

@@ -1,3 +1,43 @@
 The raw format of the pulseblaster executable is  a sequence of 10-byte "VLIW" instructions.
-These are generated by pb_asm, and documented in pb_utils/doc/raw.txt.
+(These are normally generated by the separate tool pb_asm, part of pb_utils).
+
+Consider the following VLIW instruction:
+
+#OUTPUT         OPCODE  ARG	 LENGTH
+0xffeedd        CALL	0x88776  0xccbbaa99
+
+The assembler, pb_asm does the following:
+
+- Opcodes are converted from strings to numbers (as defined in pulseblaster.h)
+  [In this case, CALL = 0x4 ]
+
+- Lengths are corrected, eg subtraction of PB_INTERNAL_LATENCY.
+  [In this example, length becomes 0xccbbaa96 ]
+
+- The VLIW is is split up into 10 bytes:
+
+
+The bytes are these:
+
+  3       bytes of output
+  2 1/2   bytes for arg
+  1/2 	  byte  for opcode
+  4 	  bytes for the delay.
+
+
+Thus, we actually get the following series of writes, in this order
+
+  0xff		MSB	}	
+  0xee			} 3 byte output
+  0xdd		LSB	}
+
+  0x88		MSB	} 2 1/2 bytes of arg
+  0x77			}
+  0x64		LSN,OP	} most significant nibble = LSN of ARG,   least significant nibble = opcode
+
+  0xcc		MSB	}
+  0xbb			} 4 byte delay length.
+  0xaa			}
+  0x96		LSB	}
+