
                              
                     PIC 16CXX Simulator
                              
                              
1. Simulator Overview                                 1
2. Commands                                           3
3. Command Line Options                               5
4. Journal file                                       6
5. Input Stimulus File                                7


1. Simulator Overview

1.1. Description
PSIM is a versatile software simulator for Microchip
PIC16CXX series microcontrollers.  It allows the user to
simulate their code on a PC to verify its proper operation.

1.2. Requirements
PSIM requires an IBM or compatible computer (XT or above)
with at least 400K bytes of free memory to run.  Although
PSIM will function with a monochrome monitor, it is strongly
recommended that a VGA monitor be used to take full
advantage of the features.

1.3. Syntax
PSIM uses the listfile that is produced by various Parallax
assemblers (see assembler documentation for producing
listfiles).  It is also compatible with listfiles produced
by Microchip's PICALC and MPALC and the beta version (0.01)
of the PIC Macro Assembler by Applied Academics.  To start
PSIM, type "PSIM filename" at the DOS prompt, where filename
is the name of the listfile that you would like to simulate.
The file extension ".lst" can be omitted -- the ".lst"
extension is assumed by default.  If there are no errors,
PSIM will load the listfile and display the source code in
the lower half of the screen.  The microprocessor's internal
registers (files) are displayed in the upper half of the
screen.  The bottom line of the screen lists the function
key commands.

1.4. Device Type
PSIM determines the device type being simulated (e.g.,
PIC16C54, 55, 56, 57, 58, 71, 84) by a variety of methods.
The recommended method is to include the "device" directive
in source code (see assembler instructions for details).
The simulator locates the "device" directive in the list
file and sets the device type accordingly.  If the "device"
directive is omitted, the simulator will determine the
device type by the type of the list file and the amount of
program ROM that is used by the source code.  If there are
no instructions above address 1FFH hex, the PIC16C54 is
assumed.  If there are instructions higher than 1FFH but not
higher than 3FFH, the PIC16C56 is assumed.  If there are
instructions above 3FFH than the PIC16C57 is assumed.

Another method to select the device type is to include it in
the command line preceded by "/d=".  Examples are as follows
(they are all equivalent):
          PSIM filename /d=PIC16C54
          PSIM filename /d=PIC54
          PSIM filename /d=54

The final method for selecting the device type is to use the
Alt-D command from within the simulator.  Pressing Alt-D
will pop up a menu where you can use the up and down arrow
keys to select the desired device.  Press enter when the
desired device is highlighted.  Keep in mind that the
PIC16C5X and PIC16C71/84 are not object code compatible.  If
the device is set to PIC16C71 while simulating PIC16C5X
code, unexpected results will occur.

1.5. Crystal Frequency
The simulator uses a crystal frequency value to calculate
the instruction cycle time.  The crystal value can be
entered by one of two different methods.  The first method
is to enter it on the command line after the filename
preceded by "/x=".  Upper or lower case characters are
allowed.  Allowable suffixes are "MHz", "kHz", and "Hz".  If
no suffix is entered, it is assumed to be in Hertz
(cycles/second). Some examples are as follows:

          PSIM filename /x=4MHz
          PSIM filename /x=3.12MHz
          PSIM filename /x=32.768kHz
          PSIM filename /x=32768Hz
          PSIM filename /x=32768

The second method of entering the crystal value is to press
Alt-C from within the simulator and type in a new value.
See the Alt-C command below for further details.  If no
crystal frequency is entered, it will default to 8MHz upon
startup.

1.6. Scrolling
You may scroll through the source code displayed in the
lower half of the screen by using the up and down arrow
keys, PgUp, PgDn, Home and End.  The Home key brings you to
the beginning of the address space, while the End key brings
you to the end.  The marker on the middle line is used for
showing the current program counter location and for setting
breakpoints.  The line indicating the current program
counter location is displayed in gray with blue letters.
When you press the up or down arrow keys, you can scroll up
or down through the code.  The line marker is highlighted in
black with yellow characters when you scroll off of the
current program counter line.  To set a breakpoint in your
code, you may scroll through the code until the desired line
is highlighted at the center, then press F2.  This will set
a breakpoint at that line and denote this by highlighting it
in red.  There are no limits to the number of breakpoints
that you can set.

1.7. Altering RAM
To alter a register (file) during simulation, you may use
one of two methods.  If your computer has a mouse, you can
move the mouse cursor until the desired register is
highlighted.  Then press the left mouse button to increment
the register contents or the right mouse button to decrement
it.  The upper and lower nibbles of a register can be
incremented or decremented separately for those that are
displayed in hex.  For those that are displayed in binary,
you may alter each bit separately.  Some of the registers
are not allowed to change.  You may not change the indirect
address register (f0).  The indirect address is not
physically implemented in the processor and altering it
would have no effect.  Also, if the selected device is a
PIC54 or 55 you may not change the upper two bits of the
program counter, since these devices do not implement these
bits.  For the PIC56, you are not allowed to alter the upper
bit of the program counter.

If you do not have a mouse, you may select a register by
pressing and holding the control key and using the arrow
keys to move the highlighted cursor.  This highlighted
cursor will move from register to register as you press the
arrow keys (while the ctrl key is held).  When it is on the
desired register, you can release the control key and type
in the desired value for that register.  If you are altering
a register that is displayed in hex, you can type in any
valid hex character.  If you are altering a register that is
displayed in binary, you may only type in 1's or 0's.  You
must type in all the numbers that are highlighted before the
new value will be accepted.  The highlighted cursor will
disappear when you resume simulation.

1.8. Watchdog Timer
The watchdog timer may be enabled or disabled using one of
two methods.  The first is to include the "wdt_on" or
"wdt_off" assembler directive in the source code (see
assembler documentation for details).  The second method is
to press Alt-W from within the assembler.  A menu will pop
up allowing the user to select "enable" or "disable" with
the up or down arrow keys.  Press return when the proper
selection is highlighted.

1.9. Quitting
To quit PSIM and return to DOS, press escape (ESC) or Alt-X.
You will then be asked to verify your decision before it
will quit.  Press "y" to quit or "n" or ESC to return to the
simulator.



2. Commands

The function key commands are as follows:

F1 - HELP.  This displays the help menu.  Use the Page Down
key to display the second page of the help menu.

F2 - BRKPT.  Toggle the breakpoint at the highlighted line.
To insert a breakpoint at a specific line, use the cursor
keys to scroll the program display up or down until the
desired line is displayed in the center highlighted bar,
then press F2.  The line will then turn red to indicate that
the breakpoint is set.  Pressing F2 again on the same line
will clear the breakpoint.

F3 - CLEAR.  Clear all breakpoints.

F4 - HERE.  Execute the code until the highlighted line is
reached.  Pressing F4 will simulate the program line by line
until the center highlighted line is reached.  The message
"running..." is displayed at the bottom of the screen to
indicate that it is simulating.  When the highlighted line
is reached, the screen is updated and the registers that
were altered are highlighted.  To stop the simulation while
it is running, press any key.

F5 - TIME.  Reset the real time display to zero.  This is
useful for timing code execution.

F6 - GO.  Pressing F6 will start the simulator running, and
will not stop until a key is pressed or a breakpoint is
reached.  The screen is updated and the changes are
highlighted after each line is executed.

F7 - STEP.  This causes one line to be executed.  The
changes in the registers are highlighted after the line is
executed.  Pressing the space bar also executes one line.

F8 - NEXT.  F8 causes the simulator to execute until the
next line is reached or a breakpoint is reached.  This is
useful for executing through subroutine calls.  If F8 is
pressed when the cursor is on a subroutine call, the
simulator will execute the code until the line after the
call is reached.  The user can also stop execution at any
time by pressing any key.  If the F8 key is pressed when the
highlighted line is at the end of the address space (e.g.
1FFH for the PIC16C54), it will never reach the next line,
since it is out of the code space.  In this case, it will
continue running until the user presses any key to stop it.

F9 - RUN.  This causes the simulator to execute the code
until a breakpoint is reached or any key is pressed.  The
screen is not updated until execution is stopped.

F10 - RESET.  This simulates a hardware reset.

SPACE - STEP.  Same as F7.

Alt-C  CRYSTAL.  The crystal value defaults to 8MHz.  This
value is used to calculate execution time.  To enter a new
crystal value, press Alt-C.  A window will pop up allowing
the user to type in the desired crystal frequency value.
The user can type the value in Hertz (Hz), kiloHertz (kHz),
or megaHertz (MHz) by typing the value and the appropriate
suffix.  If no suffix is entered, it is assumed to be in
Hertz.  The suffix can be upper or lower case or a
combination of the two.  Some examples are as follows:
32768, 32768Hz, 32.768kHz, 1MHz, 3.57MHz.

Alt-D  DEVICE.  To select a different device type, press Alt-
D while in the simulator.  This will pop up a menu where you
can use the up and down arrow keys to select the desired
device.  Press enter when the desired device is highlighted.
You must be careful when using this method.  Any code that
is above the address limit of the newly selected device will
be eliminated.  Also, keep in mind that the PIC16C5X and
PIC16C71/84 are not object code compatible.  If the device
is set to PIC16C71 while simulating PIC16C5X code,
unexpected results will occur.  To exit from the device menu
without changing the device type, press escape.

Alt-E DISPLAY EEPROM.  If the device is set to PIC16C84, the
user can view the contents of the EEPROM data memory by
pressing Alt-E.  This is not available when any other
processor type is selected.

Alt-F  LOAD FILE.  To load in a different file, press Alt-F.
A file menu will pop up allowing the user to select a file
from the list.  The list files are displayed in yellow and
directories are in red.  Only files with a '.lst' extension
are listed.  To load a file, use the cursor keys to move the
highlighted cursor to the desired file and press enter.  If
you need to load a file from a different directory, move the
highlighted cursor to the desired directory and press enter.
The display will then list the files in the selected
directory for you to choose from.  To quit the file menu
without loading in a new file, press the escape key.

Alt-S DISPLAY STACK.  The first two stack locations are
displayed at the top left side of the screen at all times.
If the device type is set to PIC16C71 or PIC16C84, the user
can display all 8 stack locations in a pop up window by
pressing Alt-S.

Alt-W  WATCH DOG TIMER.  To enable or disable the watch dog
timer, press Alt-W from within the assembler.  A menu will
pop up allowing the user to select "enable" or "disable"
with the up or down arrow keys.  Press return when the
proper selection is highlighted.

Alt-F4  JUMP TO CURSOR.  Moving the cursor to a new line and
pressing Alt-F4 causes the simulator to jump to the
highlighted line, without executing any instructions.  This
is useful for jumping directly to code segments that you
wish to debug, without having to run through the normal code
execution to get there.  It is also useful for jumping over
long delay loops in your code.

Alt-F7  BACK STEP.  Pressing Alt-F7 steps backward one line
in your program.  The entire state of the microcontroller is
stored in a 100 element history buffer to allow the user to
step back through the code up to 100 steps.

Alt-X  EXIT.  Pressing Alt-X exits the simulator and returns
to DOS.  A pop-up prompt will allow you to confirm the exit
command.



3. Command Line Options

Valid command line options are as follows:

/d=device, where device = pic54, pic55, pic56, pic57, pic58,
pic71, or pic84.  This sets the type of processor being
simulated, overriding the normal listfile device detection.

/e-  -disables serial port checking for the in-circuit
emulator.  Normally, PSIM checks the available serial ports
for the presence of the in-circuit emulator.  If you are not
using the emulator and do not want PSIM to alter your serial
ports, you can disable it with this command line option.

/e=n  -where n is the number of the serial port connected to
the in-circuit emulator.  This forces PSIM to only look for
the emulator on the specified com port at startup.

/f-  -disables serial port checking for the I/O simulator
Reflection 5X.  Normally, PSIM checks the available serial
ports for the I/O simulator.  If you are not using
Reflection 5X and do not want PSIM to alter your serial
ports, you can disable it with this command line option.

/f=n  -where n is the number of the serial port connected to
the I/O simulator Reflection 5X.  This forces PSIM to only
look for Reflection 5X on the specified com port at startup.

/i=filename -where filename is the input stimulus file name.
This loads the stimulus file for execution during
simulation.  See section 5 for details.

/j=journalfile -where journalfile is the journal file name.
This loads and executes the keystrokes read from the journal
file.  See section 4 for details.

/j-  -shut off journal file feature.  Keystrokes will not be
stored in the journal file.

/r  -randomizes RAM values on startup.  By adding the
command line parameter /r, the file registers will come up
in a random state, with the exception of the RAM locations 2
through 7 (or 2 through 6 for the PIC57).  This more
accurately simulates an actual PIC microcontroller, since
it's RAM comes up in random states upon power up.

/s  -disable stack overflow and underflow error detection.

/x=xtal, where xtal = crystal frequency.  This sets the
crystal frequency used by the simulator to calculate
instruction cycle time.

/?  -display help menu showing valid command line options.


4. Journal Files

All keystrokes entered during simulation are automatically
stored in a journal file named 'psim.jrn' in the current
default directory.  This file is automatically created
during each PSIM session, unless it is turned off with the
command line option: "/j-".  When you re-enter PSIM, the
last journal file will be overwritten.  If you want to
retain the journal file for later use, rename it or copy it
to another filename before re-executing PSIM.  To re-run a
journal file, type: "psim listfile /j=journalfile" at the
DOS prompt.  This will load in the listfile and execute the
keystrokes read from the journalfile.  This feature is
useful for configuring your simulation session upon startup.
For instance, you can initialize an I/O port to a certain
value or set some breakpoints in your code.  This setup can
then be automatically executed upon startup of later
simulation sessions.  Note that mouse movements and mouse
button clicks are not stored in the journal file -- you must
use the cursor keys for initializing register values.


5. Input Stimulus File

The stimulus file feature allows the user to schedule bit
changes in the I/O port pins at specified times during
simulation.  This scheduling is controlled via a text file
called a stimulus file.  The "/i=filename" command line
option is used to read in the stimulus file, where
"filename" is the name of the stimulus text file.

The stimulus file is an ASCII file containing instructions
for applying stimuli to the I/O pins of the microprocessor.
All commands must be comma separated.  White spaces and tabs
are ignored.  Any line beginning with a semicolon is a
comment line.  There are five different schedule commands to
tell when you want the stimulus applied to the I/O pin(s).
These commands must be the first command on a line.  The
five commands are t=r, c=n, dt=r, dc=n, and pc=n, where r is
a real number and n is an integer.

The t=r command applies the stimulus when the time reaches
r.  The c=n command applies the stimulus when the cycle
counter reaches n.  The dt and dc commands apply the stimuli
when the delta time (or delta cycles) reach the given value.
That is, when that command is reached, the current time (or
cycle count) is read, and the delta time (or delta cycle
count) is added to the reading to give the stimulus time.

After the schedule command comes the stimulus command.  The
stimulus on each line can be applied to one I/O pin (e.g.
ra0=1) or to a full port (e.g. rb=d5h).  It can also be
applied to the RTCC pin (e.g. rtcc=0) or, when simulating a
PIC16C71, can be applied to the analog inputs of the A/D
converter (e.g. ain2=4.80v).

You may have up to 8 I/O bit changes per line or 3 full port
changes.  The following are examples of valid stimulus
commands:


; This is a comment line in the stimulus file
pc=8, ra=2dh,rb=feh      ; this sets port A to 2d hex, and
                         ; port B to fe hex when the program
                         ; counter reaches 8 (program counter 
                         ; values are entered in decimal, port 
                         ; values in hex).

t=0.00002, ra0=1, ra3=0  ; this sets bit 1 of port A and
                         ; clears bit 3 of port A at
                         ; time = 0.00002 seconds

c=50, rb0=1              ; this sets bit 0 of port B after
                         ; the 50th cycle is reached

dt=0.00001,   rb7=1      ; this sets bit 7 of port B when
                         ; dt=0.00001 seconds.  In this example
                         ; it will occur 0.00001 seconds after 
                         ; the 50th cycle.

dc=12, rtcc=1            ; sets the RTCC pin 12 cycles after
                         : the last stimulus
dc=5, rtcc=0             ; clears the RTCC 5 cycles after
                         ; the last stimulus.
