EVBU - An Open Source 68HC11 Simulator

Andrew Sterian
Padnos College of Engineering & Computing
Grand Valley State University

Introduction

The Motorola 68HC11 is a popular microcontroller and several evaluation boards are available (including Motorola's original board, known as the EVBU) for exploring the capabilities of this microcontroller. This software is a 68HC11 simulator that emulates many aspects of an EVBU with a 68HC11 running the BUFFALO monitor program. The user interface to EVBU is similar (but not identical) to what a user would experience using a terminal program connected to the EVBU hardware. EVBU is free software licensed under the terms of the GPL.

In addition to a command-line emulation of BUFFALO, the EVBU software provides a logic-analyzer-like interface to the 68HC11 port pins. This allows you to view output waveforms and to construct and view input stimulus waveforms.

The main goal of the EVBU software is to aid in the understanding of the 68HC11 and of various concepts in digital systems. It is not the goal of EVBU to be a fast, complete, all-singing-all-dancing simulator (investigate THRSim11 or UMPS if you are looking for one). Only some of the 68HC11 peripherals are implemented. Thus, EVBU is intended mostly as a teaching tool, although it is a fairly capable simulator. The execution speed is on the order of 500X real time for an 8 MHz 68HC11. That is, it takes about 500 seconds to simulate 1 second of real time (on a 1 GHz Pentium processor). Improving the speed of the simulator is not a major goal of the project.

EVBU is written in pure Python and uses the wxPython graphical framework. It should run on any platform that supports the above applications. EVBU was developed with Python 2.1.1 and wxPython 2.3.2. Earlier versions of Python and wxPython may work, but there are no guarantees. Note that on Unix systems, wxPython currently requires GTK, so make sure this package is installed. Also note that wxPython's version is closely tied to the Python version, so if you need to upgrade your Python installation, you will probably also need to upgrade wxPython.

The EVBU program offers several enhancements over the actual BUFFALO monitor:

• Logic levels at output port pins can be displayed graphically, and input port pins can be stimulated with user-constructed waveforms.
• Symbolic debugging is supported. Breakpoints can be set at labels rather than addresses, tracing through instructions also shows each source line, etc.
• Tracing through instructions shows the next instruction to be executed, not only the one that just executed.
• Debugging commands not found in BUFFALO include executing to the end of a subroutine and executing for a specified number of cycles.
• Numbers can be entered in hexadecimal, as in BUFFALO, but also decimal, binary, and octal.
• Cycle counting is implemented for timing algorithms or to execute code for a certain number of cycles.

You can download the latest version of EVBU from:

Note that EVBU actually comes in two parts: PySim11, a Python package that is the actual simulation engine, and EVBU, another Python package that implements the interface to this engine. Both packages work closely with each other and will simply be referred to as "EVBU" in this document.

Installation

First, install Python 2.1.1 or later and wxPython 2.3.2 or later. If you already have the above packages (but in older versions) try running EVBU and see what happens...you may not need to upgrade.

Windows

Run the evbu0.5.exe installation program. I will assume you choose all of the default installation options. The installer will create and populate the following directories:

c:\python21\evbu
c:\python21\pysim11
c:\python21\lib\evbu

The above assumes you have Python installed in C:\Python21. The first two directories are where the simulator modules are located. The last directory contains the documentation, example files, etc. Also in this last directory is a sample batch file EVBU.BAT which shows you how to run the EVBU program.

Unix

Extract the evbu0.5.tar.gz file then install as follows:

python setup.py install

The installer will create and populate the following directories:

/usr/local/lib/python2.1/site-packages/evbu
/usr/local/lib/python2.1/site-packages/PySim11
/usr/local/lib/EVBU

The above assumes your Python library directory is as indicated (it may be elsewhere but the installer should be able to find it, so don't worry about it). The first two directories are where the simulator modules are located. The last directory contains the documentation, example files, etc. Also in this last directory is a sample shell script evbu which shows you how to run the EVBU program.

Running EVBU

Windows

If Python has been registered as the official handler of .PY files, then you should be able to just create a desktop link to the evbu.py file, and clicking on the link will start EVBU. Right-click on the desktop, select "New-->Shortcut..." and Browse to find the evbu.py file. Give it a shot...it'll probably work.

Otherwise, you run EVBU by invoking the Python interpreter on the evbu.py file of the evbu package. For example:

c:\python21\python c:\python21\evbu\evbu.py

Pretty painful, huh? The idea is that you put the above in a batch file and place the batch file somewhere on your PATH. The EVBU.BAT file that comes with this software contains a line like the above (which you can customize to your own installation). Place the EVBU.BAT file somewhere on your path...C:\WINDOWS is probably a safe bet. Open a command window (a.k.a DOS box) and type "echo %PATH%" (no quotes) for more ideas of where to place this batch file.

Unix

You run EVBU by invoking the Python interpreter on the evbu.py file of the evbu package. For example:

python /usr/local/lib/python2.1/site-packages/evbu/evbu.py

The evbu shell script that comes with this software contains an example for running EVBU, modelled on the above. Place this shell script on your path. I suggest /usr/local/bin if you have write permission, or $(HOME)/bin if you do not (and make sure $(HOME)/bin is on your path).

Limitations

The limitations of EVBU are partially intentional (to preserve similarities with the spartan BUFFALO interface) and partially due to the goals of the software. The current limitations are listed below; ongoing development may chip away at them over time.

• Only a subset of 68HC11 peripherals is supported. This includes output compares, input capture, RTI, timer overflow, and the pulse accumulator. Not supported are strobes and handshakes, SCI, SPI, EEPROM, IRQ/XIRQ, and A/D.
• All memory is readable and writable. There are no ROM or EEPROM limitations.
• The program simulates some of the BUFFALO subroutine entry points such as OUTSTR, HEXBIN, etc. but not all of them.
• The command line interface of the EVBU program was designed to be similar to the BUFFALO interface on EVBU hardware, but they are not identical. Several of the differences are considered enhancements, while others are simply due to laziness. There is, for example, no assembly of instructions supported by the 'ASM' command, just disassembly.

Usage Notes

Program Options

The '-h' option prints a brief summary of available options. The starting address can either be set manually using the 'RM' command, or via the S19 file using the 'END' directive, or via the '-s' EVBU option. The '--use-swi' option allows your program to use SWI for its own purposes and does not return control back to the simulator. The '--no-buffalo' option does not install the BUFFALO service subroutines and interrupt vectors. The '--no-timer' and '--no-pio' options prevent the timer and parallel I/O peripherals, respectively, from being included in the simulation and speed up execution.

Command Line Interface

If you are familiar with the BUFFALO monitor, you should find the interface of this software to be familiar. The best documentation for the command line interface is obtained by typing 'help command' for the command of interest. Typing 'help overview' gives a list of commands. Some commands have the same name as the BUFFALO counterparts but are slightly different. The LOAD command, for example, is not 'LOAD T' as in BUFFALO but simply 'LOAD FILENAME.S19' which loads an S19 file directly into memory. More information is available in the BUFFALO Commands section.

New commands worthy of investigation are:

• S -- This command skips the current subroutine. That is, it executes instructions up to the address most recently pushed on the stack.
• STOPWHEN -- This command executes instructions for a certain number of cycles.
• CYC -- Display or reset the instruction cycle counter
• PRINT -- Display hexadecimal and decimal equivalents of integers (such as binary) or symbols (if a MAP file is loaded)
• TN/TY -- Like the trace command 'T' but the next instruction, if it is a branch, is unconditionally skipped ('TN') or taken ('TY').
• PSHB/PSHW -- This command pushes data on the stack to support the testing of subroutines.

The trace command 'T' displays the instruction that just executed along with the register values after execution, just like BUFFALO, but then also displays the next instruction that will be executed. This may be confusing at first but I believe it makes debugging much easier.

The point behind the 'TN' and 'TY' commands is to help test various paths through your program without a lot of work. For example, if you have a 'BRSET' instruction testing the state of an external port pin, you can use 'TY' to simulate the effect of having the pin set and the branch taken.

Symbolic Debugging

EVBU supports loading MAP files in the format generated by the -MTA option (i.e., generate an ASCII map file) of the ASM11 freeware 68HC11 assembler. When the 'LOAD' command is issued, the S19 file name has its extension replaced to .MAP and the corresponding file is sought in the same directory. If it exists, it is automatically loaded. The 'LOADMAP' command can also be used to load a specific MAP file.

When a MAP file is loaded, the symbols in the file are available as constants. For example, rather than setting a breakpoint by using an absolute address, a symbol name can be used instead. NOTE: Symbol names in EVBU are case-insensitive. Do not enable the -C option of the ASM11 program to allow case-sensitive labels.

The MAP file also contains line number information from the source file. When a MAP file is loaded, the 'L' command will display source code surrounding the line that represents the current value of the program counter. Similarly, tracing through instructions with the 'T' command will display source lines.

BUFFALO Subroutines

Many of the BUFFALO subroutine entry points such as OUTSTR and HEXBIN are supported using "virtual functions." This is a concept supported by PySim11 which traps execution at certain addresses and rather than executing 68HC11 code invokes a Python function instead, then issues a simulated RTS instruction. For example, the following 68HC11 assembly code:

OUTSTR    EQU $FFC7
          LDX #hello
          JSR OUTSTR
          SWI
hello     FCC 'Hello!'
          FCB 4,13

will print the string 'Hello!' just as it would under BUFFALO. This support of BUFFALO also extends to the interrupt table. A secondary interrupt table is created at $00C4 which contains a list of JMP instructions to interrupt service routines, as with the actual BUFFALO monitor.

Copyright & License

Copyright © 1999-2002 Andrew Sterian. All Rights Reserved. mailto: steriana@claymore.engineer.gvsu.edu

Both EVBU and PySim11 come with ABSOLUTELY NO WARRANTY. This is free software licensed under the terms of the GNU General Public License. You are welcome to redistribute this software under certain conditions. For more details, see the previous link.

To Do

1. Thorough testing.
2. Loading of symbols from GCC-generated code.
3. IRQ and XIRQ
4. A/D converter
5. Apply memory protections to the PySim11 engine to emulate the 68HC11E9 and display 'rom' or raise an exception when non-RAM is written to.
6. Allow entry of expressions rather than just constants
7. Better breakpoint handling: one-time-only breakpoints, breakpoints with conditions and expressions, actually using the count field of a breakpoint to stop only after some hits, automatic actions on breakpoint hit, breakpoints on memory changes, etc.
8. Better documentation, tutorial, more examples.

Credits

This help file is based on a template for the help file for mxTools by M.A. Lemburg. This software was created with VIM; thanks to the authors of this program and special thanks for the Python syntax support. Thanks to Tony G. Papadimitriou for his freeware ASM11 assembler. Thanks to Mark Wicks for finding bugs and contributing patches. Thanks to the wxPython and wxWindows authors for great Open Source contributions, and, of course, to the Python developers and support community.

History

Version 0.6 -- July 17, 2004

• Fixed an error with the implementation of the inchar() BUFFALO function.
• Added cd command to change directories.
• The up-arrow and down-arrow keys now recall previous commands.
• Pressing the ESC key now clears the input buffer.
• Commands may now be in uppercase or lowercase.
• The File menu has a new Load option (with hotkey Ctrl-L) to bring up a dialog box for loading an S19 file.

Version 0.5 -- March 10, 2002

• Major changes to implement a graphical interface. The main improvement is the logic analyzer display.
• New peripherals: parallel I/O, input capture, pulse accumulator (disabled using the new --no-pio option).
• More documentation
• Switched to Distutils distribution and installation
• The --no-timer option didn't work.
• Removed the -g option (it doesn't make as much sense with a GUI).
• The LSR instruction in extended mode did not work.

Version 0.4 -- June 15, 2000

• Added support for the timer and related peripherals (TOF, RTIF, output compares, TCNT register). This can be disabled (for faster program execution) using the new '--no-timer' option from the command line.
• Interrupts are now supported. Timer overflow, for example, will generate an interrupt if the TOI bit is set.
• On-chip registers are now supported (only for supported peripherals).
• Fixed bugs that prevented branching or memory accesses across the 16-bit address boundary.

Version 0.3 -- May 10, 2000

• Fixed implementation of ROL, ROR, DAA, FDIV instructions
• H bit was incorrectly set after 8-bit addition instructions
• RM command caused an exception when trying to modify the D register
• Support for the BUFFALO service routines INCHAR and INPUT on Unix systems was contributed by Mark Wicks (untested).

Version 0.2 -- February 29, 2000

• Added PSHB/PSHW commands
• Interrupt vectors now point to BUFFALO pseudo-vectors rather than being all zeros.
• Error in BUFFALO HEXBIN service routine failed after internal SHFTREG quantity exceeded 16 bits.
• Added a big kluge to ignore the case when the INCHAR Buffalo routine was called, the ENTER key was pressed, and this character lingered to the time the raw_input() function was called in the Cmd loop, thus causing the previous command to be reissued against the user's will. For some reason, sys.stdin.flush() has no effect. This kluge involved modifying the stock cmd.py a bit hence it has been included in the EVBU distribution.

Version 0.1 -- December 30, 1999

• Initial release