Commands

The simulator works by adding commands to the Tcl language, therefore you can use all of the Tcl commands or variables. The simulator commands are:

• load_s29, reloadFile to load/reload .s29 680x0 binary files

• runStep, runNoSub, runGo, runStop to run the code,

• change, register to modify register contents

• dis, md1 (same as md), md2 to dump memory,

• meminfo to display memory map

• asm to assemble one single instruction

• poke, pokew, pokel, pokea, peek, peeka to write/read memory,

• bkpt to manage breakpoints,

• genIPL, confIPL, initexception, exception to manage interruptions,

• memin, memout to save/load memory to/from file,

• addmemory, addinterface, start to configure the system

• ExceptionHook is a Tcl procedure executed when an Exception occurs. It is used to implement the TRAP system library calls

• clrinfo to clear the info window

Loading an executable

These commands load binary code into the memory. Features vary according to the format of the loaded file.

Loads an S-Format binary program. This format is very elementary and does not include any symbols information. Text section is set to the beginning of the binary file as well as PC. Data section is arbitrarily set to $700.

Reloads the current loaded .s29 file. Useful to refresh the memory after a new version has been assembled.

Load a 68000 executable and view the symbols included in the program. The optional parameter is to specify where to put the .data section. The program try to put it at the right place, but if an error occurs, you can force it to put the data at a given address.

After loading the code, the .text section is disassembled, dumped in dumping window 2, the .data section is dumped in window 1. All the register are clear. The Status Register is set to 0x2700. The USP and SSP pointers are set with specified default values (0x800 for USP and 0x700 for SSP, but you can change them either with the change or the register command or simply click the left mouse button on it and enter directly their new value. The exceptions table is reset to default values, and finally the interrupt are configured (auto-vector or not).

Cmd : load test.exe
=$>$ File 'test.exe' loaded at 0x00001000 (entry at 0x00001012).
Data at 0x00007000.

Reload the same executable. Useful to rerun the program.

If no argument, the command shows the table of symbols (where is located each label). If you give the name of a label, the command returns the address of this symbol. If you give an address, the command return either the name of the label located at this address if any or tells you that there is no symbol.

Cmd : assoc
=$>$ At 0x00001000 is located 'start' (text)
At 0x0000101E is located 'end' (text)
At 0x00007000 is located 'text' (data) Cmd : assoc text
=$>$ Symbol 'text' located at 0x00007000. Cmd : assoc www
=$>$ Unknow symbol 'www'. Cmd : assoc 0x101e
=$>$ Symbol 'end' located at 0x0000101E.

Viewing code and memory

These commands allow you to disassemble code and dump memory.

Disassemble memory in source window. You must specify the start address which can be an absolute address, a label, or a register (d0-d7,a0-a6,usp,ssp,pc). You can also specify how much bytes to disassemble (the default is 256 bytes).

Cmd : dis start
=$>$ Disassembled from 0x00001000 to 0x00001064. Cmd : dis 0x2345 Cmd : dis d0 same as dis [expr $d0] Cmd : dis [expr $pc - 10]

Dump memory in a dumping window. There are 2 commands : md (or md1) to use the first window (on the left) and md2 to use the first window (on the right). You must specify the start address which can be an absolute address, a label, or a register (d0-d7,a0-a6,usp,ssp,pc). You can also specify how much bytes to dump (the default is 160 bytes).

Cmd : md text
=$>$ Memory dumped from 0x00007000 to 0x000070A0 in window 1. Cmd : md2 0x2345 Cmd : md1 [expr $a6 + $d3]

Running the code

These commands are described, but generally you do not use them in command line : just use the buttons in the graphical interface. The description will only be useful for people who want to add new button or write new Tcl procedures.

Run one opcode of the executable.

Run one opcode of the executable, but do not go into subroutine. The skipped opcode are bsr, jsr and trap (including trapv).

This is an internal command which stops the current running program. Only needed if you want to write extensions to the simulator.

Modifying register and memory

You can change the value of register using the change command and memory using the poke commands.

Change the value of the register registerName which can be d0-d7,a0-a6,a7 or usp, ssp, sr, pc. The value is numerical, the name of a label or the name of a register. You can choose the size of the operation using byte, word or long for size (the default is long).

Cmd : change d0 2
=$>$ Value changed. Cmd : change a0 text Cmd : change d0 a0 same as change d0 $a0 Cmd : change d4 [expr $d3 + $d5] word

Change or dump the value of a register. Mostly used as an internal command (the change command above actually calls register). Only useful for people who needs to implement Tcl extensions to the simulator.

Print the memory map: displays the type of memory and its place. Also displays the currently registered Tcl proc for the peripheral circuits.

Put the given byte(s) at the given address which can be an absolute address, a label, or a register (d0-d7,a0-a6,usp,ssp,pc). You are not limited in the number of value.

Cmd : poke 0x1000 1 2 3
=$>$ Poked 3 bytes starting at 0x00001000 Cmd : poke [expr $a0 + 10] 0xFF

Same as poke but use word instead of byte for the value. Cmd : poke text 1 2 3
=$>$ Poked 6 bytes starting at 0x00007000

Same as poke but use long instead of byte for the value. Cmd : poke usp 3
=$>$ Poked 4 bytes starting at 0x0000FF00

Allow you to write a string in memory. You can use all the escape characters like in C. Cmd : poke 0x7000 "$\backslash$ttext to poke$\backslash$n"
=$>$ Poked 14 bytes starting at 0x00007700

Give you the content of the memory at address given by where. The size must be byte (the default value), word or long. Cmd : peek 0
=$>$ 0x00 Cmd : peek text long
=$>$ 0x64684520

Dump the content of the memory at address where as a string. End the string at the first null byte unless the end parameter is specified.

Cmd : peeka 0x800
=$>$ The string at 0x800

Assembles the 68010 instruction at address. The syntax of the instruction is the regular syntax of a 680x0 assembler. However, no symbol can be used. The address defaults to PC. If asm is called a second time, then the address default to the address directly following the result of the assembly of the previous invocation. This makes it easy to assemble instructions which will be located one after the other. The result can be seen immediately in the source window, if address is currently visible.

Cmd : asm 0x800 move #3,D3
=$>$ 0x00000800 363C0003 move #3,D3

Loading or saving memory

You can save the memory and reload it in the following formats : S-record, raw, ASCII, Swift (format used by Cadence © for loading a memory before simulation) and Source (ASCII file that you can fed back to an assembler to assemble).

You must specify the start and end point of the area to save and the name of the file. You specify the format as srecord (the default), raw, ASCII, swift or source.

Cmd : memout 0x1000 0x10FF mem
=$>$ Memory saved in 'mem' (S-record format).

Cmd : memout loop pc mem raw
=$>$ Memory saved in 'mem' (RAW format).

Cmd : memout $a0 [expr $a0+100] code.mem swift
=$>$ Memory saved in 'code.mem' (SWIFT format).

Just give the name of file if it is in format S-record, ASCII, Swift or raw. The command will extract the start and end address and load it in memory. If you use raw format, you must specify all the parameters.

Cmd : memin code.mem
=$>$ Memory load from 'code.mem' (SWIFT format) at 0x00001000.

Breakpoints

You can manage the breakpoints by this command, but clicking in source window to toggle the breakpoint if easier.

If you type the command with no parameters, the list of all the existing breakpoints will be printed. If you specify an address, the command returns 1 if there is a breakpoint at this address or 0 otherwise. This can be used by Tcl extension to test if there is a breakpoint at a given address. If you want to add or delete a breakpoint, just specify the operation (add for adding and del for deleting) and an address which can be an absolute address, a label, or a register (d0-d7,a0-a6,usp,ssp,pc).

Cmd : bkpt
=$>$ Breakpoint at 'start'
Breakpoint at 0x0000101E Cmd : bkpt loop add Cmd : bkpt [expr $pc + 10] add Cmd : bkpt del loop

Interruptions (IPL) and Exceptions

All of the 7 IPL levels can be individually set to vectorized or auto-vectorized mode. Peripheral circuits Tcl extensions can request IPL by the genIPL command and their requests is kept pending until the 68000 process them (SR mask $<$ IPL level request).

With no arguments, this command lists the current configuration/status of the IPL interruptions (vectorized, auto-vectorized, pending, masked). If you specify level, these informations will be returned only for this particular level. If you give auto in addition to the level then the simulator sets this particular level of IPL to auto-vectorized. If you specify a VectorNumber as an 8-bit number, then this particular IPL level is set as vectorized with this VectorNumber.

Cmd : confIPL
=$>$ IPL 1 : Auto-vectored (vector 0) Not Pending - Not Masked
IPL 2 : Auto-vectored (vector 0) Not Pending - Not Masked
IPL 3 : Auto-vectored (vector 0) Not Pending - Not Masked
IPL 4 : Auto-vectored (vector 0) Not Pending - Not Masked
IPL 5 : Auto-vectored (vector 0) Not Pending - Not Masked
IPL 6 : Auto-vectored (vector 0) Not Pending - Not Masked
IPL 7 : Auto-vectored (vector 0) Not Pending - Not Masked

This command can be called by the peripheral circuits Tcl extension to set the vector number before performing a vectorized IPL request, or whenever they want to change the vector number. The vector number is stored by the simulator and will be used when the IPL request will be issued.

Cmd : confIPL 4 200 Cmd : confIPL 4
=$>$ IPL 4 : Vectorized (vector 200) Not Pending - Not Masked

This command issues an interrupt request by setting the IPL pins of the 68000 at the right level. Just give the number of the interrupt to generate (between 1 and 7). The program will show you that you request is registered, in fact the interruption and exception procedure will begin at the next step of simulation.

Cmd : genIPL 4
=$>$ IPL 4 request registered

The command confIPL can also be used to reset a pending IPL request while it is masked or even before it has been processed.

Cmd : genIPL 4
=$>$ IPL 4 request registered Cmd : confIPL 4
=$>$ IPL 4 : Auto-vectored (vector 0) Pending - Not Masked Cmd : confIPL 4 auto Cmd : confIPL 4
=$>$ IPL 4 : Auto-vectored (vector 0) Not Pending - Not Masked

Generate an exception of vector VectorNumber. Extension of the simulator can call this command to generate, for example, BUS ERROR exception in case of illegal access.

Cmd : exception 2
=$>$ Exception (vector 2) : BUS ERROR at 0x00000800

Sets all the exception vectors to address (default to 0x400), write an RTE instruction at address, resets masks and pending exceptions.

This is not a command but the name of a Tcl procedure which can be defined by the user and which will be called (if it exists) each time an exception is processed. This is not called for an IPL, only for Exceptions. The procedure must return either:

1. the address of the next instruction

2. the string "GoOn" to execute the instruction following the one where the exception state has been detected

This can be used to implement specific user-processing. For example the system library TRAP calls are implemented using this procedure. Note that within the procedure, A7 is USP or SSP depending on the mode when Exception happened.

Configuration

These commands are only needed to write configuration file. The standard use of the simulator does not requires them at all.

Add a new physical memory. Give the start and end of the new memory map, and specify the type : ram for RAM or sram for Supervisor RAM (this kind of RAM can be written only in supervisor mode. Used for the exception table for example.).

To define 64K of memory with a supervisor area for the exception table, just use the following commands :

Cmd : addmemory 0x00000000 0x000003FF sram Cmd : addmemory 0x00000400 0x0000FFFF ram

Allow you to define peripheral device. You give an area of memory and the name of a Tcl procedure to call when the 68000 try to read or write at these addresses. Look in section A for more details and a short example.

Tell the program that you have finished with the configuration. Needed to allocate physical memory, so that you could load an executable or do something else.

Controlling the program

With these commands, you can control the program : before and after the execution of each opcode you can put your own commands. For a question of speed, you have better define the procedure beforeOpcode and afterOpcode in all cases : by default just define empty routines.

If flag is 0 you disabled the procedure : nothing will be done between the opcodes. It is useful to turn hook off when you execute a big code because it is faster. If flag is not 0, you force the program to call beforeOpcode and afterOpcode each time.

These procedures allow you to manage specials breakpoints or conditions. The arguments of the procedure are the value of the Program Counter PC and the text of the opcode in opcode as it appears in the source window.

You can access the value of the registers which are called : d0 to d7, a0 to a6, usp, ssp, pc, sr.

These routines are called before the opcode for beforeOpcode and after the execution of it for afterOpcode when you use one of the commands to run (runGo, runStep or runNoSub).