          Web-Enabled Simulators (WEDS) Framework
     for Digital Signal Processors and Microcontrollers

  Dogu Arifler, Chi Duong, Brian L. Evans, Srikanth Gummadi,
       Jun Huang, Saleem K. Marwat, and Chris M. Moy

     Department of Electrical and Computer Engineering
   The University of Texas at Austin, Austin, TX 78712-1084

                Version 1.3.0	05/18/01

          http://signal.ece.utexas.edu/~arifler/


                 Table of Contents

    A. Introduction                  B. Installation on Unix Machines
    C. Installation on PCs           D. Customizing WEDS
    E. Supporting the WEDS project   F. Acknowledgements


A. Introduction

This release of WEDS consists of the following components:

-- A set of Java applets that provide a configurable framework for
   Web-based user interfaces for instruction set architecture
   simulators/emulators
   (by Dogu Arifler, Brian Evans, Jun Huang, and Saleem Marwat) 

-- A multithreaded TCP/IP server written as a Java application that
   provides the interface between the Java applets and the
   simulators/emulators
   (by Dogu Arifler, Brian Evans, Jun Huang, and Saleem Marwat) 

-- Command-line simulators/debuggers written in C/C++ that run under
   Windows '9x, Windows NT/2000, and more than twelve Unix architectures
   including Solaris 2.5 and Linux for the following processors:
   a. Texas Instruments TMS320C30 floating-point digital signal
      processor simulator
      (by Chi Duong, Brian Evans, Srikanth Gummadi, and Chris Moy) 
   b. Motorola MC68HC11 microcontroller simulator
      (by Saleem Marwat and Brian Evans) 
   c. Motorola MC56811 fixed-point digital signal processing simulator
      (by Anna Yuan and Brian Evans)
   d. Motorola MC56LC811 fixed-point digital signal processing board
      debugger
      (by Anna Yuan and Brian Evans)

A list of known bugs in this directory as the file knownBugs.txt.

All source code in the release is freely distributable.  All of the
source code written by UT Austin is covered by the GNU license.

Before you can install WEDS, you must have the following packages
which are not included in the WEDS release:

-- Java 2 Standard Edition (J2SE) (Java Developer Kit 1.3), which is 
   freely available from

   http://java.sun.com/j2se

-- Java(TM) Plug-in 1.3 for running Swing applets in Web browser that 
   currently do not support Swing. Note that you will automatically
   be guided through the Java Plug-in installation if you do not already
   have the plugin on your system.

   http://java.sun.com/products/plugin

We provide pre-built binaries of the TMS320C30 and MC68HC11 emulators
for Windows '95/NT machines (using the Borland C/C++ compiler 5.02)
and Solaris 2.5 machines (using the GNU C/C++ compiler version 2.7.2).
The sections below describe how to install and customize WEDS on Unix
machines and PCs.  To build Unix versions of the emulators other than
the Solaris 2.5 version, you'll need

-- a ANSI C/C++ compiler: the source code has been tested with the GNU
   C/C++ compiler version 2.7.2 available from http://www.fsf.org/.
   NOTE: Native C compilers invoked by cc are often not ANSI-compatible.

-- GNU make utility (which must be called 'make' and be on your path
   before the default Unix make utility)

Note that the initial release of WEDS was called the Web-Enabled
Texas Instruments C30 Simulator (WETICS).  As a consequence, we have
kept the directory structure based on the WETICS acronym.


B. Installation on Unix Machines

1. Download the Unix WEDS release as a GNU-zipped tar archive:

ftp://pepperoni.ece.utexas.edu/pub/wetics/wetics1.3.0/wetics1.3.0.tar.gz

   Uncompress these files in your public_html directory, e.g.

mv wetics1.3.0.tar.gz $HOME/public_html
cd $HOME/public_html
gunzip wetics1.3.0.tar.gz
tar xvf wetics1.3.0.tar
rm wetics1.3.0.tar

2. Update weds.cfg file according to your settings:

   weds.cfg requires the definition of 3 variables:
   SERVERNAME = <IP address or the name of the host to run the WEDS server>
   URL = <URL that contains the WEDS's user interface classes>
   TCPPORT = <TCP Port number that the server will listen to connection requests>
 
3. Set an environment variable indicating the machine and operating
   system architecture you are using:

setenv PTARCH `$HOME/public_html/wetics/bin/ptarch`

   Note that the 'setenv' command is C shell syntax.  If you are using
   either the Bourne or Korn shells, then the proper syntax is

PTARCH=`$HOME/public_html/wetics/bin/ptarch`; export PTARCH

4. Update the WEDS emulators ONLY if you are not on a Solaris 2.5 machine:

cd $HOME/public_html/wetics
make install >& make.out
grep -i error make.out

   You do not have to build the emulators under Solaris 2.5 because
   the binaries are already included for Solaris 2.5.

5. Start the WEDS TCP/IP server on your Web site:

cd $HOME/public_html/wetics/classes
java -Denv.C30SIM=../simulator/tms320c30/bin.$PTARCH/c30sim \
     -Denv.MC6811=../simulator/m68hc11/bin.$PTARCH/m68hc11sim \
     -Denv.SIM568=../simulator/clas568/bin.$simArch/sim56800 \
     -Denv.ADS568=../simulator/ads568/bin.$simArch/ads56800 \
     utexas.espl.weds.server Server >& Server.out &

   You can enable debugging information to be printed by the server
   by passing -DDEBUG=true to the java command.

   Note that the server startup command depends on the PTARCH
   environment variable being set correctly.

   As an alternative, you can start the WEDS TCP/IP server as follows:

cd $HOME/public_html/wetics/bin
./startServer userName

   where userName is a login name.  Before you run the startServer
   shell script, however, you should consider checking to make sure
   that the settings at the beginning of the file are correct for your
   Unix platform.

   To add an extra layer of security: (1) set up a dummy account with
   user name webserve that is the only member of the group webserve
   and place a quota on the account, (2) change directories to
   $WEDSHOME/public_html/wetics/classes in the account in which
   WEDS is installed and create two subdirectories named outfiles and
   userprograms that are owned and writable by webserve, and (3) change
   directories to $WEDSHOME/public_html/wetics/bin and run the
   server from the webserve account using the Unix command

./startServer webserve

6. Open your WEDS URL using Netscape 2.0 or higher (or Explorer 3.0
   or higher) and run the Web-based user interface.


C. Installation on PCs:

1. Download WEDS for the PC by retrieving the zipped archive

ftp://pepperoni.ece.utexas.edu/pub/wetics/wetics1.3.0/wetic130.zip

   The 'wetic110.zip' is a PK zip file.  Uncompress these files in
   your public_html directory using

pkunzip -a wetic110.zip

   The -a option is necessary to convert all of the text files in
   the archive to PC format because the archive was created on a
   Unix machine.

2. Edit the weds.cfg file (See Installation on Unix Machines, Step 2)

3. Start the TCP/IP server on your Web site.  Change directories to

public_html\wetics\classes

   and run the Server Java application

java utexas.espl.weds.server.Server > Server.out

   The default settings of the Server application will use the 
   Windows '95/NT versions of the TMS320C30 and MC68HC11 emulators.
   To specify the Windows '95/NT versions explicitly, use

java -Denv.C30SIM=..\..\simulator\tms320c30\bin.win\c30sim -Denv.MC6811=..\..\simulator\m68hc11\bin.win95\m68hc11sim -Denv.SIM568="../../simulator/clas568/bin.$simArch/sim56800 -Denv.ADS568=../../simulator/ads568/bin.$simArch/ads56800 Server > Server.out

   You can enable debugging information to be printed by the server
   by passing -DDEBUG=true to the java command.

4. Open the WEDS URL using Netscape 2.0 or higher (or Explorer 3.0
   or higher) and run the Web-based user interface.


D. Customizing WEDS

D.1. Adding a new simulator

One of the key ideas behind WEDS is that the same user interface can
be configured to support different types of digital signal processor
and microcontroller simulators.  To change the number and types of
simulators being supported, simply edit the data in following file:

wetics/javasrc/utexas/espl/weds/server/ServerThread.java   lines 78-137

No application code changes when changing the simulators that are
supported, but you will have to recompile ServerThread.java with
the new changes.

D.2. Customizing what socket is used for the connections

By default, WEDS uses socket number 4337 to communicate.  You
can customize this by changing the statement

TCPPORT = <TCP Port Number>

in the weds.cfg file.

D.3. Access to Various Directories from Web browsers

Using .htaccess files, we have prevented Web browsers from seeing

1. the server directory tree except for server/classes/examples and
   server/classes/userprograms which are needed by WEDS users, and
2. the simulator directory tree except for simulator/tms320c30/doc
   and simulator/m68hc11/Sim68Doc which contain documentation.

The release contains the following .htaccess files relative to
the $HOME/public_html/wetics directory:

1. Deny access

classes/.htaccess
simulator/tms320c30/.htaccess
simulator/m68hc11/.htaccess

2. Allow access

classes/examples/.htaccess
classes/userprograms/.htaccess
simulator/tms320c30/doc/.htaccess
simulator/m68hc11/Sim68Doc/.htaccess

D.4. Known JDK Bugs in Earlier Versions

In the earlier versions, the WEDS server could not reliably terminate a child 
simulator process when the connection was terminated by the user by closing the user
interface for the simulator.  We believe the problem was due to a bug in JDK 1.0.2.
In J2SE, however, this problem has been resolved. Nevertheless, we still choose to 
kill the WEDS server, and hence all of its child  simulator processes if there is any,
at regular intervals. We developed a solution for Unix systems that involves
initiating a crontab* entry for the WEDS TCP/IP server:

$HOME/public_html/wetics/bin/weticsCrontab

This crontab job will kill and restart the WEDS TCP/IP server every
morning at 3:15 AM local time.  For more information on crontab jobs,
see 'man crontab' and 'man cron'.  Check with you system administrator
before setting up the crontab job.

* Please see knownBugs.txt for a cron related bug in this distribution.

E. Supporting the WEDS project

The WEDS framework has been under development since August of 1996.
It has been primarily implemented by senior electrical and computer
engineering students Dogu Arifler, Chi Duong, Saleem Marwat, and Chris
Moy at UT Austin as part of their senior design projects.  The project
has received help from Dogu Arifler, Srikanth Gummadi, and Jun Huang
during the 1997-1998 academic year while they were graduate students.

If you are interested in supporting this project, then please contact
Prof. Brian L. Evans at bevans@ece.utexas.edu or (512) 232-1457.


F. Acknowledgements

Beginning September 1, 1997, this project has received support
from the Defense Advanced Research Projects Agency (DARPA) and the
United States Army on the Composite CAD Program under DARPA Contract
DAAB07-97-C-J007, and the National Science Foundation through
a CAREER Award under Grant MIP-9702707.
