Monster Media 1994 #1/monster.zip/monster/MATH/C25SIM.ZIP/c25sim.doc

Text File | 1994-01-02 | 25KB | 589 lines

########################################################################

THIS IS A FREE DEMO VERSION OF A SIMULATOR FOR THE TI TMS320C25. YOU MAY
USE, COPY, AND DISTRIBUTE IT. PLEASE DO NOT ALTER OR DELETE ANY OF THE
INCLUDED FILES, OR ADD NEW ONES.

########################################################################

The following C25 instructions have been disabled in this version of the
simulator:

APAC LTA LTD LTP LTS MAC MACD MPYA MPYS MPYU SPAC SQRA SQRS

You may use this freeware version all you want. You may use, copy and
distribute it as much as you like, provided that you do not add files to it,
delete files from it, or change its files.

Other than these instructions being disabled, and the prompt in C25SIM.EXE
being "DEMO>" instead of "READY>", this software is identical to the
full-featured C25SIM package. The reasoning behind this approach is to allow
you to make a fully informed decision about purchasing this software. The
C25SIM software includes an OBJ file for the simulator engine so that you
can write a customized simulator specific to your application. You may want
to explore this before making your purchasing decision.

To order the full-featured C25SIM package, send a check or money order for
$120.00 to

    Will Ware
    26 Beacon St., Apt. 34B
    Burlington, MA  01803

Your package will include software that executes all the C25 instructions, a
printed manual, periodic software updates as they occur, and technical
support via electronic mail. My email address is:

    72143,315            for Compuserve

    [e-mail]    for Internet

############################################################################

                    C25SIM

            An Affordable TMS320C25 Simulator

############################################################################

GETTING STARTED

C25SIM.EXE is a menu-based C25 simulator. To use it, type

    c25sim foo

and it will load the files FOO.HI, FOO.LO, FOO.MAP, and FOO.LST. You will
see a "READY>" prompt (the prompt will be "DEMO>" if you're using the demo
version). You can then press F1 to see the help screen, of F2 to see the
source listing. In both the help screen and the source listing, you can
navigate with the Home, End, PageUp, PageDown, and up and down arrow keys.
Any other key will return you to the simulator.

Notice that the C25's registers and flags all appear on the right side of
your screen. Whenever the simulator executes code, these are updated.

Type "symbols" (and press Enter) to see the symbol table. This is extracted
from FOO.MAP. The simulator commands that require numerical arguments will
also accept symbol names, and will look up the value of the symbol.

Type "bp _interrupt_handler" to set a breakpoint at the beginning of the
interrupt handler. FOO.ASM sets up a timed interrupt, which saves the C25's
registers on a stack, increments the _L variable, restores the registers,
and returns to the main program. You will see interrupts occuring about
every 500 processor cycles.

Type "go". This command will cause the simulator to execute code until a
breakpoint is hit, or until you press a key on your keyboard. When the
simulator stops, it will notify you that it reached a breakpoint, tell you
the address, and print the names of any symbols whose values match that
address. You will see:

    READY> go
    Hit a breakpoint at 0053
    _interrupt_handler
    READY>

Type "go" again. The simulator will continue executing until it hits the
same breakpoint again. Type "rd _L" to read the data memory value at the
address for the _L variable. Type "go" and "rd _L" a few more times to see
that the interrupt handler is indeed incrementing _L.

The timer is displayed on the right side of the screen, by the name TIM. The
PRD register, or period register, is used to reload the timer after it
counts down to zero. At this point, TIM will have a value close to 0x1F4,
since it was recently reloaded when the interrupt occured. Type "cycles 100"
to run the simulator for 100 processor cycles. The value of TIM will be
around 0x190 at this point, indicating that it will time out in about 400
processor cycles.

############################################################################

THE HELP SCREEN

The following two pages are the help screen, which is the file C25SIM.HLP,
displayed in C25SIM.EXE when you press the F1 key. This is always available
while you are using the simulator. For your convenience, a copy of the help
screen follows.


QUICK COMMAND REFERENCE
load        Load hex and map files
listing        Load listing file (default extension: LST)
wp        Write program memory
rp        Read program memory
wd        Write data memory
rd        Read data memory
mr        Modify a C25 register
pwait        Program memory wait state
dwait        Data memory wait state
bp        Set a breakpoint
clrbps        Clear all breakpoint
go        Run N steps or until next breakpoint
cycles        Run for N processor cycles
reset        Reset the C25
bkgnd        Run C25 continuously as background process (or stop)
int        Manually trigger an interrupt
symbols        Show symbol table
match?        Find all global labels matching current PC
quit        Quit this program

Use Home, End, PageUp, PageDown, and up and down arrows to navigate, any
other key returns to the simulator.

Function keys:    F1 => view this help file
        F2 => view source listing file
        F3 => view symbol table
        F4 => execute one instruction (active only in simulator)
        F5 => string search (active only in viewer)
        F6 => repeat string search (active only in viewer)

MORE DETAILS ON COMMANDS

Commands are case-insensitive. "WP", "Wp", "wP", and "wp" are all valid.

Many commands take numerical arguments. Numbers are interpreted as decimal
by default, and are interpreted as hexadecimal if they have the prefix "0x",
as in C. Numerical arguments can be decimal numbers (29), hexadecimal
numbers (0x1234), or global symbols defined in the MAP file. Assuming there
is a global symbol "_interrupt_handler", these would all be acceptable ways
to set a breakpoint.

    bp 0x53
    bp 83
    bp _interrupt_handler

"Go" takes an optional numerical argument. If no argument is used, "go" will
execute code until either a breakpoint is hit, or a key is pressed on the
keyboard. If an argument is given, "go" will stop on either of those
conditions, or when that number of instructions have been executed.

"steps" and "cycles" each take a number, respectively specifying how many
instructions or processor cycles to execute.

"wp" and "wd" take two numerical arguments, an address followed by data.

"bp" takes on numerical argument, an address, and sets a breakpoint there.

"rp" and "rd" take an address, and optionally a second address. If two
addresses are specified, then a range of memory values is displayed, up to
but not including the second address, for example:

    READY> rd 0x1C00 0x1C10
    Data memory
    1C00 - 1234 5678 0246 1357 1234 5678 0246 1357
    1C08 - 1234 5678 0246 1357 1234 5678 0246 1357

"load" takes a filename, and loads Intel hex files for C25 code, and a Texas
Instruments map file, if one exists. For more details, see the description
below of the functions load_hex_files() and load_map_file().

"listing" takes a filename, and loads a new source listing file. This can be
viewed by pressing the F2 key. While in the listing view screen, you can
navigate with Home, End, PageUp, PageDown, and the up and down arrow keys.
Press any other key to return to the simulator. If the simulator is invoked
with a filename argument, it will try to load a listing file automatically.
If the argument is "FOO", the simulator will look for "FOO.LST". If an
extension is specified, it will use that.

"symbols" prints the symbol table (extracted from the MAP file), showing the
names of globally defined symbols and their hexadecimal values.

"match?" prints the names of all globally defined symbols whose values match
the current PC.

"mr" takes the name of a register, followed by a new value to assign that
register. The valid register names are: arp ov ovm intm dp arb cnf tc sxm c
hm fsm xf fo txm pm pc t sp ar0 ar1 ar2 ar3 ar4 ar5 ar6 ar7 bio acc p drr
dxr tim prd imr greg.

"pwait" and "dwait" set up wait states for ranges of program and data
memory. To specify a range of program memory with two wait states from
address 0x800 to 0xFFF, type "pwait 0x800 0xFFF 2". "dwait" works the same
way for data memory. Up to twenty ranges can be specified for program
memory, and another twenty for data memory.

"int" takes an interrupt type name, and manually triggers an interrupt of
that type. The valid C25 interrupts are: RS, INT0, INT1, INT2, TINT, RINT,
XINT, TRAP.

MORE DETAILS ON THE FILE VIEWER

The file viewer lets you conveniently view text files from the simulator.
At any time while simulating, you may press the F1 key to view this help
file, the F2 key to view the source listing, or the F3 key to view the
symbol table. When in the file viewer, you can navigate using the Home,
End, PageUp, PageDown, and up and down arrow keys.

Within the file viewer you can search for a string of text. Press F5 and
you will be prompted for the string to be searched for. The first line, at
or after your current position, that contains that string will be moved to
the top of the screen. When you press the F6 key, the next line containing
that string will be moved to the top of the screen. If the string is not
found, a warning to that effect will appear.


############################################################################

HOW TO ASSEMBLE AND LINK FOO.ASM

Files with the prefix FOO are some sample C25 code, which were assembled and
linked with TI's C25 assembly language tools. The procedure for assembling
FOO.ASM is illustrated below. On the distribution disk, you will find
FOO.ASM, FOO.LST, FOO.CMD, FOO.HI, and FOO.LO. FOO.HI and FOO.LO are Intel
hex files that can be used to program high-byte and low-byte EPROMs.

    dspa foo.asm foo.obj foo.lst
    dsplnk foo.cmd foo.obj -m foo.map
    dsprom -intel a.out foo
    del a.out

############################################################################

WHAT DOES FOO.ASM DO?

FOO.ASM exercises the C25's timer, interrupts, bit-reversed addressing mode,
and idle mode. The results of all this appear in two address registers, AR4
and AR5, and in three data memory locations labelled "_i", "_k" and "_L".
There is also an array of data memory locations called "rstring" used for
the recieve interrupt.

First FOO establishes AR1 as a stack pointer, and sets up a timed interrupt
to occur every 500 processor cycles. rstring is initialized to zeros. AR4,
AR5, _k, and _L are then initialized to zero. FOO then enters a loop (L1),
where it respectively increments and decrements AR4 and AR5 using
four-bit-wide bit reversal, and goes on to call a do-nothing subroutine.
After the subroutine call, FOO sets _i to zero and enters an inner loop (L2)
which will run ten times using AR0 as a loop counter. Inside the L2 loop, _k
is set to 17 times _i, and then _i is incremented. After the L2 loop runs
ten times, FOO calls a subroutine which checks the value of _L, and executes
an IDLE instruction if _L has reached 15. _L is incremented periodically by
the timed interrupt.

There is also a receive interrupt which fills rstring with incoming data.
When a data word of zero is received, rstring is refilled with zeroes and
the receive interrupt starts at the beginning again.

############################################################################

WHAT DOES SAMPLE.C DO?

SAMPLE.C is an example of how to use the simulator library functions to
write a special-purpose simulator. SAMPLE looks specifically for changes in
_k, _L, AR4, and AR5, and reports the changes, and how many processor cycles
have passed when they occur. SAMPLE reports when interrupts occur, and when
the C25 hits an IDLE instruction.

SAMPLE also simulates the operation of the C25's serial port by writing the
DRR register and triggering periodic receive interrupts.

As SAMPLE is running, you may:
    Press the 'Q' key to quit and return to DOS,
    Press 'R' to get a full report of the C25's registers, flags,
        and status
    Press 'M' to toggle a mode bit which is initialized to zero.
        When the mode bit is one, changes in _k, _L, AR4, and AR5
        are displayed on your screen.
    Press 'S' to print the current contents of rstring, which is filled
        by the receive interrupt with characters from the string
        "Supercalifragilistic".
    Press any other key to pause SAMPLE and get a shorter report
        of C25 status


############################################################################

WRITING A CUSTOMIZED SIMULATOR

C25LIB.OBJ is a library of routines for creating your own simulator very
easily. The effort of doing a small amount of C programming will be vastly
offset by the flexibility of being able to design a simulator specifically
to address your own application.

SAMPLE.C is an example C program that illustrates how to use the routines in
C25LIB.OBJ. SAMPLE.C was written specifically in conjunction with FOO.ASM.
The variables and routines available in C25LIB.OBJ are spelled out in the
header file C25LIB.H.

C25LIB.OBJ was compiled using the Microsoft C Compiler version 6.00A. You
can link it to your own Microsoft C program by typing:

    cl yourcode.c c25lib.obj

C25LIBT.OBJ was compiled with Borland Turbo C version 2.01. You can link it
to your Turbo C program by typing:

    tcc yourcode.c c25libt.obj

############################################################################

IMPORTANT THINGS

A.    Your code must call the routine initialize_simulator() before
    attempting to execute any C25 code. This routine initializes the
    table that allows the simulator to disassemble and execute C25
    instructions.

B.    To accomodate the windowing done in C25SIM, all the simulator
    library functions route their printed output thru the routine
        void __write(char *);   /* two underscores */
    which you must provide. For many applications, you can simply
    use the following definition, taken from SAMPLE.C:
        void __write(char *s) { printf("%s", s); }

############################################################################

1. Registers and Flags

The C25 flags and registers are as follows, and are available to be inquired
or altered in your C program.

extern int arp, ov, ovm, intm, dp;
extern int arb, cnf, tc, sxm, c, hm, fsm, xf, fo, txm, pm;
extern long int accumulator, p_register;
extern unsigned int pc;
extern int t_register, _stack[8], _sp, ar[8];
extern int mp_mc_mode;
extern int ports[16], bio;
extern int drr, dxr, tim, prd, imr, greg;

All the C25's registers and flags are available as variables in C. Most of
these variables are 16 bits (int). The accumulator and the P register are 32
bits (long int). The following registers are odd lengths: ARP (3 bits), DP
(9 bits), ARB (3 bits), and PM (2 bits). The upper bits of these registers
are ignored by the simulator. The following flags are only one bit, and the
upper 15 bits are ignored: ov, ovm, intm, dp, cnf, tc, sxm, c, hm, fsm, xf,
fo, txm, mp_mc_mode, bio. xf and bio are external pins on the C25.
mp_mc_mode is also an external pin, which determines whether code is fetched
from the C25's internal ROM (microcontroller mode) or from external ROM
(microprocessor mode). By default it is set to 1, indicating that the C25 is
in microprocessor mode.

############################################################################

2. Steps and Cycles

extern unsigned long int steps_taken, cycles;

There are two long integers that mark time in the simulator. "steps_taken"
measures how many instructions have been executed. Repeated instructions
(controlled by the RPT or RPTK instruction) will not count: only the repeat
instruction itself will be recorded. "cycles" measures the actual execution
time for your code, in processor cycles. If you clock your C25 at 40 MHz,
each clock cycle is 100 nanoseconds.

############################################################################

3. Wait States

typedef int (*iufunc) (unsigned int);
iufunc pwaitf, dwaitf, iwaitf;

C25SIM normally assumes that all memory is zero-wait-state. This assumption
can be easily changed to match your hardware. This affects the "cycles"
variable. There are three pointers to functions: pwaitf, dwaitf, iwaitf,
respectively regarding program memory, data memory, and I/O ports. These
pointers are initialized to NULL. To simulate non-zero-wait-state memory,
write a C routine that accepts an unsigned integer (a memory address) and
returns an integer (the number of wait states for writing or reading that
address), and assign the appropriate pointer to point at that function.
Here is a sample usage.

/* convenient way to specify memory address ranges */
#define ui(x)  ((unsigned int) (x))
#define range(x,lo,hi)  ((ui(x) >= ui(lo)) && (ui(x) <= ui(hi)))

int program_wait_states(unsigned int addr)
    {
    /* a small block of REALLY slow memory */
    if (range(addr, 0x100, 0x1FF)) return 10;
    /* everything else is zero-wait-state */
    return 0;
    }

void main(void)
    {
    initialize_simulator();
    ....
    pwaitf = program_wait_states;
    ....
    /* run simulation */
    }

############################################################################

4. Accessing Program and Data Memory from C

extern int warn_progmem_writes;

extern int *program_memory_address(int a);
extern void write_program_memory(int a, int d);
extern int read_program_memory(int a);

extern int *data_memory_address(int a);
extern void write_data_memory(int a, int d);
extern int read_data_memory(int a);

As you load code into the simulator, C25SIM allocates blocks of your PC's
memory to function as blocks of virtual C25 program memory. Likewise, when
your code starts using data memory, C25SIM allocates PC memory for virtual
data memory. If you want to write or read C25 memory directly, you can use
program_memory_address() and data_memory_address() to convert C25 addresses
to PC addresses (pointers to integers).

Alternatively, you can use write_program_memory() and read_program_memory()
to access program memory, and write_data_memory() and read_data_memory() to
access data memory. The only difference in using these functions is that
they will warn you if you are reading uninitialized memory, or writing
program memory (a potential bozo no-no in the C25's Harvard architecture).

If you want to use write_program_memory() to write to program memory without
getting warnings, set warn_progmem_writes to zero. By default it is set to
one, and is only cleared temporarily when hex files are loaded.

############################################################################

5. Starting the simulator, stepping the simulator

extern void initialize_simulator(void);
extern void advance(void);

initialize_simulator() sets all the simulator's registers, flags and
variables to zero, except for mp_mc_mode and warn_progmem_writes which are
set to one. It also sets up the table which the simulator uses to
disassemble code as it executes.

     ! ! ! ! ! ! ! !
     NOTE: You *must* run initialize_simulator() before stepping the
     simulator. Otherwise the simulator will not recognize any C25
     instructions.
     ! ! ! ! ! ! ! !

advance() causes the simulator to execute one instruction.

When executing any repeated instruction, the "steps_taken" variable will
only be incremented once. The "cycles" variable will be incremented thru the
correct number of processor cycles that would physically occur.

############################################################################

6. Loading files, using global symbols

extern void load_hex_files(char *word);

extern void load_map_file(char *word);
extern int lookup_symbol(char *name);
extern void print_matching_symbols(int d);

load_hex_files() loads executable C25 code into the simulator.

If your code is in high and low Intel hex files (e.g. for programming 8-bit
eproms), with the filename extensions "HI" and "LO" respectively, then you
can load both files by calling load_hex_files() and passing it the prefix of
the filename (everything up to, but not including, the period).

If your code is a single Intel hex file with 16-bit data, with highbytes
followed by lowbytes, you can load it by specifying an entire filename, with
the only restriction that the filename extension must be "HEX".

If your code was linked with TI's C25 linker, and you produced a map file,
you can load the names and values of all globally defined symbols (routines,
labels, and variables) using the function load_map_file(). Pass the filename
as an argument; if no filename extension is given, the function will assume
it is "MAP".

Once the symbols are loaded, you can look up the value of a symbol with the
function lookup_symbol(), which takes the symbol's name as a string and
returns the value as an integer. Another handy function is
print_matching_symbols(), which accepts an integer and prints the names of
all symbols with that value. This can be handy for identifying your location
in some code.

############################################################################

7. Breakpoints

The current version of C25SIM supports 100 breakpoints.

extern void add_breakpoint(int d);
extern void delete_breakpoint(int i);
extern void clear_all_breakpoints(void);
extern int go_til_breakpoint(long int n);

add_breakpoint() will set up a breakpoint at an address in program memory,
and delete_breakpoint() will delete a breakpoint at an address, if one
exists. clear_all_breakpoints() will delete all existing breakpoints.

The function go_til_breakpoint() accepts a numerical argument n. If n = -1,
then go_til_breakpoint runs C25 code until either of two conditions:
    1. the simulator hits a breakpoint,
        in which case go_til_breakpoint returns -1,
    2. or a key is pressed on the PC's keyboard,
        in which case go_til_breakpoint returns the ASCII
        value for the key that was pressed.
If n is not -1, then go_til_breakpoint will also terminate on a third
condition:
    3. n instructions have been executed,
        in which case go_til_breakpoint returns -2.

############################################################################

8. Resets and Interrupts

extern void c25_reset(void);
extern void c25_interrupt(int n);

These functions are used to reset or interrupt the simulated C25. The C25
has eight kinds of interrupts:

/* Interrupt types */
enum int_type { RS, INT0, INT1, INT2, TINT, RINT, XINT, TRAP };

The RS interrupt is simply a processor reset. The TRAP interrupt is normally
invoked by a software instruction. RS and TRAP are non-maskable interrupts.
The timer can be configured in the C25 code to provide timed interrupts
(TINT).

The simulator does not attempt to model the C25's on-chip serial ports. You
can model a receive-buffer-full event by loading a value into the "drr"
variable and then performing a RINT interrupt. Likewise you can simulate a
transmit-buffer-empty event by triggering a TINT interrupt. If you are using
the serial ports, your code will probably want to respond by loading the
"dxr" variable with data to be shifted out.

If an interrupt is not enabled when c25_interrupt() is invoked, a flag is
set to record the fact that the interrupt is pending, and the interrupt is
triggered as soon as it is enabled.

############################################################################

9. Reporting processor status

void short_report(void);
void long_report(void);

These functions respectively print out short and long reports of processor
status. A short report shows the program counter and the instruction
currently being executed, both in hexadecimal, and the number of
instructions executed and processor cycles both in decimal.

    PC:0096   Instructions executed: 622   Processor cycles: 1000
    Instruction: 70A0    SAR

A long report shows the same information from the short report, plus the
values of the C25's registers and flags. All registers are shown in
hexadecimal, except for ARP, DP, ARB and PM, which are shown in binary, with
a decimal value in parentheses. Single-bit flags are shown as 0 or 1.
Sixteen-bit registers are shown as four digits of hex, and 32-bit registers
are shown as eight digits of hex.

    PC:0041   Instructions executed: 154   Processor cycles: 300
    Instruction: FE80    CALL
    ACC:00000000 ARP:000(0)
    ARs: 000A 0403 0000 0000 0004 0007 0000 0000
    Hardware stack: empty
    OV:0 OVM:0 INTM:0 DP:000001000(8)
    ARB:101(5) CNF:0 TC:0 SXM:0 C:0 HM:0 FSM:0 XF:0 FO:0 TXM:0 PM:00(0)
    T:0000 P:00000000
    DRR:0000 DXR:0000 TIM:00D0 PRD:01F4 IMR:0008 GREG:0000