This is the README.txt file for the TMU distribution.  The TMU package allows
a program running on a Linux workstation to easily transfer data to and from
a user's circuit in an Altera DE-3 or DE-4 demonstration board.


DOCUMENTATION

There are 4 pdf documents in the doc sub-directory, entitled:

	The TMU Ports Package
	Creating and Running Circuits with the TMU Ports Package
	An Example Application for the TMU Package
	The tmumon Program


INSTALLATION

1) Untar the package and change into the top level directory:

	tar xzf tmu1.3.tar.gz
	cd tmu1.3

2) Edit the top level makefile and change the top two lines from this to
something sensible:

	INSTALL_DIR=please_set_the_INSTALL_DIR_variable_in_the_top_level_makefile_and_run_make_config
	DEFAULT_SERVER=localhost

Set INSTALL_DIR to a directory where the package's files should be installed.
Set DEFAULT_SERVER to the name of the machine that is connected to the
demonstration board via the USB cable.

3) Type:

	make config
	make install

This will copy the values of the INSTALL_DIR and DEFAULT_SERVER variables
to the lower level makefiles that need them, and then compile and install the 
programs and scripts that make up the package.


CABLING

There are 4 USB connectors on the DE-3 demonstration board.  The one marked
USB-BLASTER is used by Quartus to program the board, and for debugging
circuits using SignalTap.  The ones marked HOST2 and HOST3 (or USB2 and
USB3) are used to connect USB peripherals to the board.

The connector that the TMU package uses to communicate with the board is
marked USB1.  It is smaller than the other USB connectors.  Connect a
cable from this connector to the Linux workstation that will be running
the tmumon program.

On the DE-4, the connector used by the TMU package is labelled USB OTG.


PERMISSIONS

Once plugged in and programmed, a user's circuit with the TMU portmux
circuitry will show up on the attached Linux workstation as a device somewhere
under the /dev/bus/usb directory (for example, /dev/bus/usb/004/005).
By default, Linux will protect the device so that ordinary users can't
access it:

	crw-rw-r-- 1 root root 189, 256 2011-01-20 10:41 005

This will prevent the tmumon program from communicating with the circuit.
You can change this to full permissions by using sudo:

	sudo chmod 666 /dev/bus/usb/whatever

but this has to be re-done every time the board is re-programmed or re-attached.
To fix this, you can use Linux's udev package to automatically change the
permissions every time.  The file:

	src/tmumon/tmuports.rules.udev

can be copied to:

	/etc/udev/rules.d/52-tmuports.rules

to make this happen.  Read the udev documentation for details.


TMUMON

Once the USB cable is plugged in and the permissions have been fixed, you
should be able to start the tmumon daemon program on the Linux machine that is
connected to the cable.

In any directory on that machine, run:

	tmumon &

If the board has been programmed with a user's circuit that includes the
TMU portmux circuitry, tmumon should print:

	Opening interface...
	Successfully opened interface.

Once tmumon is running, it should stay running indefinitely until killed.
It will accept requests from user programs using the TMU package, and will
relay them to the board over the USB cable.  It should adapt gracefully
if the board is disconnected and re-connected or re-programmed.


EXAMPLE CIRCUITS

There are two example circuits in the examples/de3 directory, along with
programs that use the TMU package to communicate with them.

The "counter" circuit supplies a 32 bit value that increments every time
a program reads from its "result" port.  The "summer" circuit returns the
32 bit sum of all numbers written to its "input_data" port since the last
time its "result" port was read. 

The same example circuits, but for the DE-4 board, are in the
examples/de4 directory.


OTHER NOTES

The tmumon program needs to use the libusb-1.0 library.  Although you may
already have the libusb-1.0 package installed on your machine,
you may be missing the <libusb-1.0/libusb.h> include file.  To get it, install
the libusb-1.0-0-dev package.  If you can't find a packaged distribution,
look on this web site:

	http://www.libusb.org/wiki/libusb-1.0

The tmu script that builds the portmux component for your circuit assumes
that Altera's quartus bin directory is on your search path.

The optional tmstatus program needs the tcl/tk wish program installed.  We are
using tk 8.4.

The optional tmget and tmrelease scripts assume that the TMU program "tm"
is on your search path.

By default, the ports package will assume that it is talking to a board that
is connected to "localhost".  You can over-ride the default host by setting the
TM_SERVER environment variable before opening the port.  To change this
default permanently, modify the DEFAULT_SERVER variable in src/tmports/makefile.


JAVA SUPPORT

There is preliminary support that should allow java programs to talk to
circuits in src/tmports/*.java.  It is still a bit rough, but we have used it
on an Android phone to talk to an FPGA circuit over a wireless LAN.
