[pb_utils] - add pb_utils to this tree.

pb_utils contains an assembler, some utitlities, documentation and some examples.

.gitignore

@@ -6,3 +6,5 @@ Module.symvers
 Module.markers
 modules.order
 .tmp_versions
+pb_utils/man/*.bz2
+pb_utils/man/*.html

Makefile

@@ -16,6 +16,7 @@ compile:
 	ln -sf    pb_test-flash-2Hz.1.bz2 man/pb_test-flash-fastest-5.55MHz.1.bz2
 	ln -sf    pb_test-flash-2Hz.1.bz2 man/pb_test-identify-output.1.bz2
 	ln -sf    pb_driver-load.1.bz2    man/pb_driver-unload.1.bz2
+	make -C pb_utils
 
 install:
 	@[ `whoami` = root ] || (echo "Error, please be root"; exit 1)
@@ -40,10 +41,15 @@ install:
 	install  -m644 README.txt LICENSE.txt doc/*            $(DOCDIR)
 	install  -m644 man/*.1.bz2                             $(MAN1DIR)
 
+	make -C pb_utils install
+
+
 clean:
 	rm -f kernel/*.o kernel/*.ko
 	rm -f man/*.bz2 man/*.html
 
+	make -C pb_utils clean
+
 uninstall:
 	@[ `whoami` = root ] || (echo "Error, please be root"; exit 1)
 	rm -rf /lib/modules/`uname -r`/kernel/3rdparty/pulseblaster
@@ -63,3 +69,5 @@ uninstall:
 	rm -f  $(MAN1DIR)/pb_test-flash-fastest-5.55MHz.1.bz2
 	rm -f  $(MAN1DIR)/pb_test-identify_output.1.bz2
 	rm -rf $(DOCDIR)
+
+	make -C pb_utils uninstall

README.txt

@@ -41,7 +41,7 @@ USERSPACE
 It's possible to just write directly to the /sys interface. 
 
 * pb_ctl and pb_utils provide helpful wrappers. 
-  pb_utils can also assemble .vliw format files.
+* pb_utils can also assemble .vliw format files.
 
 * pb_test-identify-output is useful for identifying channels.
 

pb_utils/LICENSE.txt

@@ -0,0 +1,5 @@
+Copyright by Richard Neill <pulseblaster at REMOVE.ME.richardneill.org> 2004-2013
+
+This is Free Software, released under the GNU GPL, version 3 or later.
+http://gnu.org/copyleft/gpl.html
+

pb_utils/Makefile

@@ -0,0 +1,170 @@
+PREFIX      = $(DESTDIR)/usr/local
+BINDIR      = $(PREFIX)/bin
+INCLUDEDIR  = $(PREFIX)/include
+DATAROOTDIR = $(PREFIX)/share
+DOCDIR      = $(DATAROOTDIR)/doc/pb_utils
+MANDIR      = $(DATAROOTDIR)/man
+MAN1DIR     = $(MANDIR)/man1
+MAN5DIR     = $(MANDIR)/man5
+BASHCOMPDIR = /etc/bash_completion.d
+
+CFLAGS      = -Wall -Wextra -Werror -O3 -march=native -std=gnu99
+
+all ::	pbutils manpages
+
+pbutils:
+	$(CC) $(CFLAGS) -o src/pb_start    src/pb_start.c
+	$(CC) $(CFLAGS) -o src/pb_stop     src/pb_stop.c
+	$(CC) $(CFLAGS) -o src/pb_arm      src/pb_arm.c
+	$(CC) $(CFLAGS) -o src/pb_cont     src/pb_cont.c
+	$(CC) $(CFLAGS) -o src/pb_init     src/pb_init.c
+	$(CC) $(CFLAGS) -o src/pb_zero     src/pb_zero.c
+	$(CC) $(CFLAGS) -o src/pb_prog     src/pb_prog.c
+	$(CC) $(CFLAGS) -o src/pb_asm      src/pb_asm.c
+	$(CC) $(CFLAGS) -o src/pb_vliw     src/pb_vliw.c
+	$(CC) $(CFLAGS) -o src/pb_stop-arm src/pb_stop-arm.c
+	$(CC) $(CFLAGS) -o src/pb_serial_trigger  src/pb_serial_trigger.c
+
+	strip src/pb_start
+	strip src/pb_stop
+	strip src/pb_arm
+	strip src/pb_cont
+	strip src/pb_init
+	strip src/pb_zero
+	strip src/pb_prog
+	strip src/pb_asm
+	strip src/pb_vliw
+	strip src/pb_stop-arm
+	strip src/pb_serial_trigger
+
+	@grep -Eq '#define\s*HAVE_PB\s*1' src/pulseblaster.h || echo "Warning: Built with #define HAVE_PB 0."
+
+manpages:
+	bzip2 -kf man/pb_utils.1
+	ln -sf  pb_utils.1.bz2  man/pb_start.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_stop.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_arm.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_stop-arm.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_cont.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_init.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_zero.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_prog.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_asm.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_vliw.1.bz2
+	ln -sf  pb_utils.1.bz2  man/pb_check.1.bz2
+	bzip2 -kf man/pb_test-pbinit-counter.1
+	ln -sf  pb_test-pbinit-counter.1.bz2  man/pb_test-vliw-walk4.1.bz2
+	bash man/vliw.5.sh
+	bash man/pb_freq_gen.1.sh
+	bash man/pb_manual.1.sh
+	bash man/pb_serial_trigger.1.sh
+	bash man/pb_serial_trigger_check.1.sh
+
+examples :: examples_good examples_invalid
+examples_good:
+	rm -f vliw_examples/good/*.bin*
+	@echo "Processing vliw_examples/good (correct code that should assemble ok)..."
+	for file in vliw_examples/good/*.vliw ; do echo "Assembling $$file..."; ./src/pb_asm $$file || exit 1; done
+	@echo "All good examples assembled succesfully."
+examples_invalid:
+	rm -f vliw_examples/invalid/*.bin*
+	@echo "Processing vliw_examples/invalid (invalid code that should fail to assemble)..."
+	for file in vliw_examples/invalid/*.vliw ; do echo "Assembling $$file..."; ! ./src/pb_asm $$file && echo "**CORRECTLY** detected deliberate syntax error in file $$file ." || exit 1; done
+	@echo "All invalid examples succesfully failed to assemble."
+
+clean:
+	rm -f src/pb_start
+	rm -f src/pb_stop
+	rm -f src/pb_arm 
+	rm -f src/pb_cont
+	rm -f src/pb_init
+	rm -f src/pb_zero
+	rm -f src/pb_prog
+	rm -f src/pb_asm
+	rm -f src/pb_vliw
+	rm -f src/pb_serial_trigger
+	rm -f vliw_examples/good/*.bin*
+	rm -f vliw_examples/invalid/*.bin*
+	rm -f man/*.bz2 man/*.html
+
+install:
+	@[ `whoami` = root ] || (echo "Error, please be root"; exit 1)
+
+	mkdir -p $(BINDIR) $(INCLUDEDIR) $(MAN1DIR) $(MAN5DIR) $(DOCDIR)
+
+	install        src/pb_start               $(BINDIR)
+	install        src/pb_stop                $(BINDIR)
+	install        src/pb_arm                 $(BINDIR)
+	install        src/pb_cont                $(BINDIR)
+	install        src/pb_init                $(BINDIR)
+	install        src/pb_zero                $(BINDIR)
+	install        src/pb_prog                $(BINDIR)
+	install        src/pb_asm                 $(BINDIR)
+	install        src/pb_vliw                $(BINDIR)
+	install        src/pb_check.sh            $(BINDIR)/pb_check
+	install        src/pb_freq_gen.sh         $(BINDIR)/pb_freq_gen
+	install        src/pb_manual.sh           $(BINDIR)/pb_manual
+	install        src/pb_serial_trigger      $(BINDIR)
+	install        src/pb_serial_trigger_check.sh $(BINDIR)/pb_serial_trigger_check
+
+	install        tests/pb_test-pbinit-counter.sh   $(BINDIR)/pb_test-pbinit-counter
+	install        tests/pb_test-vliw-walk4.sh       $(BINDIR)/pb_test-vliw-walk4
+
+	install  -m644 src/pulseblaster.h  $(INCLUDEDIR)
+
+	install  -m644 src/pb_utils.bashcompletion  $(BASHCOMPDIR)/pb_utils
+	install  -m644 doc/* README.txt LICENSE.txt $(DOCDIR)
+	install  -m644 man/*.1.bz2  $(MAN1DIR)
+	install  -m644 man/*.5.bz2  $(MAN5DIR)
+	cp -r          vliw_examples/               $(DOCDIR)
+
+	@grep -qE '#define\s*HAVE_PB\s*1' /usr/local/include/pulseblaster.h || echo "Warning: Installed with #define HAVE_PB 0."
+	@/bin/echo -e "Success: pb_utils is now installed."
+
+
+uninstall:
+	@[ `whoami` = root ] || (echo "Error, please be root"; exit 1)
+
+	rm -rf $(DOCDIR)
+
+	rm -f $(BINDIR)/pb_start
+	rm -f $(BINDIR)/pb_stop
+	rm -f $(BINDIR)/pb_arm 
+	rm -f $(BINDIR)/pb_cont 
+	rm -f $(BINDIR)/pb_init
+	rm -f $(BINDIR)/pb_zero
+	rm -f $(BINDIR)/pb_prog 
+	rm -f $(BINDIR)/pb_asm 
+	rm -f $(BINDIR)/pb_vliw
+	rm -f $(BINDIR)/pb_check
+	rm -f $(BINDIR)/pb_serial_trigger
+	rm -f $(BINDIR)/pb_serial_trigger_check
+
+	rm -f $(BINDIR)/pb_test-pbinit-counter
+	rm -f $(BINDIR)/pb_test-vliw-walk4
+	rm -f $(BINDIR)/pb_freq_gen
+	rm -f $(BINDIR)/pb_manual
+
+	rm -f $(INCLUDEDIR)/pulseblaster.h 
+
+	rm -f $(BASHCOMPDIR)/pb_utils
+
+	rm -f $(MAN1DIR)/pb_utils.1.bz2
+	rm -f $(MAN1DIR)/pb_start.1.bz2
+	rm -f $(MAN1DIR)/pb_stop.1.bz2
+	rm -f $(MAN1DIR)/pb_arm.1.bz2
+	rm -f $(MAN1DIR)/pb_stop-arm.1.bz2
+	rm -f $(MAN1DIR)/pb_cont.1.bz2
+	rm -f $(MAN1DIR)/pb_init.1.bz2
+	rm -f $(MAN1DIR)/pb_zero.1.bz2
+	rm -f $(MAN1DIR)/pb_prog.1.bz2
+	rm -f $(MAN1DIR)/pb_asm.1.bz2
+	rm -f $(MAN1DIR)/pb_vliw.1.bz2
+	rm -f $(MAN1DIR)/pb_check.1.bz2
+	rm -f $(MAN1DIR)/pb_freq_gen.1.bz2
+	rm -f $(MAN1DIR)/pb_manual.1.bz2
+	rm -f $(MAN1DIR)/pb_serial_trigger.1.bz2
+	rm -f $(MAN1DIR)/pb_serial_trigger_check.1.bz2
+	rm -f $(MAN1DIR)/pb_test-pbinit-counter.1.bz2
+	rm -f $(MAN1DIR)/pb_test-vliw-walk4.1.bz2
+	rm -f $(MAN5DIR)/vliw.5.bz2

pb_utils/README.txt

@@ -0,0 +1,117 @@
+This is the contents of pb_utils/, and a short explanation of what everything does. All binaries can be invoked with -h.
+
+
+README.txt
+	This readme file with the explanations.
+
+pulseblaster.h
+	The header file, with all the definitions. See the manual for more information. In particular, the #defines are here for debugging.
+
+../driver
+	Other directory, with the pulseblaster kernel driver in it. Note that you need to run pb_driver-load.sh
+
+
+src/
+	The actual pulseblaster programs themselves.
+		pb_functions.c
+			Include file: functions containing most of the stuff that actually does things!
+
+
+		pb_init [FLAGS]
+			Initialise the pulseblaster and set the outputs to FLAGS (or zero if unspecified).
+			FLAGS is optional and is in either hex or decimal, and may be one long number or split up into bytes. (eg '12 34 56' or '0xFFACD2')
+			Note: this will terminate and overwrite any currently-loaded program.
+
+		pb_zero 
+			Initialise the pulseblaster and set the outputs to all zeros. This is used to explicitly zero the outputs; useful to remove parasitic 
+			power otherwise supplied to the circuit, during a power-on reset. (It's a trivial modification of pb_init).
+			Note: this will terminate and overwrite any currently-loaded program.
+
+		pb_prog FILE.vliw
+			Program the pulseblaster with the pulse program in FILE.vliw  (as documented in doc/vliw.txt)
+			Some basic sanity-checking of the .vliw file is performed, however complex errors (eg stack depth exceeded) will not be caught.
+			After this, the pulseblaster is left un-armed.
+			[File may also be a pre-compiled .bin file, from pb_asm]
+			Programming the PulseBlaster stops it, but leaves the outputs untouched.
+
+		pb_asm FILE.vliw [OUT.bin]
+			Assemble the .vliw file to a .bin file. for use subsequently by pb_prog. 
+			This doesn't touch the pulseblaster hardware at all.
+
+		pb_start
+			Starts the pulseblaster excecuting (from the beginning of the program). 
+			This will work whether or not the pulseblaster is armed. Start implicitly stops (and resets) the PB in order to restart it.
+			[HW_TRIGGER is not-quite exactly equivalent; it only works when the PB is armed]
+
+		pb_stop
+			Stops the pulse program which is currently executing. Does NOT re-arm it. 
+			[HW_RESET is slightly different; it leaves the PB armed.]
+
+		pb_arm
+			(Re-)Arm the pulseblaster. Only required after programming to make HW_TRIGGER work.
+			(pb_arm will implicitly stop a running pulseblaster)
+
+		pb_cont
+			Continue the pulseblaster. Required to software trigger after a WAIT. 
+			(Unlike pb_start, pb_cont will not stop and reset a running pulseblaster)
+
+		pb_check
+			Check whether the PulseBlaster is physically installed. (checks `lspci`). pb_driver-load may still be needed.
+
+
+	Helper programs:
+		pb_freq_gen
+			Control the PB to output a square wave of a given frequency on a given set of output bits.
+
+		pb_manual
+			Manually control the pulseblaster outputs. This is a user-interface wrapper around pb_init, to allow for direct control
+			of the output lines. Useful for prototyping and testing.
+
+		pb_serial_trigger
+			Trigger the HW_Trigger input. This uses a spare RS232 serial port, with a trivial circuit to allow for external
+			triggering (or resetting). It could usefully be adapted.
+
+doc/
+	Documentation of file formats etc.
+		vliw.txt
+			documents my ".vliw" file format. Note: .vliw files are human-editable, but *usually* generated from a .pbsrc file.
+		pulseblaster-hardware-trigger-reset.txt
+			Explanation of the pulseblaster hardware trigger/reset.
+		pulseblaster-opcodes.txt
+			Explanation of the pulseblaster opcodes.
+		hardware-modifications.txt
+			Explanations of how I modified the pulseblaster.
+
+man/
+	Brief man pages for the pb_utils binaries, the tests, and the vliw file-format.
+
+vliw_examples/
+	Example vliw files, for testing and debugging. Notably:
+		good/ 	- some useful and testing files, such as:
+ 		    example.vliw
+		 	simple vliw file
+	  	    flash_leds_2Hz.vliw
+			flash LEDs at 2Hz
+		    walking_leds_2Hz.vliw
+			walking LEDs (3s) at 2Hz
+		    flash_leds_fastestpossible.vliw
+			walking LEDs at fastest possible rate for the hardware.
+		walking_4leds_1Hz.vliw
+			walking LEDs (4s) at 1Hz
+
+		invalid/ - some deliberately broken vliw files.
+
+tests/	
+	Test scripts, to check everything works. 
+		pb_test-pbinit-counter.sh
+			test that pb_init works, but emulating a binary counter.
+		pb_test-vliw-walk4.sh
+			test that vliw file programming works.
+
+Makefile
+	To compile and install: make; sudo make install.  The executables (all beginning with pb_) will be installed in /usr/local/bin
+
+
+README.txt, LICENSE.txt
+	This readme, and the GPL License.
+