S21 is a free MS-DOS software simulator for the MuP21 microprocessors.
S21 is available in a s21.zip free file. This file contains the compiler, source code, and executable file, and documentation.
S21 permits evaluation of the operation of the MuP21 cpu at no cost. S21 displays the contents of the simulated chips registers, and permits single stepping of instructions, and the use of breakpoints. Code sequences can be verified, and tested for speed.
S21.EXE is an executable file in DOS, so the command "S21" at the DOS prompt will start the S21 program.
When the program starts the screen will look like this:
PC= 0 PC@= 0 | 0 0 0 0 | 0 0 0 0 .....
^ JMP 0
A= 0 0 0 0 0 <> 0 0 0 0 ........
R3= 0
R2= 0
R1= 0 0 0 0 0 <> 0 0 0 0 ........
R= 0 0 0 0 0 <> 0 0 0 0 ........
T= 0 0 0 0 0 <> 0 0 0 0 ........
N= 0 0 0 0 0 <> 0 0 0 0 ........
S2= 0
S3= 0
S4= 0
S5= 0
0 instructions in 0 nanoseconds
B1= 123456
B2= 123456
B3= 123456 IP Break Point
[COMMANDS: ^ V < > SPACE A B C D F G H L N R S T Z + -]
The program will respond to any of the commands listed on the bottom line of
the S21 screen. Now LOAD a MuP21 program from DOS with the "L" command.
Press the "L" key, and the screen will change to:
Volume in drive C has no label
Directory of C:\FPC350\FOX
DEMO P21 65535 9-27-91 11:11p
TERM P21 65535 9-25-91 2:45p
EF1 P21 65535 9-05-91 7:56p
EF2 P21 65535 9-27-91 2:29p
4 File(s) 4493312 bytes free
InPut the file name and hit
At this point you must enter one of the listed files. The user must enter the
extension (normally P21) with the filename as in the example
"EF.P21". When you hit the return key P21 will return to the debugger.From this point any command listed on the command line can be executed. The "H" key will display the following screen:
MuP21 simulator command help
left move back one 5 bit instruction
right move forward one 5 bit instruction
up increment the current 5 bit instruction
down decrement the current 5 bit instruction
Space Single step current instruction
A Set new ProgramCounter ADDRESS
B Set Breakpoint 1 or 2 or 3
C Copy sequence in memory
D Set consecutive DATA locations in memory
F Forth
G GO execute code till a breakpoint
H MuP21 simulator command help screen
L Load MuP21 instruction file
N NEXT word Increment IP BREAKPOINT and GO
R Set MuP21 Register (A,T,N,S2,S3,S4,S5,R ,R1,R2,R3)
S Save MuP21 instruction file
T Trace On/Off
Z Zero Instruction and Time counters
+ Increment Breakpoint 3
- Decrement Breakpoint 3
HIT ANY KEY TO CONTINUE
PC= 0 PC@= 0 | 0 0 0 0 | 0 0 0 0 .....
^ JMP 0
The first four command keys are the arrow keys. These four keys are the
command interface to the assembler/disassembler for the MuP21 or F21. The top
two lines of the screen, and the four arrow keys are all that are needed
to use the assembler/disassembler. The top line on the S21 screen shows
the contents of the Program Counter (PC= 0). The contents of the
memory location pointed to by the program counter is then shown as
(PC@= 0). Since each word of MuP21 memory can contain up to four
five bit instructions the contents of the memory pointed to by the
program counter is also displayed as four five bit values between 0 and
1F (| 0 0 0 0 |). On the line below the top line an up arrow points
to the five bit instruction that is the next instruction to execute on
the MuP21. The current instruction is disassembled on this second line
after the up arrow pointer.The left and right arrow keys move the pointer to the current instruction forward or backward. The up and down arrow keys increment and decrement the current five bit instruction. Since there are only 32 opcodes on the MuP21 the opcodes wrap around from 1F to 0 and from 0 to 1F.
Following the display of the contents of the memory location pointed to by the program counter as four five bit instructions, the contents of the next four memory locations in the MuP21 are displayed in hex. Following the hex displays these five memory locations are also displayed in ASCII. If the contents of these locations are less than the space character, or if they are greater than 255 only a period is displayed (.....).
Below the Program Counter and instruction memory display on the top two lines of the display are the registers and memory locations pointed to by the MuP21 registers. The names of the MuP21 registers are displayed on the left of the screen. The A or address register is displayed at the top of the register display. Below this is the stack array. The four return stack registers and the five data stack registers are displayed back to back so that the operation of the MuP21 "PUSH" and "POP" instructions can clearly be seen moving data between the two stacks as one register array.
The four locations in memory below the location pointed to by each of the middle four registers is displayed to the right of the register. A "<>" is then displayed, and it is followed by the contents of the location in memory pointed to by the register, and the three locations that follow that in memory. If the register is being used as a stack pointer then the four locations to the left of the "<>" are the top four items on the stack. The number just to the right of the "<>" is the location in memory actually pointed to by the register.
To the right of these eight hex numbers the same eight values are also displayed as ASCII. If the contents of these locations are less than the space character, or if they are greater than 255 only a period is displayed (........).
The SPACE_BAR is the command to single step the current instruction in the MuP21. Note that the function show by the disassembler will be performed when the spacebar is pressed. The time for this instruction to execute will be added to the total time counter just below the display of the registers in the MuP21 (0 instructions in 0 nanoseconds). A simple calculation of the average timing of instructions is displayed after instructions have begun to execute and until 64k instructions have been executed (19 instructions in 455 nanoseconds (ave 43 mips)).
To reset the Program Counter use the "A" command. The "A" command will prompt for a new Address for the program counter.
The "G" command will begin repeated instruction execution until one of the breakpoints is reached, or the "ESC" key is pressed. The program will display each instruction if trace is on, or nothing if trace is off until a breakpoint is reached, or "ESC" is pressed. One can also stop the execution of MuP21 programs by breaking out completely to the FPC Forth environment with the CONTROL_BREAK key. From FPC you can return to the MuP21 environment at the same point that you broke out with the command "CHIP" from the FPC FORTH environment. The "T" key in the P21 program toggles the trace function on and off.
Three breakpoints are provided for MuP21 program debugging. Breakpoints B1 and B2 are set to break to the debugger when the Program Counter value equals the value in either of these breakpoints. Breakpoint B3 is set to break if the value of the "R" register should equal the value in B3. Since the "R" register is used as the interpreter pointer in the MuP21 eForth model the B3 breakpoint is also referred to on the screen as the IP breakpoint. When you press the "B" key the program will prompt for "B1, B2, or B3" and accept a "1", a "2", or "3" key to designate the breakpoint to be set. Then the program will accept a value and set that value into the breakpoint.
The "N" command will increment B3 and perform a "GO". This is a very nice mechanism to trace through high level Forth words as the B3 breakpoint is linked to the "R" register or "IP" interpreter pointer in high level Forth. Do not use the "N" command with Forth words that change the IP such as high level BRANCH words. Also do not use the the "N" command on other words that increment the IP by more than one such as DOLIT that moves the IP past the next location as it reads the data in that memory location. For these instructions use the "+" command to increment breakpoint 3 past a literal, or use the "+" and "-" commands to move to a branch location.
If your code does not reach one of the three breakpoints you have set fairly quickly you should use the "ESC" key or "CONTROL_BREAK" to stop program execution and examine the registers.
Breakpoints 1 and 2 break the program whenever the program counter equals the value in either breakpoint 1 or 2. Breakpoint 3 can break on the value of A, R, or PC. If the variable F21 is set OFF then S21 simulates the MuP21 chip with 6 data stack and 4 return stack locations simulated. With F21 variable OFF breakpoint 3 is set to break on R. This is because R is used for the IP in MuP21 eForth. If the F21 variable is set ON then S21 simulates the F21 chip with larger on chip stacks, and faster timing. With the F21 variable ON S21 sets breakpoint 3 to either the A or PC register. If the variable DTC is also ON then breakpoint 3 is set to A since in Direct Threaded F21 eForth the A register is the IP. If DTC is OFF and F21 ON then breakpoint 3 is the Program Counter since the PC is the IP in subroutine threaded code.
You can reload the program that you are debugging at any time with the "L" command. If you exit to Forth with the "F" command or with the "CONTROL_BREAK" key you can restart with either "CHIP" or "SIM". The Forth command "CHIP" restarts just where you left off. The Forth command "SIM" restarts the simulator and resets some of the registers and variables. If you are in Forth you can exit to DOS with the "BYE" command.
The "C" command prompts for a "FROM" and a "TO" address, and for the number of words of memory to copy.
The "D" command will load consecutive locations in memory with data. It will prompt for the data to be loaded in each word as it increments the program counter which is used as a pointer. The value FFFFF cannot be entered directly as it is the special number that terminates the data entry mode. If you want to enter -1 simply enter a -1. -1 is actually 1FFFFF in a 21 bit register, but memory can only hold 20 bits, so FFFFF will be placed in memory.
All registers execpt the Program Counter are set with the "R" command. The "R" command will only accept the register names that are displayed on the display (A,R3,R2,R1,R ,T,N,S2,S3,S4,S5). After a register has been designated then a value will be accepted and the register value set.
The "S" command SAVES the current MuP21 16K WORD program to a 64K byte DOS file. It will prompt for the DOS Filename. The program will only display files that end with the extension "?21". The program CAN load and save files with any or no extension, but the program will only display files that end in the "?21" extension when it displays the directory.
The default keyboard operation is CHAR_WAIT_OFF. In this mode ?RX will always say that a key is ready, and wait for a key like KEY. If you move to Forth with the "F" command and then type CHAR_WAIT_ON and CHIP to return to the simulator it will go into the slower state. In this mode the simulator will first check to see if a PC key is down, and will return 0 for ?RX is a key is down. When running eForth on the simulator words like WORDS or SEE will check if a key is down, and will abort right away if CHAR_WAIT_OFF is set.
The souce code to the S21 program is in three files. S21.SEQ contains the code that defines the S21 memory space, the simulated X21 registers and all of the instructions for the MuP21. The basic display of the registers and memory is also defined in S21.SEQ. S21FILE.SEQ contains the source code to the words that access DOS files. SIM.SEQ contains the source code for the complete simulator with the breakpoints and all of the commands to the simulator/debugger.
To compile the source code for S21 use the FPC F.EXE file. From DOS type "F FLOAD F21SIM" to compile the three souce programs and save a copy of S21.EXE to disk.