.
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.20.0 new stuff:

28JUL00 gpsim-0.20.0
  o Modules - gpsim now supports dynamically loaded modules
    -- module command
  o gui - upgraded to latest versions of gtk & gtkextra
  o gui - Menu items now work
  o gui - button bar
  o gui - now refreshes while simulating
  o gui - Stack Window has been added
  o BSD is now supported
  o numerous bug fixes

*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.


Modules
-------
One of big features in this release is Modules. gpsim now has a way to allow you to create specific simulation environments without having to learn everything about gpsim. This has been a major overhaul of the infrastructure of gpsim. 

The idea is that you'll be able to create your own custom modules, package these into a library, and then load them from gpsim.

There are two example modules: an LED one and a Logic one. These are somewhat experimental, but can serve as templates for creating your own modules. The LED module consists of a single digit, 7-segment, common-anode display. The Logic module contains a two-input AND gate and a two-input OR gate. Both libraries are available from the gpsim web page:

  http://www.dattalo.com/gnupic/led-0.0.3.tar.gz
  http://www.dattalo.com/gnupic/logic-0.0.1.tar.gz

(Note, the version number may change, so it would be best to go to the gpsim web page and look for the latest version there).

The README.modules file explains in more detail how to create/use modules.

`module' command
----------------

A new command has been added to gpsim to support modules:

gpsim> help module
module [ [load module_type [module_name]] | [lib lib_name] | [list] | 
[[dump | pins] module_name] ]
        If no options are specified, then the currently defined module(s)
        will be displayed. This is the same as the `module list' command.
        The `module load lib_name' tells gpsim to search for the module
        library called `lib_name' and to load it. (Note that the format of
        module libraries is exactly the same as a Linux shared library. This
        means that the module library should reside in a path available to
        dlopen(). Please see the README.MODULES in the gpsim distribution.
        To instantiate a new module, then type
          module module_type module_name
        where module_type refers to a specific module in a module library
        and module_name is the user name assigned to it.
        Information about a module can be displayed by the commad
          module module_name [dump | pins]

        where module_name is the name that you assigned when the module
        was instantiated. The optional dump and pins identifiers specify
        the information you wish to display (dump is the default).

        examples:


        module                      // Display the modules you've already defined.
        module lib my_mods.so       // Load the module library called my_mods.
        module list                 // Display the list of modules supported.
        module load lcd my_lcd      // Create an instance of an 'lcd'
        module pins my_lcd          // Display the pin states of an instantiated module
        module load lcd lcd2x20     // Create a new module.
        module load led start_light // and another.

-------

It's fairly tedious to memorize all of the details of this command. So your best bet is to copy the configuration scripts in the example libraries. 


gui - Menu items now work
-------------------------
Before Ralf joined the gpsim development, I had created a rough outline of the gui interface. There were numerous menus that were not fully implemented. Ralf has fixed that. Now gpsim can load files by navigating through the menus. In addition, the various windows were enabled/disabled with this cumbersome tabbed notebook window. Ralf has gotten rid of that and provided a <windows> menu item that will allow you to open and close windows.

gui - button bar
----------------
Ralf has added a button bar to the gui control panel. This allows you to perform simple commands like step, run, stop, etc. with a simple click. These complement the hot-keys that were already present.


gui - now refreshes while simulating
------------------------------------
The gui now can be refreshed will the simulation is running. Before, the simulation engine would hog all of the cpu and would ignore the gui until the simulation completed (e.g. when  a break point was encountered). Also, the rate at which the gui is updated is controlled directly from the gui control window.

gui - Stack Viewer
------------------
Ralf has added a stack viewer that will display the contents of the PIC stack. You can double click on entries in the Stack Viewer to set breakpoints on the addresses.

BSD supported:
--------------
Joerg Wunsch <joerg_wunsch@interface-business.de>, a BSD guy, has taken the time to  get gpsim to compile under BSD.In the process he has fixed a few system dependcy bugs that have plagued gpsim for a really long time.

bug fixes
---------
There were literally so many bug fixes that I lost track.
  -- core dumps for instantiating several processors
  -- TMR0 rollover bug (actually in the breakpoint code)
  -- stimuli -> there are ALWAYS bugs here
  -- multi-line stimuli weren't working


What's coming next?
-------------------

Register Stimuli.
More Modules
Begin research into a schematic capture front end.

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 [-h] [-p<device> [<hex_file>]] [-c<stc_file>]
        -h            : this help list
        -p<device>    : processor (e.g. -pp16c84 for the 'c84)
        <hex_file>    : input file in "intelhex16" format
        -c<stc_file>  : startup command file
        -s<cod_file>  : .cod symbol file

        -v            : gpsim version

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 ./gpsim-0.0.14/examples subdirectory. 

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

gpsim> help
attach         Attach stimuli to nodes
break          Set a break point
clear          Remove a break point
disassemble    Disassemble the current cpu
dump           Display either the RAM or EEPROM
echo           echo "text"
help           Type help "command" for more help on a command
list           Display source and list files
load           Load either a hex,command, or .cod file
module         Select & Display modules
node           Add or display stimulus nodes
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
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
