****************************************************************************** ****************************************************************************** ****************************************************************************** ****************************************************************************** ****************************************************************************** *** ** *** ** *** TICK v 2.0 (9-93) ** *** ** *** TMS320C40 parallel network detection and loader utility ** *** ** *** Now Supports: ** *** Transtech, Hunt, and Traquair boards ** *** hosted by DOS, SunOS, Linux (a PC unix) ** *** ** *** by Ben Abbott and Akos Ledeczi ** *** ** *** EMAIL: abbott@vuse.vanderbilt.edu, akos@vuse.vanderbilt.edu ** *** ** *** Modifications for UNIX by ** *** ** *** Mark Milligan ** *** University of British Columbia ** *** ** *** Rolf Skeie ** *** NDRE ** *** ** *** Copyright (C) 1993, Vanderbilt University. All rights ** *** reserved. ** *** ** *** Free use of this program is granted as long as it is not ** *** redistributed for profit. It may NOT be distributed in any ** *** form as part of a commercial product without the written ** *** permission of the authors. ** *** ** *** This program is distributed in the hope that it will be ** *** useful, but WITHOUT ANY WARRANTY; without even the implied ** *** warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR ** *** PURPOSE. ** *** ** *** If you need some other form of rights let us know. We can work ** *** something out. ** *** ** ****************************************************************************** ****************************************************************************** ****************************************************************************** ****************************************************************************** Considering the interest for a network check program for C40's, we have decided to release our code. New this version: - Support for Hunt/Sun SBus interface (thanks Rolf). - Source code to the makeload utility. - Cleaner, faster, closer to ANSI. - No more tick.dwn file (it is compiled to C code). - The big news is the addition of a broadcast based network loader. - Flood loader functions. - Automatic ID Rom based initialization and memory zeroing functions. - Support for multiple port address (DOS and Linux versions) - Simple Dumb Terminal (output only) mode for debug. - Example programs to illustrate loader functions: 1) Simple text based output of argv,argc values to stdout of host. 2) Flood loading of arbitrary networks for prime number calculation. Features of v1.2: - This version now reads the ID ROM values and prints them out. (Use the -i switch for the long output format) - This version has been tested with a Traquair/Hunt HEV40 board hosted by a SunOS/Unix machine. Also tested was a Transtech TDMB408 board under MSDOS v5.0 and the public domain PC unix Linux. The Traquair/Hunt HEPC-2 board was tested with an early version of this code and appears to be compatible with the Transtech board. It is believed that the HESB-40 Sbus card is compatible with the HEV40 code due to the unix device driver interface similarities. - Tick now uses INMOS style link drivers. This should help make it more easily portable to other hardware in the future. If you make a port, please let us have your driver code, and other changes. - Other features added: 1) command line parsing 2) verbose mode. 3) debug mode. 4) command line device selection. /* UNIX ONLY */ 5) environment variable for: Device Driver = TICK_DEV (SUN only) set this to point at your device driver file To compile this code you will need TI C and Turbo C. It might work with MicroSoft, but we don't use it. If you use DJGCC on PC's, look at the Makefile to see how to compile. Linux users can compile this code with their GCC compiler. The Sun version of the code was compiled with GCC. Makefiles have been included to help you build the code. Version 2.0 no longer supplies a compile.bat file. I hope everyone can figure out how to use make. We have included an executable (tick.exe) so that you don't have to compile at all. The following output illustrates how to run the program: c:> tick TICK v2.0 TMS320C40 parallel network detection utility Copyright (c) 1993 Vanderbilt University # TYPE MHz LINK0 LINK1 LINK2 LINK3 LINK4 LINK5 GMEM LMEM FMEM 1 00120001-000C 40 2:3 ... ... HOST ... 2:2 4096Kb 4096Kb 8Kb 2 00120002-000A 40 3:3 ... 1:5 1:0 ... 3:2 4096Kb 4096Kb 8Kb 3 00120002-000A 40 ... ... 2:5 2:0 ... ... 4096Kb 4096Kb 8Kb This output indicates that the network connected to this PC has 3 C40's in it. They have been numbered 1 to 3. C40 #1 is connected to the PC host through its link 3. Link 0 of C40 #1 is hooked to Link 3 of C40 #2, etc. Several items read from the ID Rom are displayed: 1) The type identifier says that Processor #1 has a manufacturer id of 0012 (Hex), model id is 0001 (Hex), Revision level is 000C (Hex). 2) The speed is indicated under the MHz label. 3) The Memory size values for Global, Local, and on chip are also provided. Using the "-i" switch provides a full ID ROM print out of each module. We have patterned this interface after the INMOS "check" program. All code here is new and is not based on the INMOS code. ****************************************************************************** ****************************************************************************** ******************************* ******************************* ******************************* NETWORK LOADER ******************************* ******************************* ******************************* ****************************************************************************** ****************************************************************************** Making a full documentation of the loader is beyond our energy level. In this section, we will simply try to illustrate the capabilities of the loader by describing the examples. The loader works in a two stage broadcast based fashion. That is, it first bootstraps the network (using the TICK functions provided for exploration). The bootstrap code, stack, and data all fit within the two on chip RAM sections of the C40 (yet it is all C code, good job TI). Once the network has been bootstrapped, the C40s begin to process loader messages. The bootstrap process has left the network connected in an acyclic tree starting from the host. This tree is used for the broadcast functions. The host sends packets out that indicate the recipients (via a bit field), the function to be performed, and the data to perform the function with. All packets go to all processors. If a packet recipient field does not match a particular node number, that node ignores the packet. There are really only two types of packets used during the loading process: DATA packets, and the START packet. The Examples directory: ----------------------- Most people like examples to understand how to use a software tool. We have provided a few simple examples to help in a subdirectory examples. To build the examples use turbo C make "make -fmakefile.dos". You may have to modify the .cmd files if your TIMs do not have RAM on the local bus or if it is in a strange place (like on strobe 1). To run an example type exam1.bat or exam2.bat or exam3.bat (I trust you unix guys know the drill here). exam1 is a simple argc, argv, string output example. It should print out the args described in the exam1.bt file. exam2 uses the flood load functions of TICK to use all of your processors to count prime numbers (give it some time to finish). exam3 also uses the flood load functions but in this case it checks to see what processors have checked in. Look at the examples, then look at the documentation, then look at the examples again. Then look at the source code. I would be quite pleased to add user contributed documentation and examples. The Network loader: ------------------- Loading code onto a network of processors is done by calling: tick -Lfile.bt Where file.bt is a text file indicating how to load the network. Its format is described below. The booting process involves two stages: - stage one sets up an acyclic broadcast tree to receive download commands on all C40s. During this bootstrap stage, all local and global RAM described in the ID ROM of each TIM bootstrapped is initialized to the 0 integer value. As well, ID ROM information is used to initialize the control register values of each TIM as necessary. - stage two accepts download packets through the broadcast tree that direct each processor to fill memory with its code as needed. The loader only uses on chip RAM of the C40s for its functions. However, it uses almost all of the on chip RAM. Therefore, initialized user code must NOT use the on chip RAM area. Results of doing so will be quite strange lock ups, etc. Since stage 1 initializes the processor control register values, the file loaded onto each processor need only match the available memory constraints. Beware, there is no run time checking to see that the user has not exceeded his available memory. However, the TI linker allows you to do a good job here at link time. Files to be loaded may be generated with the TI linker lnk30. The "makeload" program described below is used to transform output files from the lnk30 into ".dwn" files acceptable to the loader. Boot file format (.bt file) --------------------------- The boot file tells the loader the specific C40 executable file (.dwn file made with the makeload -B switch) to place on each of the different processors in the network. The boot file also indicates the path the loader should use to bootstrap the network. The boot path information makes the format of boot file somewhat complicated. We use a graphical tool to generate these files (as well as, 3L wire list files) directly, GCM. At this moment, it is about to become a commercial product sold by Transtech. GCM works for both transputer and C40 networks. It also helps you understand the output of the TICK program by providing it in a graphic format. Ask them about it. The ".bt" file format follows: - Comment lines are allowed in the .bt file. Valid comment lines must have a ";" character in the first column. - No lines should be longer than 132 characters (including all parameters) - All other lines have the following format: <.dwn file> [arguments] Only the arguments are optional. These are the values that the C program on the processor will see as arg[1], arg[2],... Arg[0] is the ".dwn" file name. is the node number of the processor that will boot node . There must be a physical comm port connection between the and the . is the comm port number [0..5] that should use to boot . <.dwn file> is the executable that will be loaded onto . Node numbers (the values given to and ) must begin with 1 and end with the number of processors to be loaded. No gaps are allowed. The host computer (the PC or SUN) is always indicated as node number 0. On a PC, the only valid is 0, the PC to C40 link adaptor. We do not have a SUN, however, We think it may be possible for it specify different s for the host. The rest of this documentation ignores this possibility. The order of -- triples must describe a valid depth first search of a spanning tree of the network to be loaded starting from the host. This means that the on the first non-comment line should be 0 and its should also be 0. of this first line is typically given a value of 1 but may be any number that fits the previously given requirements. The next line should indicate the first processor that is to boot as well as the comm port of the first that must be used to boot the next processor. And so on. Incorrect boot files will typically fail in one of two ways: (1) The loader will hang while trying to bootstrap a particular processor because no response is given. This is the failure mode that is seen when there is no processor connected to a port that was indicated as a . (2) A message saying something about an error bootstrapping node "X" because node "Y" was found in its place. This happens when the boot file indicates two paths to the same node. In this case, the attempted second bootstrap of the node causes the error. This error also happens when the "depth first spanning tree" rule is not followed. A simple way to generate a correct boot file for a network is to use the "tick -Ftest.dwn" command. This command will spit out a valid boot file for the network found. In this case, the boot file automatically generated will be set up to flood the network of C40s with the executable "test.dwn". At the end of the booting process, the global variables defined in the C startup code ("low_main.c") are set. These variables include: long _node_number; /* the number assigned to a */ long _boot_chan; /* the comm port booty was booted from. This is NOT the . Rather, it indicates an acyclic path toward the host and can be most powerful for farming applications. */ long _broadcast_mask; /* a bit field indicating each of the comm ports that were used by this node number as s. Bit 0 (the least significant bit) indicates whether or not comm port 0 was used to boot a processor, and so on. The broadcast mask is also useful for farming applications in that it describes an acyclic tree that may be used to broadcast packets out to worker processors. */ As well, argc and argv are set in the usual C fashion. By allowing the user to provide unique arguments for each loaded processor, the personality of the loaded code may be customized without having to load a unique ".dwn" file for each processor. The big advantage of using this technique is load time. Each unique ".dwn" file need only be downloaded once regardless of the number of processors that should be loaded with its code. The terminal modes and simple I/O functions: ------------------------------------------- In order to provide a simple output interface, TICK can go into a dumb display terminal mode. "tick -T" tells the host to go into this mode. Each TI character (4 bytes) received by the host will be sent to standard out. In this case, the most significant 3 bytes are dumped. "tick -TL" is similar but prints the value of the longs (4 bytes) received by the host to standard out. In this case, the values are printed in both HEX and base 10. If you have linked your C40 executable to the low_main.o40 file provided, a few simple I/O functions are available: void _low_put_long( long port, long value ); /* sends a long out a comm port. It will hang if the queue is full until room is made for the new long to be inserted. */ void _low_put_string( long port, char *str ); /* sends a string. */ long _low_get_long( long port ); /* reads a long from a port. It will hang until the read is complete. */ long _low_test_read( long port ); /* checks to see if a call to _low_get_long() will hang */ long _low_test_write( long port ); /* checks to see if a call to _low_put_long() will hang */ void _low_config(int on) /* A routine to toggle the light (or whatever) */ The flood mode: --------------- TICK can be used to act like a flood loader, a loader that automatically finds and fills all processors of a network regardless of its size or connection structure. It really is not a flood loader. Rather, flood loading involves two unique invocations of TICK. Invocation one searches the network with the standard TICK functions to find all of the processors and their interconnection structure. These results are output to a file in the format of a valid ".bt" file for the network. Invocation 2 loads the network as indicated by the just generated ".bt" file. Invocation one: tick -Ffile.dwn >flood.bt will generate a ".bt" file that will flood the network with the file "file.dwn". Invocation two: tick -Lflood.bt will actually load the network. A side effect of invocation 1 is the generation of a file "ti.mp" in the current directory. This file describes a shortest path type of virtual communication path that we use for our internal Vanderbilt message passing system. This code will most likely NOT be released out to the public. However, you may find some of its features interesting: - All processors can send messages to any other processor. - The host computer may be used as a compute engine and may send messages to any C40 node. - Full C I/O functions via the host are supported for all C40s in the network (not just a global printf). - Message passing is asynchronous and uses the full DMA capability of the C40. - A unix streams like wrapper is provided on top of the message passing system. - An identical message passing system works on transputers. - Multiple PC hosts can be and have been supported. - The GCM tool described previously allows multiple, user defined communication paths between nodes to be added. Application codes may select which path to use between processors. This is of great advantage for C40 networks since bidirectional communication transfers should be avoided for performance reasons. The makeload program: --------------------- The makeload program transforms output from the TI linker lnk30 into various download formats. The input file should always be a fully referenced, absolutely located COFF file with a start address. It should have been linked with the ROM initialization option. Further, if you are trying to use the loader portion of TICK, you will want to link to the low_main.o40 file provided. Syntax: makeload [switches] lnk30.out makeload.out Switches: -B produce a file acceptable to the TICK loader. -T produce a file in the format valid to bootstrap a reset TI down a raw link. -C produce a file of C code of an initialized array of longs describing the boot stream of data. -Z add explicit code to the download file to initialize the stack, bss, and heap sections to integer value 0. Typical call for use with the TICK loader: makeload -B user_prg.out user_prg.dwn The -Z switch is useful if your ID ROM is strange and does not really tell how much RAM you have. In this case, the loader can not always figure out how much RAM to initialize to 0. The -C and -T switches are used to generate the executable TICK program. In this case, C code is produced that is included for execution on the host. That code is an array of longs that when spit into a reset C40 causes it to come to life and run the TICK and loader functions. If you plan to hack in this area, please look at the code for tick and makeload. *********************** Manifest for TICK v 2.0 *********************** boot.asm : basic entry point for C40 codes boot.o40 check.c : Host computer codes directing C40 search and load functions check.obj checkti.c : C40 codes to handle host requests in search and load checkti.map : lnk30 output map for C40 executable checkti.o40 checkti.out : lnk30 output COFF for C40 executable defaults.h : Common flags for host and C40 side dos.cmd : C40 lnk30 command file for PC versions hes.cmd : C40 lnk30 command file for Hunt Sun version hesio.h heslink.c : Device driver interface routine for Sun version hevlink.c : Device driver interface routine for other Sun version linkio.h : Device driver interface routine prototypes for all versions low_main.c : Basic C40 startup program to handle argc, argv, etc. low_main.o40 makefile.gcc : Makefile for DJGCC a 32 bit DOS C compiler makefile.hes : Makefile for Sun makefile.lnx : Makefile for Linux (pc Unix) makefile.sun : Makefile for other Sun makefile.tcc : Makefile for DOS (Turbo C) makeload.c : The makeload utility for transforming TI COFF to .dwn files makeload.exe : MAKELOAD for DOS compiled with Turbo C makeload.obj readme : Some documentation ship.bat sun.cmd : C40 lnk30 command file for other Sun version swap4.c : Out of date utility to flip byte order for old Sun version t408link.c : Device driver interface routines for all PC versions t408link.obj tick.c : Top level Host computer side (parses args etc.) tick.exe : TICK V2.0 for DOS compiled with Turbo C tick.h : The file CHECKTI.OUT transformed to C code array tick.obj ********** * Examples are described in the readme ********** examples\exam1 examples\exam1.bat examples\exam1.bt examples\exam1.c examples\exam1.cmd examples\exam1.dwn examples\exam1.map examples\exam1.o40 examples\exam1.out examples\exam2 examples\exam2.bat examples\exam2.c examples\exam2.cmd examples\exam2.dwn examples\exam2.map examples\exam2.o40 examples\exam2.out examples\exam3 examples\exam3.bat examples\exam3.c examples\exam3.cmd examples\exam3.dwn examples\exam3.map examples\exam3.o40 examples\exam3.out examples\makefile.dos ****************************************************************************** ****************************************************************************** ****************************************************************************** *** *** *** *** *** Please let us know if you find this code useful, have comments, *** *** suggestions, bugs, etc. *** *** *** *** Ben Abbott or Akos Ledeczi *** *** Vanderbilt University *** *** Department of Electrical Engineering *** *** 400 24th Ave S. *** *** Nashville, TN 37235 *** *** *** *** abbott@vuse.vanderbilt.edu *** *** akos@vuse.vanderbilt.edu *** *** *** *** *** ****************************************************************************** ****************************************************************************** ****************************************************************************** ****************************************************************************** ******************************************************************************