.
gpsim - Gnu Pic Simulator, a simulator for Microchip's PIC microcontrollers.
http://www.dattalo.com/gnupic/gpsim.html


Please see the INSTALL file to get instructions on how to install gpsim.
Please see the TODO file to get an idea of the current status and a little background on how the code works.
Please see the HISTORY file to see how gpsim has evolved.
Please see the README.EXAMPLES file for information about the examples.
Please see the PROCESSORS file to see a list of supported processors.
Please see doc/gpsim.lyx or doc/gpsim.ps for the latest documentation
Please see COPYING for the GPL.

gpsim-0.21.1 new stuff:

04JAN04 gpsim-0.21.1
  o Added the stopwatch command.
  o 18f1220 and 18f1320 added by Bradly McLean
  o EEPROM added to 18F devices by Mike Durian

*note:
eXdbm and gtk+extra are needed by gpsim.
With version gpsim-0.20.0 you'll need to upgrade to gtk+extra-0.99.9.
Please see the gpsim web page.


System Requirements:
--------------------

I've only tested the code on a Intel based Linux boxes (redhat 4.2, 5.1, 5.2, 6.0, 6.1).

 Much of the software is in C++, so you'll need the standard include files and libraries etc. I tried not to use any gcc specific C++ things (like the operator ?> for example). So I see no reason gpsim wouldn't compile on any system. The g++ compiler and include files are required. The GNU readline library is also required.


If you want the gui support then you'll also need glib and gtk. I'm using version 1.2.3 (the version numbers for these packages track one another). I've also have successfully used 1.2.1. You're also going to need the latest gtk+-extra, eXdbm packages. See INSTALL about these.




Installing:
----------

See the INSTALL file.

Invoking:
---------

Run gpsim by typing:

$ gpsim --help

gpsim - the GNUPIC simulator
version: 0.21.1


type help for help
Usage: gpsim [-h] [-p <device> [<hex_file>]] [-c <stc_file>]
  -p, --processor=<processor name>     processor (e.g. -pp16c84 for the 'c84)
  -c, --command=STRING                 startup command file
  -s, --symbol=STRING                  .cod symbol file
  -L, --                               colon separated list of directories to
                                       search.
  -v, --version                        gpsim version
  -i, --cli                            command line mode only
  -d, --icd=STRING                     use ICD (e.g. -d /dev/ttyS0).

Help options:
  -?, --help                           Show this help message
  --usage                              Display brief usage message

for example:

$gpsim -pp16c61 pichexfile.hex

will start the simulator, select a 'c61 as the target and load the program memory with pichexfile.hex hex file. There are several pic source files in the /examples subdirectory. 

or (preferred)

$gpsim -s piccodfile.cod     # note, you don't need to specify the processor for .cod files


Once started, a very simple command line prompt will process your requests:

gpsim> help
attach         Attach stimuli to nodes
break          Set a break point
bus            Add or display node busses
clear          Remove a break point
disassemble    Disassemble the current cpu
dump           Display either the RAM or EEPROM
frequency      Set the clock frequency
help           Type help "command" for more help on a command
icd            ICD command.
list           Display source and list files
load           Load either a hex,command, or .cod file
log            Log/record events to a file
node           Add or display stimulus nodes
module         Select & Display modules
processor      Select & Display processors
quit           Quit gpsim
reset          Reset all or parts of the simulation
run            Execute the pic program
set            display and control gpsim behavior flags
step           Execute one or more instructions.
stimulus       Create a stimulus
stopwatch      Measure time between events
symbol         Add or display symbols
trace          Dump the trace history
version        Display the gpsim's version
x              examine and/or modify memory



More help is available for each command by typing help "command". For example, help break prints this:

gpsim> help break
break [c e | w | r | wv | rv | wdt [location] [value] ]

        options:
                c   - cycle
                e   - execution
                w   - write
                r   - read
                wv  - write value
                rv  - read value
                wdt - wdt timeout
                    - no argument, display the break points that are set.
        examples:
                break e 0x20     // set an execution break point at address 0x20
                break wv 0x30 0  // break if a zero is written to register 0x30
                break c 1000000  // break on the one million'th cycle
                break            // display all of the break points

The cli is available even when the gui is used.


Features:
---------

Standard simulator stuff:
  o Breakpoints - execution, read and write memory, wdt, <ctrl C>
  o single stepping
  o step over
  o run until break
  o disassemble 
  o dump memory/eeprom
  o Trace
  o stimulus files - analog and digital
  o configuration files
  o symbolic debugging

Gui stuff:
  o Register viewer
  o Source file viewer
  o Program opcode window
  o Symbol viewer
  o Watch window
  o Pinout/breadboard window
  o Stack Viewer


gpsim specific
  o Simulate multiple processors (not fully supported)
  o Dynamically loaded modules

Peripherals supported:
  o eeprom
  o WDT
  o TMR0
  o I/O Ports
  o TMR1
  o TMR2
  o CCP
  o PWM
  o A/D
  o UART 

BUGS:
----
I'm absolutely certain there are bugs. If you find one, send it to me at either
scott@dattalo.com

or post it to the gnupic mailing list:
       mailto:gnupic@linuxhacker.org

Finally, see the file Contributions for people who have submitted suggestions and patches.

Scott
