#LyX 1.4.3 created this file. For more info see http://www.lyx.org/
\lyxformat 245
\begin_document
\begin_header
\textclass book
\language english
\inputencoding default
\fontscheme times
\graphics default
\paperfontsize 10
\spacing single
\papersize default
\use_geometry false
\use_amsmath 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\leftmargin -0.5cm
\topmargin 0.5cm
\rightmargin 0.5cm
\bottommargin 0.5cm
\secnumdepth 2
\tocdepth 2
\paragraph_separation skip
\defskip smallskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes true
\end_header
\begin_body
\begin_layout Title
gpsim
\end_layout
\begin_layout Date
$Date: 2006-11-09 08:27:47 -0800 (Thu, 09 Nov 2006) $
\end_layout
\begin_layout Standard
\begin_inset LatexCommand \tableofcontents{}
\end_inset
\end_layout
\begin_layout Chapter*
Introduction
\end_layout
\begin_layout Standard
gpsim is a full-featured software simulator for Microchip PIC microcontrollers
distributed under the GNU General Public License
\begin_inset Note Note
status collapsed
\begin_layout Standard
scott2 Wed Sep 30 13:25:58 1998
\end_layout
\end_inset
(see the COPYING section).
\end_layout
\begin_layout Standard
gpsim has been designed to be as accurate as possible.
Accuracy includes the entire PIC - from the core to the I/O pins and including
ALL of the internal peripherals.
Thus it's possible to create stimuli and tie them to the I/O pins and test
the PIC the same way you would in the real world.
\end_layout
\begin_layout Standard
gpsim has been designed to be as fast as possible.
Real time simulation speeds of 20Mhz pics are possible.
\end_layout
\begin_layout Standard
gpsim can be controlled from either a graphical user interface (GUI), a
command line interface (CLI) or by a remote process.
Typical debugging features like breakpoints, single stepping, disassembling,
memory inspect & change, and so on are all supported.
In addition, complex debugging features like real time tracing, assertions,
conditional breaks, and plugin modules to name a few are also supported.
\end_layout
\begin_layout Chapter
gpsim - An Overview
\end_layout
\begin_layout Standard
If you don't care to wade through details, this chapter should help you
get things up and running.
The INSTALL and README files will provide more up-to-date information than
this document, so please refer to those first.
\end_layout
\begin_layout Section
Making the executable
\end_layout
\begin_layout Standard
gpsim's executable is created in a manner that's consistent with much of
the other open source software:
\end_layout
\begin_layout Standard
\begin_inset Tabular
|
\begin_inset Text
\begin_layout Standard
command
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
description
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
tar -xvzf gpsim-x.y.z.tar.gz
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
expand the compressed tar file
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
./configure
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Create a 'makefile' unique to your system
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
make
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
compile gpsim
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
make install
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
install gpsim
\end_layout
\end_inset
|
\end_inset
\end_layout
\begin_layout Standard
The last step will require root privileges.
\end_layout
\begin_layout Subsection
Make Details - ./configure options
\end_layout
\begin_layout Subsubsection*
gui-less
\end_layout
\begin_layout Standard
The default configuration will provide a gui (graphical user interface).
The cli (command line interface) is still available, however many people
prefer just to use the cli.
These hardy souls may build a command-line only interface by configuring
gpsim:
\end_layout
\begin_layout LyX-Code
./configure --disable-gui
\end_layout
\begin_layout Subsubsection*
debugging
\end_layout
\begin_layout Standard
If you want to debug gpsim then you'll probably use gdb.
Consequently, you'll want to disable shared libraries:
\end_layout
\begin_layout LyX-Code
./configure --disable-shared
\end_layout
\begin_layout Standard
This will create one, huge monolithic executable with symbolic information.
\end_layout
\begin_layout Subsection
RPMs
\end_layout
\begin_layout Standard
gpsim is also distributed in RPM form.
In recent versions, there are two RPMs: gpsim-devel and gpsim.
Both of these must be installed.
There is also a RPM for the source code.
This can be used to build a binary RPM unique to your system.
Please see the latest INSTALL and README for the most up to date information.
\end_layout
\begin_layout Subsection
Windows
\end_layout
\begin_layout Standard
gpsim runs on Windows too.
Borut Razem maintains the gpsim Windows web site:
\end_layout
\begin_layout Quote
http://gpsim.sourceforge.net/gpsimWin32/gpsimWin32.html
\end_layout
\begin_layout Standard
You can find detailed instructions there for installing gpsim and its dependenci
es.
Snap shots can be found:
\end_layout
\begin_layout Quote
http://gpsim.sourceforge.net/snap.php
\end_layout
\begin_layout Section
Running
\end_layout
\begin_layout Standard
The executable created above is called: gpsim.
The following command line options may be specified when gpsim is invoked.
\end_layout
\begin_layout LyX-Code
gpsim [-?] [-p []] [-c ]
\end_layout
\begin_layout LyX-Code
-p, --processor= processor (e.g.
-pp16c84 for the 'c84)
\end_layout
\begin_layout LyX-Code
-c, --command=STRING startup command file
\end_layout
\begin_layout LyX-Code
-s .cod symbol file
\end_layout
\begin_layout LyX-Code
-L, -- colon separated list of directories
to
\end_layout
\begin_layout LyX-Code
search.
\end_layout
\begin_layout LyX-Code
-v, --version gpsim version
\end_layout
\begin_layout LyX-Code
-i, --cli command line mode only
\end_layout
\begin_layout LyX-Code
-d, --icd=STRING use ICD (e.g.
-d /dev/ttyS0).
\end_layout
\begin_layout LyX-Code
Help options:
\end_layout
\begin_layout LyX-Code
-?, --help Show this help message
\end_layout
\begin_layout LyX-Code
--usage Display brief usage message
\end_layout
\begin_layout Standard
Typically gpsim will be invoked like:
\end_layout
\begin_layout LyX-Code
[My-Computer]$ gpsim -s mypic-program.cod
\end_layout
\begin_layout Standard
(The
\emph on
[My-Computer]$
\emph default
text is an example of a typical bash command prompt - you'll only type
the text after this prompt).
This loads the .cod file generated by gputils.
\end_layout
\begin_layout Standard
Under Windows, gpsim can also be invoked by navigating through the Start/Progam
menu.
This will open a DOS window to provide access to the command line interface.
It's also possible to open a DOS window (or CygWin bash session) and invoke
gpsim from there.
\end_layout
\begin_layout Section
Requirements
\end_layout
\begin_layout Standard
gpsim has been developed under Linux.
It should build and run just fine under the popular Linux distributions
like Fedora, Ubuntu, etc.
gpsim has also been ported to the MAC, MicroSoft Windows, Solaris, and
BSD.
Two packages gpsim requires that may not be available with all Linux distributi
ons are readline and gtk (the gimp tool kit).
The ./configure script should tell you if these packages are not installed
on your system or if the revisions that are installed are too old.
\end_layout
\begin_layout Standard
There are no minimum hardware requirements to run gpsim.
Faster is better though!
\end_layout
\begin_layout Standard
gputils, the gnupic utilities package, is also very useful.
gpsim will accept straight hex files, but if you want to do any symbolic
debugging then you'll want to use the .cod
\begin_inset Foot
status collapsed
\begin_layout Standard
.cod files are symbol files that were created by ByteCraft and are used by
Microchip.
\end_layout
\end_inset
files that gputils produces.
The .cod files are in the same format as the .cod files MPASM
\begin_inset Foot
status collapsed
\begin_layout Standard
MPASM is Microchip's Assembler.
\end_layout
\end_inset
produces.
\end_layout
\begin_layout Chapter
Command Line Interface
\end_layout
\begin_layout Standard
The command line interface is fairly straight-forward.
The table below summarizes the available commands.
Brief descriptions of these commands can also be displayed by typing
\emph on
help
\emph default
at the command line.
\end_layout
\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset
\end_layout
\begin_layout Standard
\align center
\begin_inset Tabular
|
\begin_inset Text
\begin_layout Standard
command
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
summary
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
attach
\begin_inset LatexCommand \index{attach}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Attach stimuli to nodes
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
break
\begin_inset LatexCommand \index{break}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Set a break point
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
bus
\begin_inset LatexCommand \index{bus}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Add or display node busses
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
clear
\begin_inset LatexCommand \index{clear}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Remove a break point
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
disassemble
\begin_inset LatexCommand \index{disassemble}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Disassemble the current cpu
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
dump
\begin_inset LatexCommand \index{dump}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Display either the RAM or EEPROM
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
frequency
\begin_inset LatexCommand \index{frequency}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Set processor frequency
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
help
\begin_inset LatexCommand \index{help}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Type help "command" for more help on a command
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
icd
\begin_inset LatexCommand \index{icd}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
In Circuit Debugger support.
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
list
\begin_inset LatexCommand \index{list}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Display source and list files
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
load
\begin_inset LatexCommand \index{load}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Load either a hex or command file
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
log
\begin_inset LatexCommand \index{log}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Log/record events to a file
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
node
\begin_inset LatexCommand \index{node}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Add or display stimulus nodes
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
module
\begin_inset LatexCommand \index{module}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
Select & Display modules
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
processor
\begin_inset LatexCommand \index{processor}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Add/list processors
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
quit
\begin_inset LatexCommand \index{quit}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Quit gpsim
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
reset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
Reset all or parts of the simulation
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
run
\begin_inset LatexCommand \index{run}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Execute the pic program
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
set
\begin_inset LatexCommand \index{set}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
display and control gpsim behavior flags
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
step
\begin_inset LatexCommand \index{step}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Execute one or more instructions
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
stimulus
\begin_inset LatexCommand \index{stimulus}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Create a stimulus
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
stopwatch
\begin_inset LatexCommand \index{stopwatch}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
Measure time between events
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
symbol
\begin_inset LatexCommand \index{symbol}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Add/list symbols
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
trace
\begin_inset LatexCommand \index{trace}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Dump the trace history
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
version
\begin_inset LatexCommand \index{version}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Display gpsim's version
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
x
\begin_inset LatexCommand \index{x}
\end_inset
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
(deprecated) examine and/or modify memory
\end_layout
\end_inset
|
\end_inset
\end_layout
\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset
\end_layout
\begin_layout Standard
The built in 'help' command provides additional online information.
\end_layout
\begin_layout Section
attach
\begin_inset LatexCommand \index{attach}
\end_inset
\end_layout
\begin_layout LyX-Code
attach node1 stimulus1 [stimulus2 stimulus_N]
\end_layout
\begin_layout Standard
attach is used to define the connections between stimuli and nodes.
At least one node and one stimulus must be specified.
If more stimuli are specified then they will all be attached to the node
examples:
\end_layout
\begin_layout LyX-Code
gpsim> node n1 # Define a new node.
\end_layout
\begin_layout LyX-Code
gpsim> attach n1 porta4 portb0 # Connect two I/O pins to the node.
\end_layout
\begin_layout LyX-Code
gpsim> node # Display the new "net list".
\end_layout
\begin_layout Section
break
\begin_inset LatexCommand \index{break}
\end_inset
\end_layout
\begin_layout Standard
The break command is used to set and examine break points.
New break points are assigned a unique number.
This number can be used to query or clear the break point.
Break points halt the simulation when the condition associated with them
is true.
Break points are ignored during single stepping.
See chapter
\begin_inset LatexCommand \ref{cha:Assertions-and-Extended}
\end_inset
for more examples of breakpoints.
\end_layout
\begin_layout Subsubsection*
Examining break points
\end_layout
\begin_layout LyX-Code
break [bp_number]
\end_layout
\begin_layout Standard
Break points can be examined by typing the break command without any options.
Specific breaks can be queried by specifying the break point number.
\end_layout
\begin_layout Subsubsection*
Program Memory/Execution breaks
\end_layout
\begin_layout Standard
The most common break point is an execution break point.
This one halts execution whenever the program counter reaches the address
at which the break point is set.
The syntax is:
\end_layout
\begin_layout LyX-Code
break e|r|w ADDRESS [expr]
\end_layout
\begin_layout Standard
The simulation halts when the address is executed, read, or written.
The ADDRESS can be a symbol or a number.
If the optional expression is specified, then it must evaluate to true
before the simulation will halt.
The read and write options only apply to those processors that can manipulate
their own program memory.
\end_layout
\begin_layout Subsubsection*
Register Memory breaks
\end_layout
\begin_layout Standard
gpsim can also associate break points with register accesses.
This is useful for capturing bugs that stomp on RAM.
E.g.
you can say something like
\begin_inset Quotes eld
\end_inset
halt execution whenever bit 4 of register 42 is cleared
\begin_inset Quotes erd
\end_inset
.
The command line syntax is:
\end_layout
\begin_layout LyX-Code
break r|w REGISTER [expr]
\end_layout
\begin_layout Standard
The simulation halts when
\emph on
REGISTER
\emph default
is read or written and the optional expression evaluates to true.
There are two styles of expressions supported.
One involves only expressions of the
\emph on
REGISTER
\emph default
, the other is completely arbitrary.
The examples below illustrate the differences.
\end_layout
\begin_layout Standard
Here's an example of a register write break.
This one will halt the simulation if any value is written to the variable
named
\emph on
temp1
\emph default
.
\end_layout
\begin_layout LyX-Code
break w temp1
\end_layout
\begin_layout Standard
Here the write is conditioned to happen for only a certain value:
\end_layout
\begin_layout LyX-Code
break w temp1==0x22
\end_layout
\begin_layout Standard
Here the condition applies to specific bits:
\end_layout
\begin_layout LyX-Code
break w temp1 & 0b11110000 == 0b11000000
\end_layout
\begin_layout Standard
This one breaks only if the hex digit 'C' is written to the upper nibble
of temp1.
\end_layout
\begin_layout Subsubsection*
Boolean Expressions
\end_layout
\begin_layout Standard
Sometimes it's necessary to specify an auxillary condition with a break
point.
For example, there may be a temporary variable that is shared throughout
the code.
You may wish to trap writes to that variable only while executing a specific
subroutine.
For example, the following break point triggers when temp1 is written and
while the program counter is in between the labels
\emph on
func_start
\emph default
and
\emph on
func_end
\emph default
:
\end_layout
\begin_layout LyX-Code
break w temp1 (pc >= func_start && pc < func_end)
\end_layout
\begin_layout Standard
\emph on
TIP:
\emph default
Use this type of break point if you suspect an interrupt routine is over
writing a variable.
\end_layout
\begin_layout Standard
Another situation is one where you wish to trap writes to a variable only
if some other variable is a certain value:
\end_layout
\begin_layout LyX-Code
break w temp1 (CurTask & 0x0f != 0b101)
\end_layout
\begin_layout Standard
If the firmware writes to the variable temp1 then the simulation will halt
if the lower nibble of CurTask is not equal to 5.
\end_layout
\begin_layout Subsubsection*
Attribute Breakpoints
\end_layout
\begin_layout Standard
gpsim also supports a concept of
\emph on
attribute breakpoints.
\emph default
Attributes are parameters that gpsim and its modules expose to the user
interface.
For example, the simulator stopwatch exposes attributes which support breakpoin
ts.
This feature is intend mainly for module writers to provide a mechanism
for allowing the user to control the module.
\end_layout
\begin_layout Subsubsection*
Cycle counter Breakpoints
\end_layout
\begin_layout LyX-Code
break c
\emph on
cycle_number
\end_layout
\begin_layout Standard
The cycle counter is gpsim's time keeper.
It increments once every instruction cycle.
The 'c' option to the break command allows a break point to be set at a
particular value of the cycle counter.
\end_layout
\begin_layout Section
clear
\begin_inset LatexCommand \index{clear}
\end_inset
\end_layout
\begin_layout LyX-Code
clear bp_number
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Standard
The clear command is used to clear break points.
The break point number must be specified.
The
\emph on
break
\emph default
command without any arguments displays all of the currently defined break
points.
This can be used to ascertain the break point number.
Once cleared, a break point is deleted.
\begin_inset Foot
status collapsed
\begin_layout Standard
A break point disable/enable feature has been discussed and may be added
a future date.
\end_layout
\end_inset
\end_layout
\begin_layout Section
disassemble
\begin_inset LatexCommand \index{disassemble}
\end_inset
\end_layout
\begin_layout LyX-Code
disassemble [[begin:end] | [length]]
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Standard
The disassemble command decodes the program memory opcodes into their standard
mnemonics.
With no options, the
\emph on
disassemble
\emph default
command disassembles instructions surrounding the current program counter:
\end_layout
\begin_layout LyX-Code
gpsim> disassemble
\end_layout
\begin_layout LyX-Code
current pc = 0x1c
\end_layout
\begin_layout LyX-Code
0012 2a03 incf reg3,f,0
\end_layout
\begin_layout LyX-Code
0014 0004 clrwdt
\end_layout
\begin_layout LyX-Code
0016 5000 movf reg,w,0
\end_layout
\begin_layout LyX-Code
0018 1001 iorwf reg1,w,0
\end_layout
\begin_layout LyX-Code
001a 1002 iorwf reg2,w,0
\end_layout
\begin_layout LyX-Code
==> 001c 1003 iorwf reg3,w,0
\end_layout
\begin_layout LyX-Code
001e e1f4 bnz $-0x16 ;(0x8)
\end_layout
\begin_layout LyX-Code
0020 d7ff bra $-0x0 ;(0x00020)
\end_layout
\begin_layout Standard
With a single numeric option, the disassemble command will
\end_layout
\begin_layout Section
dump
\begin_inset LatexCommand \index{dump}
\end_inset
\end_layout
\begin_layout LyX-Code
dump [r | e]
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Standard
dump r or dump with no options will display all of the file registers and
special function registers.
dump e will display the contents of the eeprom (if the pic being simulated
contains any).
\end_layout
\begin_layout Standard
See the 'x' command for examining and modifying individual registers.
\end_layout
\begin_layout Section
echo
\begin_inset LatexCommand \index{echo}
\end_inset
\end_layout
\begin_layout Standard
The echo command is used like a print statement within configuration files.
It just lets you display information about your configuration file.
\end_layout
\begin_layout Section
frequency
\begin_inset LatexCommand \index{frequency}
\end_inset
\end_layout
\begin_layout Standard
This command sets the clock frequency.
By default gpsim uses 20 MHz as clock.
The clock frequency is used to compute time in seconds.
Use this command to adjust this value.
If no value is provided this command prints the current clock.
Note that PICs have an instruction clock that's a forth of the external
clock.
This value is the external clock.
\end_layout
\begin_layout Section
help
\begin_inset LatexCommand \index{help}
\end_inset
\end_layout
\begin_layout Standard
By itself, help will display all of the commands along with a brief description
on how they work.
'help ' provides more extensive online help.
The help command can also display information about attributes.
\end_layout
\begin_layout Section
icd
\begin_inset LatexCommand \index{icd}
\end_inset
\end_layout
\begin_layout Standard
\emph on
icd [open ]
\end_layout
\begin_layout Standard
The open command is used to enable ICD mode and specify the serial port
where the ICD is.
(e.g.
"icd open /dev/ttyS0").
Without options (and after the icd is enabled), it will print some information
about the ICD.
\end_layout
\begin_layout Section
list
\begin_inset LatexCommand \index{list}
\end_inset
\end_layout
\begin_layout LyX-Code
list [[s | l] [*pc] [line_number1 [,line_number2]]]
\end_layout
\begin_layout LyX-Code
Display the contents of source and list files.
\end_layout
\begin_layout LyX-Code
Without any options, list will use the last specified options.
\end_layout
\begin_layout LyX-Code
list s will display lines in the source (or .asm) file.
\end_layout
\begin_layout LyX-Code
list l will display lines in the .lst file
\end_layout
\begin_layout LyX-Code
list *pc will display either .asm or .lst lines around the pc
\end_layout
\begin_layout Standard
The list command allows you to view the source code while you are debugging.
\end_layout
\begin_layout Section
load
\begin_inset LatexCommand \index{load}
\end_inset
\end_layout
\begin_layout Standard
The load command is used to load either hex, configuration, or .cod files.
A hex file is usually used to program the physical part.
Consequently, it provides no symbolic information.
.cod files on the other hand, do provide symbolic information.
The only reason to use a hex file is when there's no .cod file available.
\end_layout
\begin_layout Standard
The syntax for loading source code files is:
\end_layout
\begin_layout LyX-Code
load [processortype] file
\end_layout
\begin_layout Standard
gpsim will automatically determine if the file is a .hex or .cod file.
The optional processortype allows one to override the processor specified
in a .cod file.
\end_layout
\begin_layout Standard
Configuration files are script files containing gpsim commands.
These are extremely useful for creating a debugging enviroment that will
be used repeatedly.
\end_layout
\begin_layout Section
macros
\begin_inset LatexCommand \index{macros}
\end_inset
\end_layout
\begin_layout Standard
Macros are defined like:
\end_layout
\begin_layout LyX-Code
\emph on
name
\emph default
macro [arg1, arg2, ..., argN]
\end_layout
\begin_layout LyX-Code
macro body
\end_layout
\begin_layout LyX-Code
endm
\end_layout
\begin_layout Standard
And they're invoked by:
\end_layout
\begin_layout LyX-Code
\emph on
name
\emph default
param1, param2, ..., paramN
\end_layout
\begin_layout Standard
Macros are a way of collecting several parameterized commands into one short
command.
The first line of a macro definition specifies the macro's name and optional
arguments.
The
\emph on
name
\emph default
is used to invoke the macro.
The arguments are text string place holders.
When a macro is invoked, the parameters are aligned with the arguments.
I.e.
\emph on
param1
\emph default
in the invocation can be thought of being assigned to
\emph on
arg1
\emph default
in the definition.
The parameters replace the arguments in the macro body.
\end_layout
\begin_layout Standard
In the following example, a variable or attribute called
\emph on
mac_flags
\emph default
is being manipulated in an expression.
The arguments
\emph on
add
\emph default
and
\emph on
mask
\emph default
appear in the macro body and provide a parameterized way of manipulating
this expression.
\end_layout
\begin_layout LyX-Code
mac_exp macro add, mask
\end_layout
\begin_layout LyX-Code
mac_flags = (mac_flags+add) & mask
\end_layout
\begin_layout LyX-Code
endm
\end_layout
\begin_layout Standard
Note that the indentation is arbitrary.
The macro is invoked by:
\end_layout
\begin_layout LyX-Code
mac_exp 1, 0b00001111 # increment the lower nibble
\end_layout
\begin_layout Standard
The parameter
\emph on
add
\emph default
is replaced by the number
\emph on
1
\emph default
while
\emph on
mask
\emph default
is replaced with the binary number
\emph on
0b00001111.
\emph default
The invocation turns into the gpsim command:
\end_layout
\begin_layout LyX-Code
mac_flags = (mac_flags+1) & 0b00001111
\end_layout
\begin_layout Subsubsection*
Nested Macros
\end_layout
\begin_layout Standard
The macro body can contain any gpsim command.
Of particular interest are macro invocations within other macros.
Here's another macro that invokes the one defined above.
\end_layout
\begin_layout LyX-Code
# Nested macro example
\end_layout
\begin_layout LyX-Code
mac1 macro p1, p2
\end_layout
\begin_layout LyX-Code
run
\end_layout
\begin_layout LyX-Code
mac_exp p1, p2
\end_layout
\begin_layout LyX-Code
endm
\end_layout
\begin_layout Standard
And it could be used like:
\end_layout
\begin_layout LyX-Code
mac1 1, 0b00001111 # test lower nibble
\end_layout
\begin_layout LyX-Code
mac1 (1<<4), 0b11110000 # test upper nibble
\end_layout
\begin_layout Standard
The first invocation starts the simulator by executing a
\emph on
run
\emph default
command.
When a break point is encountered, control returns to the command line
and the
\emph on
mac_exp
\emph default
macro is invoked.
\end_layout
\begin_layout Subsubsection*
Displaying Defined Macros
\end_layout
\begin_layout Standard
All currently defined macros can be displayed by typing the macro command
without a name or arguments:
\end_layout
\begin_layout LyX-Code
gpsim> macro
\end_layout
\begin_layout LyX-Code
mac1 macro p1 p2
\end_layout
\begin_layout LyX-Code
run
\end_layout
\begin_layout LyX-Code
mac_exp p1, p2
\end_layout
\begin_layout LyX-Code
endm
\end_layout
\begin_layout LyX-Code
mac_exp macro add mask
\end_layout
\begin_layout LyX-Code
mac_flags = (mac_flags+add) & mask
\end_layout
\begin_layout LyX-Code
endm
\end_layout
\begin_layout Section
module
\begin_inset LatexCommand \index{module}
\end_inset
\end_layout
\begin_layout Standard
The
\emph on
module
\emph default
command is used to load and query external modules (see section
\begin_inset LatexCommand \ref{cha:Modules}
\end_inset
for more information about gpsim modules).
A module is a special piece of software that can extend gpsim in some manner.
LED's and switches are examples of modules.
A module library is collection of modules.
\end_layout
\begin_layout Subsubsection*
Loading module libraries
\end_layout
\begin_layout LyX-Code
module lib
\emph on
lib_name
\end_layout
\begin_layout Standard
The
\emph on
lib
\emph default
option is used to load a module library.
Module libraries are system dependent shared libraries, i.e.
on Windows they're DLL's and UNIX they're shared libraries.
This means that either the libraries should reside in a path where the
OS knows libraries exist or that the full path name must be specified along
with the
\emph on
lib_name
\emph default
.
gpsim provides a module library with a few modules:
\end_layout
\begin_layout LyX-Code
gpsim> module lib libgpsim_modules
\end_layout
\begin_layout Subsubsection*
Displaying available modules
\end_layout
\begin_layout LyX-Code
module list
\end_layout
\begin_layout Standard
The
\emph on
list
\emph default
option will display all of the modules that can be loaded.
Here is an example of gpsim's built-in modules.
\end_layout
\begin_layout LyX-Code
gpsim> module list
\end_layout
\begin_layout LyX-Code
Module Libraries libgpsim_modules.so
\end_layout
\begin_layout LyX-Code
pullup
\end_layout
\begin_layout LyX-Code
pulldown
\end_layout
\begin_layout LyX-Code
usart
\end_layout
\begin_layout LyX-Code
switch
\end_layout
\begin_layout LyX-Code
and2
\end_layout
\begin_layout LyX-Code
or2
\end_layout
\begin_layout LyX-Code
xor2
\end_layout
\begin_layout LyX-Code
not
\end_layout
\begin_layout LyX-Code
led_7segments
\end_layout
\begin_layout LyX-Code
led
\end_layout
\begin_layout LyX-Code
pulsegen
\end_layout
\begin_layout LyX-Code
Encoder
\end_layout
\begin_layout LyX-Code
TTL377
\end_layout
\begin_layout Subsubsection*
Loading a specific module
\end_layout
\begin_layout LyX-Code
module load module_type [module_name]
\end_layout
\begin_layout Standard
Once a library has been loaded, specific modules can be instantiated.
The
\emph on
module_type
\emph default
is what's displayed by the
\emph on
module list
\emph default
command.
The optional module name specifies what the instance is called.
Here's an example
\end_layout
\begin_layout LyX-Code
gpsim> module load led D1
\end_layout
\begin_layout Subsubsection*
Display loaded modules
\end_layout
\begin_layout Subsubsection*
Querying modules
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Section
node
\begin_inset LatexCommand \index{node}
\end_inset
\end_layout
\begin_layout LyX-Code
node [new_node1 new_node2 ...]
\end_layout
\begin_layout Standard
The
\shape italic
node
\shape default
command defines or queries
\begin_inset Quotes eld
\end_inset
nodes
\begin_inset Quotes erd
\end_inset
, used to connect external signals to the simulated PIC.
If no new_node is specified then all of the nodes that have been defined
are displayed.
If a new_node is specified then it will be added to the node list.
See the "attach" and "stimulus" commands to see how stimuli are added to
the nodes.
\end_layout
\begin_layout LyX-Code
examples:
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
node // display the node list
\end_layout
\begin_layout LyX-Code
node n1 n2 n3 // create and add 3 new nodes to the list
\end_layout
\begin_layout Section
processor
\begin_inset LatexCommand \index{processor}
\end_inset
\end_layout
\begin_layout LyX-Code
processor [new_processor_type [new_processor_name]] | [list] | [dump]
\end_layout
\begin_layout Standard
The
\emph on
processor
\emph default
command is used to either define a new processor or to query one that has
already been defined.
Normally there's no need to explicitly define the processor since the symbol
file already contains that information.
The two exceptions are when a) the symbolic information is not available
or b) you wish to override the processor specified in the symbol file.
(See the
\emph on
load
\emph default
command on how the processor in a symbol file can be overridden.)
\end_layout
\begin_layout Standard
To see a list of the processors supported by gpsim, type '
\emph on
processor list
\emph default
'.
To display the state of the I/O processor, type '
\emph on
processor pins
\emph default
'.
For now, this will display the pin numbers and their current state.
\end_layout
\begin_layout LyX-Code
examples:
\end_layout
\begin_layout LyX-Code
processor // Display the processors you've already defined.
\end_layout
\begin_layout LyX-Code
processor list // Display the list of processors supported.
\end_layout
\begin_layout LyX-Code
processor pins // Display the processor package and pin state
\end_layout
\begin_layout LyX-Code
processor p16cr84 fred // Create a new processor.
\end_layout
\begin_layout LyX-Code
processor p16c74 wilma // and another.
\end_layout
\begin_layout LyX-Code
processor p16c65 // Create one with no name.
\end_layout
\begin_layout Section
quit
\begin_inset LatexCommand \index{quit}
\end_inset
\end_layout
\begin_layout Standard
Quit gpsim.
\end_layout
\begin_layout Section
run
\begin_inset LatexCommand \index{run}
\end_inset
\end_layout
\begin_layout Standard
Start (or continue) simulation.
The simulation will continue until the next break point is encountered.
\end_layout
\begin_layout Section
step
\begin_inset LatexCommand \index{step}
\end_inset
\end_layout
\begin_layout Standard
Execute a single instruction, or a specified number of instructions.
\end_layout
\begin_layout LyX-Code
step [over | n]
\end_layout
\begin_layout Standard
With no arguments, the step command executes one instruction of the PIC
code.
If a numeric argument is given, this specifies a fixed number of instructions
to simulate.
The specific word
\begin_inset Quotes eld
\end_inset
over
\begin_inset Quotes erd
\end_inset
as an argument to step tells gpsim to run everything involved in the current
instruction.
This would normally be used on a CALL instruction, in which case the whole
subroutine runs and the simulation stops after it returns.
\end_layout
\begin_layout Section
symbol
\begin_inset LatexCommand \index{symbol}
\end_inset
\end_layout
\begin_layout LyX-Code
symbol [symbol_name [symbol_type value]]
\end_layout
\begin_layout Standard
The
\emph on
symbol
\emph default
command is used to query and define symbols.
If no options are specified, the whole symbol table is displayed.
The creation of user defined symbols is limited at this time (see the online
help for the current state of this command).
\end_layout
\begin_layout Section
stimulus
\begin_inset LatexCommand \index{stimulus}
\end_inset
\end_layout
\begin_layout LyX-Code
stimulus [[type] options]
\end_layout
\begin_layout Standard
The
\emph on
stimulus
\emph default
command creates a signal that can be tied to a node or an attribute.
If no options are specified then all currently defined stimuli are displayed.
\end_layout
\begin_layout Standard
Note that in most cases it is easier to create a stimulus file then to type
the command by hand.
\end_layout
\begin_layout Standard
\begin_inset Tabular
|
\begin_inset Text
\begin_layout Standard
option
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
description
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
initial_state
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
state at the start and at the rollover
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
start_cycle
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
simulation cyle when the stimulus will begin
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
period
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
stimulus period
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
name
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
specifies the stimulus name
\end_layout
\end_inset
|
\end_inset
\end_layout
\begin_layout Standard
Here's an example of a stimulus that will generate two pulses and repeat
this in 1000 cycles.
\end_layout
\begin_layout LyX-Code
stimulus asynchronous_stimulus
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
# The initial state AND the state the stimulus is when
\end_layout
\begin_layout LyX-Code
# it rolls over
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
initial_state 0
\end_layout
\begin_layout LyX-Code
start_cycle 0
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
# the asynchronous stimulus will roll over in 'period'
\end_layout
\begin_layout LyX-Code
# cycles.
Delete this line if you don't want a roll over.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
period 1000
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
{ 100, 1,
\end_layout
\begin_layout LyX-Code
200, 0,
\end_layout
\begin_layout LyX-Code
300, 1,
\end_layout
\begin_layout LyX-Code
400, 0
\end_layout
\begin_layout LyX-Code
}
\end_layout
\begin_layout LyX-Code
# Give the stimulus a name:
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
name two_pulse_repeat
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
end
\end_layout
\begin_layout Standard
A stimulus can be queried by typing its name at the command line:
\end_layout
\begin_layout LyX-Code
gpsim> two_pulse_repeat
\end_layout
\begin_layout LyX-Code
two_pulse_repeat attached to pulse_node
\end_layout
\begin_layout LyX-Code
Vth=0V Zth=250 ohms Cth=0 F nodeVoltage= 7.49998e-07V
\end_layout
\begin_layout LyX-Code
Driving=0 drivingState=0 drivenState=0 bitState=0
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
states = 5
\end_layout
\begin_layout LyX-Code
100 1
\end_layout
\begin_layout LyX-Code
200 0
\end_layout
\begin_layout LyX-Code
300 1
\end_layout
\begin_layout LyX-Code
400 0
\end_layout
\begin_layout LyX-Code
1000 0
\end_layout
\begin_layout LyX-Code
initial=0
\end_layout
\begin_layout LyX-Code
period=1000
\end_layout
\begin_layout LyX-Code
start_cycle=0
\end_layout
\begin_layout LyX-Code
Next break cycle=100
\end_layout
\begin_layout Standard
Even though this example uses 1's and 0's for the data, one can use integers,
floating point numbers, or expressions instead.
Integers are useful for supplying a stimulus to an attribute.
Expressions are useful for abstracting the data.
See Chapter
\begin_inset LatexCommand \ref{cha:Simulating-the-Real}
\end_inset
for more discussion and examples of stimuli.
\end_layout
\begin_layout Section
stopwatch
\begin_inset LatexCommand \index{stopwatch}
\end_inset
\begin_inset Foot
status collapsed
\begin_layout Standard
The stopwatch is really a collection of attributes and not a command.
But the behavior is so similar to a command that it has been included here.
\end_layout
\end_inset
\end_layout
\begin_layout LyX-Code
A timer for monitoring and controlling the simulation.
\end_layout
\begin_layout LyX-Code
The units are in simulation cycles.
\end_layout
\begin_layout LyX-Code
stopwatch.rollover - specifies rollover value.
\end_layout
\begin_layout LyX-Code
stopwatch.direction - specifies count direction.
\end_layout
\begin_layout LyX-Code
stopwatch.enable - enables counting if true.
\end_layout
\begin_layout Standard
Without any options,
\emph on
stopwatch
\emph default
will display the contents of the stopwatch timer.
\emph on
stopwatch
\emph default
is writable, so you may initialize it to whatever value you like.
The
\emph on
\emph default
behavior of the timer may be manipulated via the three attributes.
The
\emph on
.rollover
\emph default
attribute is the number of cycles at which the stopwatch timer rolls over.
The
\emph on
.direction
\emph default
and
\emph on
.enable
\emph default
attributes are boolean types.
When true, the
\emph on
.direction
\emph default
attribute will instruction the stopwatch to count up.
\end_layout
\begin_layout Section
trace
\begin_inset LatexCommand \index{trace}
\end_inset
\end_layout
\begin_layout LyX-Code
trace [dump_amount]
\end_layout
\begin_layout Standard
\emph on
trace
\emph default
will print out the most recent "dump_amount" traces.
If no dump_amount is specified, then the entire trace buffer will be displayed.
\end_layout
\begin_layout Section
version
\end_layout
\begin_layout LyX-Code
version
\end_layout
\begin_layout Standard
Display gpsim's version.
Note, this command will probably get replaced by an attribute with the
same (or similar) name.
\end_layout
\begin_layout Section
x
\begin_inset LatexCommand \index{x}
\end_inset
\end_layout
\begin_layout Standard
The
\emph on
x
\emph default
command is deprecated.
It's former use was to examine and modify memory.
The preferred way to do this now is with expressions.
The help for
\emph on
x
\emph default
now indicates this:
\end_layout
\begin_layout LyX-Code
x examine command -- deprecated
\end_layout
\begin_layout LyX-Code
Instead of the using a special command to examine and modify
\end_layout
\begin_layout LyX-Code
variables, it's possible to directly access them using gpsim's
\end_layout
\begin_layout LyX-Code
expression parsing.
For example, to examine a variable:
\end_layout
\begin_layout LyX-Code
gpsim> my_variable
\end_layout
\begin_layout LyX-Code
my_variable [0x27] = 0x00 = 0b00000000
\end_layout
\begin_layout LyX-Code
To modify a variable
\end_layout
\begin_layout LyX-Code
gpsim> my_variable = 10
\end_layout
\begin_layout LyX-Code
It's also possible to assign the value of register to another
\end_layout
\begin_layout LyX-Code
gpsim> my_variable = porta
\end_layout
\begin_layout LyX-Code
Or to assign the results of an expression:
\end_layout
\begin_layout LyX-Code
gpsim> my_variable = (porta ^ portc) & 0x0f
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Chapter
\begin_inset LatexCommand \label{cha:Graphical-User-Interface}
\end_inset
Graphical User Interface
\end_layout
\begin_layout Standard
FIXME: We could use a few illustrations here!
\end_layout
\begin_layout Standard
gpsim also provides a graphical user interface that simplifies some of the
drudgery associated with the cli.
It's possible to open windows to view all the details about your debug
environment.
To get the most out of your debugging session, you'll want to assemble
your code with gpasm (the gnupic assembler) and use the symbolic .cod files
it produces.
\end_layout
\begin_layout Section
Main window
\end_layout
\begin_layout Subsection
Menus
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
File->Open .stc or .cod files.
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
File->Quit Quit gpsim
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Windows->* Open/Close the windows.
\end_layout
\begin_layout Subsection
Buttons
\end_layout
\begin_layout Standard
(These are also found as keyboard bindings in the source windows.)
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Step Step one instruction
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Over Step until pc is after next instruction
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Finish Run to return address
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Run Run continuously
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Stop Stop execution
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Reset Reset CPU
\end_layout
\begin_layout Subsection
Simulation mode
\end_layout
\begin_layout Standard
This controls how gpsim simulates, and how the gui updates.
\end_layout
\begin_layout List
\labelwidthstring 0000000.00.0000
Never Don't ever update the gui when simulating.
This is the fastest mode.
You'll have to stop simulation by pressing Ctrl-C in the command line interface.
\end_layout
\begin_layout List
\labelwidthstring 0000000.00.0000
x\InsetSpace ~
cycles Update the gui every x cycles simulated.
\end_layout
\begin_layout List
\labelwidthstring 0000000.00.0000
every\InsetSpace ~
cycle Update the gui every cycle.
(you see everything, if you have filled up on coffee :-)
\end_layout
\begin_layout List
\labelwidthstring 0000000.00.0000
x\InsetSpace ~
ms\InsetSpace ~
animate Here you can slow down simulation with a delay between every
cycle.
\end_layout
\begin_layout List
\labelwidthstring 0000000.00.0000
realtime This will make gpsim try to synchronize simulation speed with wall
clock time.
\end_layout
\begin_layout Section
Source Browsers
\end_layout
\begin_layout Standard
gpsim provides two views of your source: '.
\emph on
asm'
\emph default
and '.
\emph on
obj'
\emph default
browsers.
The '.
\emph on
asm'
\emph default
browser is a color coded display of your pic source.
\end_layout
\begin_layout Subsection
.asm Browser
\end_layout
\begin_layout Standard
When a .cod file with source is loaded, there should be something in this
display.
(TODO: add section about high level debugging).
\end_layout
\begin_layout Standard
There is an area to the left of the source, where symbols representing the
program counter, breakpoints, etc are displayed.
Double clicking in this area toggles breakpoints.
You can drag these symbols up or down in order to move them and change
the PC or move a breakpoint.
\end_layout
\begin_layout Standard
A right button click on the source pops up a menu with six items (the word
'here' in some menu items denote the line in source the mouse pointer was
on when right mouse button was clicked.):
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
\series bold
Menu\InsetSpace ~
item Description
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
Find\InsetSpace ~
PC This menu item will find the PC and changed page tab and scroll the
source view to the current PC.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
Run\InsetSpace ~
here This sets a breakpoint 'here'and starts running until a breakpoint
is hit.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
Move\InsetSpace ~
PC\InsetSpace ~
here This simply changes PC to the address that line 'here'in source
has.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
Breakpoint\InsetSpace ~
here Set a breakpoint 'here'.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
Profile\InsetSpace ~
start\InsetSpace ~
here Set a start marker for routine profiling here.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
Profile\InsetSpace ~
stop\InsetSpace ~
here Set a stop marker.
(See the section for the profiling window.)
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
Select\InsetSpace ~
symbol.
This menu item is only available when some text is selected in the text
widget.
What it does is search the list of symbols for the selected word, and if
it is found it is selected in the symbol window.
Depending of type of symbol other things are also done, the same thing
as when selecting a symbol in the symbol window:
\end_layout
\begin_deeper
\begin_layout Itemize
If it is an address, then the opcode and source views display the address.
\end_layout
\begin_layout Itemize
If it's a register, the register viewer selects the cell.
\end_layout
\begin_layout Itemize
If it's a constant, address, register or ioport, it is selected in the symbol
window.
\end_layout
\end_deeper
\begin_layout List
\labelwidthstring 00.00.0000.0000
Find\InsetSpace ~
text This opens up a search dialog.
Every time you hit the 'Find' button, the current notebook page is found
and the source in that page is used.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
Settings A dialog with which you can change the fonts used.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000.0000
Controls A submenu containing the simulation commands.
(these are also found as keyboard bindings (recommended), or in the main
window.)
\end_layout
\begin_layout Standard
These are the keyboard bindings:
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000
\series bold
Key command
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000
s,S,F7 Step one instruction.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000
o,O,F8 Step over instruction
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000
r,R,F9 Run continously.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000
Escape Stop simulation.
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000
f,F Run to return address
\end_layout
\begin_layout List
\labelwidthstring 00.00.0000
1..9 Step n instructions
\end_layout
\begin_layout Subsection
Opcode view - the .obj Browser
\end_layout
\begin_layout Standard
This window has two tabs.
One with each memory cell on one line and information about address, hexadecima
l value and decoded instruction (i.e.
disassembly), and one with the program memory
\end_layout
\begin_layout Standard
displayed with sixteen memory cells per row and a configurable ascii column.
\end_layout
\begin_layout Subsubsection*
The Assembly tab you can:
\end_layout
\begin_layout Itemize
Double click on a line to toggle breakpoints.
\end_layout
\begin_layout Itemize
Use the same keyboard commands as the in the source browser.
\end_layout
\begin_layout Itemize
Right click to get a menu where you can change the fonts.
\end_layout
\begin_layout Subsubsection*
The Opcode tab.
\end_layout
\begin_layout Standard
Here the program memory is ordered as columns of sixteen memory cells per
column and as many row as needed to contain all memory.
\end_layout
\begin_layout Standard
The seventeenth column contains an ASCII representation of the program memory.
You can configure this column to use one of three different modes:
\end_layout
\begin_layout Itemize
One byte per cell
\end_layout
\begin_layout Itemize
Two bytes per cell, MSB first.
\end_layout
\begin_layout Itemize
Two bytes per cell, LSB first.
\end_layout
\begin_layout Standard
You can change fonts with the menu item 'Settings'.
\end_layout
\begin_layout Standard
You can set breakpoints on one or more (drag the mouse to select more cells)
addresses with the right click menu.
\end_layout
\begin_layout Section
Register views
\end_layout
\begin_layout Standard
There are two similar register windows.
One for the RAM and one for the EEPROM data, when available.
\end_layout
\begin_layout Standard
Here you see all registers in the current processor.
Clicking on a cell displays it's name and value above the sheet of registers.
You can change values by entering it in the entry (or in the spreadsheet
cell).
\end_layout
\begin_layout Standard
The following things can be done on one register, or a range of registers.
(Selecting a range of registers is done by holding down left mouse button,
moving cursor, and releasing button.)
\end_layout
\begin_layout Itemize
Set and clear breakpoints.
Use the right mousebutton menu to pop up a menu where you can select set
read, write, read value and write value breakpoints.
You can also "clear breakpoints", notice the s in "clear breakpoints",
every breakpoint on the registers are cleared.
\end_layout
\begin_layout Itemize
Set and clear logging of registers.
You can log reads, writes, reads/writes of specific values and to bits
selected by a specified mask.
You can select a different file name with 'set log filename...'.
Default is "gpsim.log".
You can choose LXT or ASCII format.
LXT can be read with the program gtkwave.
ASCII is default.
\end_layout
\begin_layout Itemize
Copy cells.
You copy cells by dragging the border of the selected cell(s).
\end_layout
\begin_layout Itemize
Fill cells.
Move mouse to lower right corner of the frame of the selected cell(s),
and drag it.
The one cell's contents will be copied to the other cells.
\end_layout
\begin_layout Itemize
Watch them.
Select the "Add Watch" menu item.
\end_layout
\begin_layout Standard
The cells have different background colors depending on if they represent:
\end_layout
\begin_layout Itemize
File Register (e.g.
RAM): light cyan.
\end_layout
\begin_layout Itemize
Special Function Registers (e.g.
STATUS,TMR0): dark cyan
\end_layout
\begin_layout Itemize
aliased register (e.g.
the INDF located at address 0x80 is the same as the one located at address
0x00): gray
\end_layout
\begin_layout Itemize
invalid register: black.
If all sixteen registers in a row are invalid, then the row is not shown.
\end_layout
\begin_layout Itemize
a register with one or more breakpoints: red.
Logged registers are also red.
\end_layout
\begin_layout Standard
gpsim dynamically updates the registers as the simulation proceeds.
Registers that change value between updates of the window during simulation
are highlighted with a blue foreground color.
\end_layout
\begin_layout Standard
The menu also has a 'settings' item where you can change the font used.
\end_layout
\begin_layout Section
Symbol view
\end_layout
\begin_layout Standard
This window, as its name suggests, displays symbols.
All of the special function registers will have entries in the symbol viewer.
If you're using .cod files then you'll additionally have file registers
(that are defined in cblocks), equates, and address labels.
\end_layout
\begin_layout Standard
You can filter out some symbol types using the buttons in the top of the
window, and you can sort the rows by clicking on the column buttons (the
ones reading 'symbol', 'type' and 'address').
\end_layout
\begin_layout Standard
You can add the symbol to the watch window by right-clicking and selecting
the "Add to watch window" menu item.
This will add the ram register with address equal to the symbols value
to the watch window.
\end_layout
\begin_layout Standard
The symbol viewer is linked to the other windows.
For example, if you click on a symbol and:
\end_layout
\begin_layout Itemize
If it is an address, then the opcode and source views display the address.
\end_layout
\begin_layout Itemize
If it's a register, the register viewer selects the cell.
\end_layout
\begin_layout Section
Watch view
\end_layout
\begin_layout Standard
This is not a output-only window as the name suggests (change name?).
You can both view and change data.
Double-clicking on a bit toggles the bit.
You add variables here by marking them in a register viewer and select
\begin_inset Quotes eld
\end_inset
Add watch
\begin_inset Quotes erd
\end_inset
from menu.
The right-click menu has the following items:
\end_layout
\begin_layout Itemize
Remove watch
\end_layout
\begin_layout Itemize
Set register value
\end_layout
\begin_layout Itemize
Clear Breakpoints
\end_layout
\begin_layout Itemize
Set break on read
\end_layout
\begin_layout Itemize
Set break on write
\end_layout
\begin_layout Itemize
Set break on read value
\end_layout
\begin_layout Itemize
Set break on write value
\end_layout
\begin_layout Itemize
Columns...
\end_layout
\begin_layout Standard
"Columns...
\begin_inset Quotes erd
\end_inset
opens up a window where you can select which of the following data to display:
\end_layout
\begin_layout Itemize
BP
\end_layout
\begin_layout Itemize
Type
\end_layout
\begin_layout Itemize
Name
\end_layout
\begin_layout Itemize
Address
\end_layout
\begin_layout Itemize
Dec
\end_layout
\begin_layout Itemize
Hex
\end_layout
\begin_layout Itemize
Bx (bits of word)
\end_layout
\begin_layout Standard
You can sort the list of watches by clicking on the column buttons.
Clicking twice sorts the list backwards.
\end_layout
\begin_layout Section
Stack viewer
\end_layout
\begin_layout Standard
This window displays current stack.
Selecting an entry makes the code windows display the return address.
Double clicking sets a breakpoint on the return address.
\end_layout
\begin_layout Section
Breadboard
\end_layout
\begin_layout Standard
Here you can create/modify and examine the environment around the pic.
Pins are displayed as an arrow.
The direction of the arrow indicates if its an input or output pin.
The color of the arrow indicates its state (green=low, red=high).
\end_layout
\begin_layout Standard
You can't instantiate pic processors from here, you'll have to do that from
the command line, or from a .stc file.
\end_layout
\begin_layout Standard
Your can create nodes by clicking on the "new node" button.
(A node is 'a piece of wire' to which you can connect stimulus.) You can
see the list of created nodes under the "nodes" item in the upper-left
tree widget.
\end_layout
\begin_layout Standard
You can create connections to nodes by clicking on a pin, and then clicking
on the button "Connect stimulus to node".
This will bring up a list of nodes.
Choose one by double-clicking on the one you like.
\end_layout
\begin_layout Standard
If you click on a pin that is already connected to a node, then you'll see
the node and its connections in the lower left part of the window.
You can disconnect a stimulus by clicking on it and pressing the "remove
stimulus" button.
\end_layout
\begin_layout Standard
When you want to add a module to the simulation, you first have to specify
the library which contains the module you want.
Click on the "add library" button and enter the library name (e.g.
"libgpsim_modules.so").
Now you can click the "add module" button.
Select the module you want from the list by double-clicking on it.
Enter a name for the module (this has to be unique, and not used before).
You now have to position the module.
Move the mouse pointer to where you'd like the module, and left-click.
\end_layout
\begin_layout Standard
If you middle-click on a pin, you'll see how the pin is connected.
Press the "trace all" to see all at
\end_layout
\begin_layout Standard
once, and "clear traces" to remove all (you'll only remove the graphical
trace, not the connection!).
If the tracing doesn't work, try moving the packages so that there are
more space around the pins.
\end_layout
\begin_layout Standard
When you are done, you can save by clicking the "save configuration" button.
You can then load this file from the command line like this (assuming the
.cod file with your source is called "mycode.cod", and the file you just
saved was called "mynets.stc":
\end_layout
\begin_layout LyX-Code
gpsim -s mycode.cod -c mynets.stc
\end_layout
\begin_layout Standard
You can't load only the .stc file since this doesn't contain the processor
type and code.
You can create (with an editor) your own .stc file (e.g.
my_project.stc) and in that file put a command "load c mynets.stc" after
you have loaded the .cod file.
You then only have to load this file (gpsim -c my_project.stc).
\end_layout
\begin_layout Section
Trace viewer
\end_layout
\begin_layout Standard
This window shows the trace of instructions executed.
See
\begin_inset LatexCommand \ref{trace}
\end_inset
.
\end_layout
\begin_layout Section
Profile viewer
\end_layout
\begin_layout Standard
This window show execution count for program memory addresses.
The profile window must be opened before starting simulation, because the
traceing is not enabled by default.
\end_layout
\begin_layout Subsubsection
Instruction profile
\end_layout
\begin_layout Standard
This shows the number of times each instruction are executed.
\end_layout
\begin_layout Subsubsection
Instruction range profile
\end_layout
\begin_layout Standard
Here you can group ranges of instruction into one entry.
\end_layout
\begin_layout Standard
The right click menu contains:
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Remove\InsetSpace ~
range Remove an entry.
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Add\InsetSpace ~
range...
Open a disalog from where you can add a range of instructions as an entry.
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Add\InsetSpace ~
all\InsetSpace ~
labels Add all code labels as ranges.
\end_layout
\begin_layout List
\labelwidthstring 00000000.00.0000
Snapshot\InsetSpace ~
to\InsetSpace ~
plot Open a window containing a graph of the data.
From this new window you can also save (postscript) or print it.
\end_layout
\begin_layout Subsubsection*
Register profile
\end_layout
\begin_layout Standard
This shows the number of reads or writes the simulator does on register.
\end_layout
\begin_layout Subsubsection*
Routine profile
\end_layout
\begin_layout Standard
Here you can see statistics about execution time for a selected routine.
You mark the entry and exit points from the source browser (profile start/stop).
If the routine you want to measure have multiple entry and/or exit points,
then you have to put a marker on every entry point as well as (and especially)
every exit point.
Othervise you will get bad data.
\end_layout
\begin_layout Standard
When you have done that, gpsim will (as simulation goes by) store the execution
times of that routine and calculate min/max/average/etc.
You can also use the menu item 'Plot distribution' to open a window displaying
a histogram of the data.
From this new window you can also save (in postscript) or print it.
\end_layout
\begin_layout Standard
You can also measure call period by switching the 'entry' and 'exit' points.
If also want the time from reset (or some equal point) to the first 'entry',
then you must also put an 'entry' point there.
\end_layout
\begin_layout Section
Stopwatch
\end_layout
\begin_layout Standard
The stopwatch window shows a cycle counter and a re-settable counter.
The cycle counter is the same as the one in the register window.
It basically counts instructions.
\end_layout
\begin_layout Standard
The other counter counts at the same rate as the cycle counter, but can
be cleared by clicking the "clear" button (or preset by entering a number
in the entry box).
\end_layout
\begin_layout Standard
The up/down indicator denotes the direction the counter counts.
\end_layout
\begin_layout Standard
The rollover value specifies the range the cycle counter can be in (a modulo
counter).
For example, if the rollover value is specified to be 0x42, then whenever
the resettable counter reaches 0x42 it will rollover to zero.
If the counter is counting down, then when it reaches 0 the next state
will be 0x41.
If you don't want is like this, then set the rollover value to something
large.
\end_layout
\begin_layout Section
Scope Window
\end_layout
\begin_layout Standard
FIXME: The scope window still needs some work...
\end_layout
\begin_layout Standard
The Scope Window graphs I/O pin states.
It is similar to an oscilloscope or logic analyzer.
It can be controlled either from the command line or from the gui.
Currently only the digital state of I/O pins are supported.
\end_layout
\begin_layout Chapter
Scripting and Configuring
\end_layout
\begin_layout Standard
gpsim does not have a native scripting language per se.
However it is possible to place gpsim commands into a file and load them
later.
This is useful for loading modules and stimuli and connecting various devices
together.
By convention, gpsim's configuration files have the extension
\emph on
.stc
\emph default
, for
\emph on
st
\emph default
artup
\emph on
c
\emph default
onfiguration.
\end_layout
\begin_layout Section
Embedded Commands
\end_layout
\begin_layout Standard
If you're using gputils, it is possible to embed configuration commands
directly into your PIC assembly source.
The gputils supplied include file
\emph on
coff.inc
\emph default
contains several macros that embed simulation command into a COFF and COD
files.
\end_layout
\begin_layout Subsection
.sim macro
\end_layout
\begin_layout LyX-Code
; Simulator Command
\end_layout
\begin_layout LyX-Code
.sim macro x
\end_layout
\begin_layout LyX-Code
.direct "e", x
\end_layout
\begin_layout LyX-Code
endm
\end_layout
\begin_layout Standard
The
\family typewriter
\emph on
.sim
\emph default
macro allows gpsim configuration commands to be embedded in the PIC source.
While gpsim loads a .cod file, the commands in the
\emph on
.sim
\emph default
macros are collected.
After the .cod file is loaded, the commands are redirected to gpsim's command
line interpreter in the order they were received.
\end_layout
\begin_layout Standard
Here's an example of switch module being loaded and configured:
\end_layout
\begin_layout LyX-Code
;# Module libraries:
\end_layout
\begin_layout LyX-Code
.sim "module library libgpsim_modules"
\end_layout
\begin_layout LyX-Code
.sim "module load switch SW1"
\end_layout
\begin_layout LyX-Code
.sim "SW1.state=false"
\end_layout
\begin_layout LyX-Code
.sim "SW1.xpos = 216.0"
\end_layout
\begin_layout LyX-Code
.sim "SW1.ypos = 156.0"
\end_layout
\begin_layout LyX-Code
.sim "SW1.Ropen = 1.0e8"
\end_layout
\begin_layout Standard
This loads gpsim's module library, instantiates a switch module, and configures
the switch's attributes.
\end_layout
\begin_layout Subsection
.command macro
\end_layout
\begin_layout LyX-Code
.command macro x
\end_layout
\begin_layout LyX-Code
.direct "c", x
\end_layout
\begin_layout LyX-Code
endm
\end_layout
\begin_layout Standard
The
\family typewriter
\emph on
.command
\emph default
macro is similar to a
\emph on
.sim
\emph default
macro except that it associates a gpsim command with a particular instruction.
This is useful for changing attribute values at different points of the
program.
\end_layout
\begin_layout Subsection
.assert macro
\end_layout
\begin_layout LyX-Code
; Assertion
\end_layout
\begin_layout LyX-Code
.assert macro x
\end_layout
\begin_layout LyX-Code
.direct "a", x
\end_layout
\begin_layout LyX-Code
endm
\end_layout
\begin_layout Standard
The
\emph on
.assert
\emph default
macro provides a source code mechanism for setting breakpoints (see chapter
\begin_inset LatexCommand \ref{cha:Assertions-and-Extended}
\end_inset
).
An assertion is an expression associated with a specific instruction.
It essential means,
\begin_inset Quotes eld
\end_inset
If the expression at this instruction evaluates to false, then halt the
simulation.
\begin_inset Quotes erd
\end_inset
\end_layout
\begin_layout LyX-Code
; Close the switch because of capacitance portc1 will go high after a
delay:
\end_layout
\begin_layout LyX-Code
; R=145, C=4.2e-6 TC=6.11e-4 or 1527 cycles 0-2 volts requires 0.51 Tc
\end_layout
\begin_layout LyX-Code
.command "SW1.state=true"
\end_layout
\begin_layout LyX-Code
nop
\end_layout
\begin_layout LyX-Code
; portc0 should be same as portc1
\end_layout
\begin_layout LyX-Code
.assert "(portc & 3) == 0,
\backslash
"SW1 closed, cap holds low
\backslash
""
\end_layout
\begin_layout LyX-Code
nop
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Standard
In this example, the
\emph on
.command
\emph default
macro writes to the switch module's
\emph on
.state
\emph default
attribute (see section
\begin_inset LatexCommand \ref{sub:Switches-&-Resistors}
\end_inset
).
Just prior to executing the first nop instruction, the switch will be closed.
The
\emph on
.assert
\emph default
macro at the very next instruction makes sure that the expected state is
seen on PORTC.
\end_layout
\begin_layout Section
Sockets
\end_layout
\begin_layout Standard
gpsim supports a socket interface.
This is inhibited by default.
Advanced users may wish to study code in the
\emph on
examples/scripts
\emph default
subdirectory.
This code not distributed and is only available in the subversion repository.
\end_layout
\begin_layout Chapter
\begin_inset LatexCommand \label{cha:Assertions-and-Extended}
\end_inset
Assertions and Extended Breakpoints
\end_layout
\begin_layout Standard
gpsim supports a wide variety of breakpoints and assertions.
Many of these were described with the break command.
This section will illustrate how to extend the break command even further
and introduce simulation assertions.
\end_layout
\begin_layout Subsection*
Breakpoint Messages
\end_layout
\begin_layout Standard
A breakpoint message is an ASCII string that is displayed whenever a breakpoint
is encountered.
Any break point can have an associated message.
The syntax at the command line is
\end_layout
\begin_layout LyX-Code
break conditions,
\begin_inset Quotes eld
\end_inset
\emph on
This is a breakpoint message
\emph default
\begin_inset Quotes erd
\end_inset
\end_layout
\begin_layout Standard
The conditions are described above in the break command and are the conditions
under which the break occurs.
\end_layout
\begin_layout Standard
Breakpoint messages are useful for distinguishing among many different breakpoin
ts.
\end_layout
\begin_layout LyX-Code
break w counter & 0xf0 == 0x80,
\begin_inset Quotes eld
\end_inset
Counter overflowed!
\begin_inset Quotes erd
\end_inset
\end_layout
\begin_layout Standard
In this example, the user is monitoring the upper nibble of the variable
counter and breaking whenever it is equal to 8.
When the command is entered, gpsim will display:
\end_layout
\begin_layout LyX-Code
break when bit pattern 1000XXXX is written to register counter(0x26).
break #: 0x20
\end_layout
\begin_layout Standard
The breakpoint can be queried with the break command:
\end_layout
\begin_layout LyX-Code
gpsim>
\emph on
break 32
\end_layout
\begin_layout LyX-Code
32: p18f452 register write value: [0x26] & 0xf0 == 0x8
\end_layout
\begin_layout LyX-Code
Message:Counter overflowed!
\end_layout
\begin_layout Standard
When the simulation encounters the break, execution halts and the message
is printed.
\end_layout
\begin_layout Section
Assertions and Embedded Simulation commands
\end_layout
\begin_layout Standard
gpsim's breakpoint design is a powerful tool that can catch many problems.
The assertion design extends this power even further.
An assertion is like a breakpoint that is associated with a particular
instruction.
For example, you may have a routine that requires BANK 0 be selected.
A gpsim assertion can be placed at the entry of the routine to verify that
this is the case.
\end_layout
\begin_layout LyX-Code
.assert
\begin_inset Quotes eld
\end_inset
(status & 0x60) == 0,
\backslash
\begin_inset Quotes erd
\end_inset
Bank 0 must be selected!
\backslash
\begin_inset Quotes erd
\end_inset
\begin_inset Quotes erd
\end_inset
\end_layout
\begin_layout Standard
The syntax is identical to the extended breakpoint command.
The expression is the condition that is checked.
If the expression evaluates to false, then the code halts and prints the
message.
The
\emph on
.assert
\emph default
is a macro that is part of gputils.
It requires a string as its input argument.
Notice that the assertion message is embedded in the argument.
gpasm and MPASM copy C's method of placing a backslash in front of quotations
that are part of a string.
\end_layout
\begin_layout Subsection*
Command Assertions
\end_layout
\begin_layout Standard
A command assertion is a gpsim associated with a particular instruction
in your PIC source code.
These are useful for changing the behavior of the simulation based on where
the code executes.
Almost any gpsim command can be placed in a command assertion.
However, the most useful ones are assignment commands.
For example:
\end_layout
\begin_layout LyX-Code
.command
\begin_inset Quotes eld
\end_inset
SW1.state = false
\begin_inset Quotes erd
\end_inset
\end_layout
\begin_layout Standard
This assignment writes to the state attribute of a switch module named SW1.
\end_layout
\begin_layout Chapter
Trace and Log: What has happen?
\begin_inset LatexCommand \label{trace}
\end_inset
\end_layout
\begin_layout Standard
Inspecting the current state of your program is sometimes insufficient to
determine the cause of a bug.
Often times it's useful to know the conditions that led up to the current
state.
gpsim provides a history or trace of everything that occurs - whether you
want it or not - to help you diagnose these otherwise difficult to analyze
bugs.
\end_layout
\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset
\end_layout
\begin_layout Standard
\align center
\begin_inset Tabular
|
\begin_inset Text
\begin_layout Standard
What's traced
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
notes
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
program counter
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
adresses executed
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
instructions
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
opcode
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
register read
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
value and location
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
register write
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
value and location
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
cycle counter
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
current value
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
skipped instructions
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
addresses skipped
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
status register
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
during implicit modification
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
interrupts
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
break points
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
type
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
resets
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
type
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
\end_inset
\end_layout
\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset
\end_layout
\begin_layout Standard
The 'trace' command will dump the contents of the trace buffer.
\end_layout
\begin_layout Standard
A large circular buffer (whose size is hard coded) stores the information
for the trace buffer.
When it fills, it will wrap around and write over the old history.
The contents of the trace buffer are parsed into frames, where one frame
corresponds to a simulation cycle.
\end_layout
\begin_layout Standard
Here's an example of a trace output:
\end_layout
\begin_layout LyX-Code
gpsim> trace
\end_layout
\begin_layout LyX-Code
0x00000000000026F6 p18f452 0x001C 0x1003 iorwf reg3,w,0
\end_layout
\begin_layout LyX-Code
Read: 0x00 from reg3(0x0003)
\end_layout
\begin_layout LyX-Code
Wrote: 0xE7 to W(0x0FE8) was 0xE7
\end_layout
\begin_layout LyX-Code
Wrote: 0x18 to status(0x0FD8) was 0x18
\end_layout
\begin_layout LyX-Code
0x00000000000026F7 p18f452 0x001E 0xE1F4 bnz $-0x16 ;(0x8)
\end_layout
\begin_layout LyX-Code
0x00000000000026F8 p18f452 0x0008 0x3E00 incfsz reg,f,0
\end_layout
\begin_layout LyX-Code
Read: 0xE4 from reg(0x0000)
\end_layout
\begin_layout LyX-Code
Wrote: 0xE5 to reg(0x0000) was 0xE4
\end_layout
\begin_layout LyX-Code
0x00000000000026F9 p18f452 0x000A 0xD004 bra $+0xa ;(0x00014) 0x00000000000
026FA p18f452 0x0014 0x0004 clrwdt
\end_layout
\begin_layout LyX-Code
0x00000000000026FB p18f452 0x0016 0x5000 movf reg,w,0
\end_layout
\begin_layout LyX-Code
Read: 0xE5 from reg(0x0000)
\end_layout
\begin_layout LyX-Code
Wrote: 0xE5 to W(0x0FE8) was 0xE7
\end_layout
\begin_layout LyX-Code
Wrote: 0x18 to status(0x0FD8) was 0x18
\end_layout
\begin_layout LyX-Code
0x00000000000026FC p18f452 0x0018 0x1001 iorwf reg1,w,0
\end_layout
\begin_layout LyX-Code
Read: 0x03 from reg1(0x0001)
\end_layout
\begin_layout LyX-Code
Wrote: 0xE7 to W(0x0FE8) was 0xE5
\end_layout
\begin_layout LyX-Code
Wrote: 0x18 to status(0x0FD8) was 0x18
\end_layout
\begin_layout Standard
Each trace frame begins with a new simulation cycle.
Typically this will include a simulated instruction.
Here's each of the fields:
\end_layout
\begin_layout LyX-Code
\begin_inset Tabular
|
\begin_inset Text
\begin_layout Standard
64-bit simulation cycle
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
processor
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
PC
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
opcode
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
instruction
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
0x00000000000026F6
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
p18f452
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
0x001C
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
0x1003
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
iorwf reg3,w,0
\end_layout
\end_inset
|
\end_inset
\end_layout
\begin_layout Standard
Other events that occur during the trace frame are indented.
Typically these will be register read or write traces.
The read traces show the value read.
Write traces show the value written and the value that was previously in
the register.
\end_layout
\begin_layout Section*
Saving Trace to a file
\end_layout
\begin_layout Standard
The trace buffer may contain thousands of entries making it difficult to
search.
The trace save feature will allow the trace buffer to be written to a file.
\end_layout
\begin_layout LyX-Code
gpsim> trace save mytrace.log
\end_layout
\begin_layout Standard
The entire contents of the trace buffer are decoded and written to the file.
The format of the trace is the same as it is when displayed at the command
line.
\end_layout
\begin_layout Section*
Raw Traces
\end_layout
\begin_layout Standard
The
\emph on
raw
\emph default
trace buffer is the trace buffer displayed in a minimally decoded form.
This is primarily used for gpsim development.
When saved to a file, the raw trace is not decoded at all.
In addition, the processor's state is written to the file.
Thus third party tools can be written to create custom trace reports
\begin_inset Foot
status collapsed
\begin_layout Standard
FIXME - The dynamically created trace type information needs to be written
to this file too.
Without it, it is difficult to tell what each traced item is.
\end_layout
\end_inset
.
\end_layout
\begin_layout Chapter
\begin_inset LatexCommand \label{cha:Simulating-the-Real}
\end_inset
Simulating the Real World: Stimuli
\begin_inset LatexCommand \index{Stimulus}
\end_inset
\end_layout
\begin_layout Standard
Stimuli are extremely useful, if not necessary, for simulations.
They provides a means for simulating interactions with the real world.
\end_layout
\begin_layout Standard
The gpsim stimuli capability is designed to be accurate, efficient and flexible.
The models for the PIC's I/O pins mimic the real devices.
For example, the open collector output on port A of a PIC16C84 can only
drive low.
Multiple I/O pins may be tied to one another so that the open collector
on port A can get a pull up resistor from port B.
The overhead for stimuli only occurs when a stimulus changes states.
In other words, stimuli are not polled to determine their state.
\end_layout
\begin_layout Standard
Analog stimuli are also available.
It's possible to create voltage references and sources to simulate almost
any kind of real world thing.
For example, it's possible to combine two analog stimuli together to create
signals like DTMF tones.
\end_layout
\begin_layout Section
How They Work
\end_layout
\begin_layout Standard
In the simplest case, a stimulus acts a source for an I/O pin on a PIC.
For example, you may want to simulate a clock and measure its period using
TMR0.
In this case, the stimulus is the source and the TMR0 input pin on the
pic is the load.
In gpsim you would create a stimulus for the clock using the stimulus command
and connect it to the I/O pin using the node command.
\end_layout
\begin_layout Standard
In general, you can have several 'sources' and several 'loads' that are
interconnected with nodes
\begin_inset Foot
status collapsed
\begin_layout Standard
Although, gpsim is currently limited to 'one-port' devices.
In other words, it is assumed that ground serves as a common reference
for the sources and the loads.
\end_layout
\end_inset
.
A good analogy is a spice circuit.
The spice netlist corresponds to a node-list in gpsim and the spice elements
correspond to the stimuli sources and loads.
This general approach makes it possible to create a variety of simulation
environments.
Here's a list of different ways in which stimuli may be connected:
\end_layout
\begin_layout Enumerate
Stimulus connected to one I/O pin
\end_layout
\begin_layout Enumerate
Stimulus connected to several I/O pins
\end_layout
\begin_layout Enumerate
Several stimuli connected to one I/O pin
\end_layout
\begin_layout Enumerate
Several stimuli connected to several I/O pins
\end_layout
\begin_layout Enumerate
I/O pins connected to I/O pins
\end_layout
\begin_layout Standard
The general technique for implementing stimuli is as follows:
\end_layout
\begin_layout Enumerate
Define the stimulus or stimuli.
\end_layout
\begin_layout Enumerate
Define a node.
\end_layout
\begin_layout Enumerate
Attach the stimuli to the node.
\end_layout
\begin_layout Standard
More often than not, the stimulus definition will reside in a file.
\end_layout
\begin_layout Subsection
Contention among stimuli
\end_layout
\begin_layout Standard
One of the problems with this nodal approach to modeling stimuli is that
it's possible for contention to exist.
For example, if two I/O pins are connected to one another and driving in
the opposite directions, there will be contention.
gpsim resolves contention with attribute summing.
Each stimulus - even if it's an input - has an effect on the node.
This effect is characterised by a voltage and an impedance.
When a node is updated, gpsim performs a Thevenin voltage summing of all
the stimuli together.
The resultant voltage is then propagated to all connected stimuli as the
current state of the node.
\end_layout
\begin_layout Standard
For example, in the port A open collector / port B weak pull-up connection
example, gpsim assigns a voltage of 5V with an impedance of 20kohms to
the pull up resistor, and a voltage of 0V with an impedance of 150ohms
to the open collector if it is active, or 100Mohms if it's not driving.
The Thevenin sum will be roughly 0.05V if the output is driving, or 5V otherwise.
Capacitive effects are not currently supported.
\end_layout
\begin_layout Section
I/O Pins
\end_layout
\begin_layout Standard
gpsim models I/O pins as stimuli.
Thus anywhere a stimulus is used, an I/O pin may be substituted.
For example, you may want to tie two I/O pins to one another; like a port
B pull up resistor to a port A open collector.
gpsim automatically creates the I/O pin stimuli whenever a processor is
created.
All you need to do is to specify a node and then attach the stimuli to
it.
The names of these stimuli are formed by concatenating the port name with
the bit position of the I/O pin.
For example, bit 3 in port B is called portb3.
\end_layout
\begin_layout Standard
Here's a list of the types of I/O pin stimuli that are supported:
\end_layout
\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset
\end_layout
\begin_layout Standard
\align center
\begin_inset Tabular
|
\begin_inset Text
\begin_layout Standard
I/O Pin Type
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Function
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
INPUT_ONLY
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Only accepts input (like MCLR)
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
BI_DIRECTIONAL
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Can be a source or a load (most I/O pins)
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
BI_DIRECTIONAL_PU
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
PU=Pullup resistor (PORTB)
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
OPEN_COLLECTOR
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Can only drive low (RA4 on c84)
\end_layout
\end_inset
|
\end_inset
\end_layout
\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset
\end_layout
\begin_layout Standard
There is no special pin type for analog I/O pins.
All pic analog inputs are multiplexed with digital inputs.
The I/O pin definition will always be for the digital input.
gpsim automatically knows when I/O pin is analog input.
\end_layout
\begin_layout Section
Asynchronous Stimuli
\end_layout
\begin_layout Standard
Asynchronous stimuli are analog or digital stimuli that can change states
at any given instant (limited to the resolution of the cycle counter).
They can be defined to be repetitive too.
\end_layout
\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset
\end_layout
\begin_layout Standard
\align center
\begin_inset Tabular
|
\begin_inset Text
\begin_layout Standard
parameter
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
function
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
start_cycle
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
The # of cycles before the stimulus starts
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
cycles[]
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
An array of cycle #'s
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
data[]
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Stimulus state for a cycle
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
period
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
The # of cycles for one period
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
initial_state
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
The initial state before data[0]
\end_layout
\end_inset
|
\end_inset
\end_layout
\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset
\end_layout
\begin_layout Standard
When the stimulus is first initialized, it will be driven to the 'initial
state' and will remain there until the cpu's instruction cycle counter
matches the specified 'start' cycle.
After that, the two arrays 'cycles[]' and 'data[]' define the stimulus'
outputs.
The size of the arrays are the same and correspond to the number of events
that are to be created.
So the event number, if you will, serves as the index into these arrays.
The 'cycles[]' array define when the events occur while the 'data[]' array
defines the states the stimulus will enter.
The 'cycles[]' are measured with respect to the 'start' cycle.
The asynchronous stimulus can be made periodic by specifying the number
of cycles in the 'period' parameter.
\end_layout
\begin_layout Standard
Here's an example that generates three pulses and then repeats:
\end_layout
\begin_layout LyX-Code
stimulus asynchronous_stimulus # or we could've used asy
\newline
\end_layout
\begin_layout LyX-Code
# The initial state AND the state the stimulus is when
\end_layout
\begin_layout LyX-Code
# it rolls over
\newline
\end_layout
\begin_layout LyX-Code
initial_state 1
\newline
\end_layout
\begin_layout LyX-Code
# all times are with respect to the cpu's cycle counter
\end_layout
\begin_layout LyX-Code
start_cycle 100
\newline
\end_layout
\begin_layout LyX-Code
# the asynchronous stimulus will roll over in 'period'
\newline
# cycles.
Delete this line if you don't want a roll over.
\end_layout
\begin_layout LyX-Code
period 5000
\newline
\end_layout
\begin_layout LyX-Code
# Now the cycles at which stimulus changes states are
\end_layout
\begin_layout LyX-Code
# specified.
The initial cycle was specified above.
So
\newline
# the first cycle specified below will toggle this state.
\end_layout
\begin_layout LyX-Code
# In this example, the stimulus will start high.
\end_layout
\begin_layout LyX-Code
# At cycle 100 the stimulus 'begins'.
However nothing happens
\end_layout
\begin_layout LyX-Code
# until cycle 200+100.
\end_layout
\begin_layout LyX-Code
{ 200, 0,
\end_layout
\begin_layout LyX-Code
300, 1,
\end_layout
\begin_layout LyX-Code
400, 0,
\end_layout
\begin_layout LyX-Code
600, 1,
\end_layout
\begin_layout LyX-Code
1000, 0,
\end_layout
\begin_layout LyX-Code
3000, 1 }
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
# Give the stimulus a name:
\end_layout
\begin_layout LyX-Code
name asy_test
\newline
\end_layout
\begin_layout LyX-Code
# Finally, tell the command line interface that we're done
\end_layout
\begin_layout LyX-Code
# with the stimulus
\end_layout
\begin_layout LyX-Code
end
\end_layout
\begin_layout Subsection
Analog Asynchronous Stimuli
\end_layout
\begin_layout Standard
Analog Asynchronous Stimuli are identical to Synchronous Stimuli except
the data points are floating point numbers.
\end_layout
\begin_layout Section
Extended Stimuli
\end_layout
\begin_layout Standard
Discuss the extended stimuli in the modules/ directory.
In particular, describe the
\emph on
PulseGen
\emph default
module and how it can complete replace the asynchronous stimuli.
Also describe the
\emph on
PullUp
\emph default
and
\emph on
PullDown
\emph default
modules and how they can be manipulated into being general purpose DC voltage
sources (FIXME, would it make sense to rename these modules?).
\end_layout
\begin_layout Chapter
Modules
\begin_inset LatexCommand \index{Modules}
\end_inset
\begin_inset LatexCommand \label{cha:Modules}
\end_inset
\end_layout
\begin_layout Standard
gpsim has been designed to debug microprocessors.
However, microprocessors are always a part of a system.
And invariably, the bugs one often encounters are those that are a result
of interfacing with a system.
Modules provide users with a way to extend gpsim and simulate a system.
For example, the
\emph on
system
\emph default
may be a processor with a few pull up resistors and switches or it may
be a processor and an LCD display.
gpsim provides a few modules that one may use either for debugging or as
templates for creating new modules.
\end_layout
\begin_layout Standard
Modules reside in a library and are dynamically loaded with the
\emph on
module
\emph default
command.
All modules have I/O pins which can connect to other modules or processors.
Most modules provide
\emph on
attributes
\emph default
that allow the user to control a module's behavior or query its internal
state.
For example, the USART module has transmit and receive baud rate attributes
that may be configured:
\end_layout
\begin_layout LyX-Code
gpsim> U1.txbaud = 9600 # set the transmit rate
\end_layout
\begin_layout LyX-Code
gpsim> U1.rxbaud # query the receiver rate
\end_layout
\begin_layout LyX-Code
9600
\end_layout
\begin_layout Standard
The symbol command can be used to query all attributes of a module.
\end_layout
\begin_layout LyX-Code
gpsim> symbol U1.
# note the period
\end_layout
\begin_layout LyX-Code
U1 = USARTModule
\end_layout
\begin_layout LyX-Code
U1.console = false
\end_layout
\begin_layout LyX-Code
U1.crlf = true
\end_layout
\begin_layout LyX-Code
U1.loop = true
\end_layout
\begin_layout LyX-Code
U1.rx = 0
\end_layout
\begin_layout LyX-Code
U1.rxbaud = 9600
\end_layout
\begin_layout LyX-Code
U1.tx = 0
\end_layout
\begin_layout LyX-Code
U1.txbaud = 9600
\end_layout
\begin_layout LyX-Code
U1.xpos = 72.00000000000000
\end_layout
\begin_layout LyX-Code
U1.ypos = 276.0000000000000
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Standard
Modules may provide only help which can be accessed using the help command:
\end_layout
\begin_layout LyX-Code
gpsim> help U1
\end_layout
\begin_layout LyX-Code
USARTModule
\end_layout
\begin_layout LyX-Code
no description
\end_layout
\begin_layout Standard
Well, the USART module isn't the best example here! However, a better example
is one of the USART attributes.
\end_layout
\begin_layout LyX-Code
gpsim> help U1.txbaud
\end_layout
\begin_layout LyX-Code
9600
\end_layout
\begin_layout LyX-Code
USART Module Transmitter baud rate
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Section
gpsim Modules
\end_layout
\begin_layout Standard
gpsim provides a library of useful modules for simulation.
The current version includes the following modules:
\end_layout
\begin_layout Standard
\begin_inset Tabular
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
pushbutton
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
pullup
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
A resistor connected (nominally) to Vdd
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
pulldown
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
A resistor connected (nominally) to Vss
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
usart
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
A serial interface with a GUI terminal window
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
pulsegen
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
I2C eeprom
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
switch
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Switch, which connects two nodes together
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
and2
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
2-input logical AND gate
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
or2
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
2-input logical OR gate
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
xor2
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
2-input logical XOR gate
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
not
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Inverter (logical NOT gate)
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
led_7segments
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
A 7-segment LED digit
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
led
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
TTL377
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
A 74HC377 style 8-bit tristate latch
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
Encoder
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
\end_layout
\end_inset
|
\end_inset
\end_layout
\begin_layout Subsection
USART
\begin_inset LatexCommand \index{USART module}
\end_inset
\end_layout
\begin_layout Standard
The USART module is a full duplex configurable USART.
In graphics mode, the USART will display its output in a console.
In addition, the console will accept keyboard input.
\end_layout
\begin_layout Subsubsection*
Attributes
\end_layout
\begin_layout Standard
.tx - The
\emph on
.tx
\emph default
attribute is the USART transmit register.
Data written to this attribute will initiate a transmission.
The USART does not support a transmit FIFO.
\end_layout
\begin_layout Standard
.rx - The
\emph on
.rx
\emph default
attribute is the USART receiver register.
Data received by the USART is available for querying through here.
\end_layout
\begin_layout Standard
.txbaud - The
\emph on
.txbaud
\emph default
attribute specifies the transmitter baud rate.
\end_layout
\begin_layout Standard
.rxbaud - The .rxbaud attribute specifies the receiver baud rate.
\end_layout
\begin_layout Standard
.console - When set to
\emph on
true
\emph default
, the console window will display received data and will accept keyboard
entries for the transmitter.
\end_layout
\begin_layout Standard
.crlf - When set to
\emph on
true
\emph default
, carraige returns and line feeds generate new lines in the console window.
\end_layout
\begin_layout Standard
.loop - When set to true, received characters are looped back to the transmitter.
\end_layout
\begin_layout Standard
.xpos - horizontal position in breadboard window.
\end_layout
\begin_layout Standard
.ypos - vertical position in breadboard window.
\end_layout
\begin_layout Subsubsection*
I/O Pins
\end_layout
\begin_layout Standard
.TXPIN - transmit pin
\end_layout
\begin_layout Standard
.RXPIN - receiver pin
\end_layout
\begin_layout Standard
.CTS - Clear to send pin.
This can be left unconnect
\end_layout
\begin_layout Standard
.RTS - Request to send pin.
\end_layout
\begin_layout Subsection
Logic
\begin_inset LatexCommand \index{Logic}
\end_inset
\end_layout
\begin_layout Standard
The only attributes supported be the logic devices are the standard
\emph on
.xpos
\emph default
and
\emph on
.ypos
\emph default
breadboard positions.
\begin_inset Note Greyedout
status collapsed
\begin_layout Standard
FIXME There should be attributes to specify the switching characteristics.
\end_layout
\end_inset
\end_layout
\begin_layout Subsection*
and2
\begin_inset LatexCommand \index{and2}
\end_inset
- Two input AND gate
\end_layout
\begin_layout Subsubsection*
I/O pins
\end_layout
\begin_layout Standard
.in0 - First input
\end_layout
\begin_layout Standard
.in1 - First input
\end_layout
\begin_layout Standard
.out - Output
\end_layout
\begin_layout Subsection*
or2
\begin_inset LatexCommand \index{or2}
\end_inset
- Two input OR gate
\end_layout
\begin_layout Standard
.in0 - First input
\end_layout
\begin_layout Standard
.in1 - First input
\end_layout
\begin_layout Standard
.out - Output
\end_layout
\begin_layout Subsection*
xor2
\begin_inset LatexCommand \index{xor2}
\end_inset
- Two input XOR gate
\end_layout
\begin_layout Standard
.in0 - First input
\end_layout
\begin_layout Standard
.in1 - First input
\end_layout
\begin_layout Standard
.out - Output
\end_layout
\begin_layout Subsection*
not
\begin_inset LatexCommand \index{not}
\end_inset
- Inverter
\end_layout
\begin_layout Standard
.in0 - Input
\end_layout
\begin_layout Standard
.out - Output
\end_layout
\begin_layout Subsection
I2C EEPROM
\begin_inset LatexCommand \index{I2C EEPROM}
\end_inset
\end_layout
\begin_layout Standard
There are currently three I2C EEPROMs supported: I2C-EEPROM2k, I2C-EEPROM16k,
and I2C-EEPROM256K.
\begin_inset Note Greyedout
status open
\begin_layout Standard
FIXME.
Probably should have attributes for configuring the prom size.
Also, there's currently no way to query or modify the prom contents.
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection*
I/O Pins
\end_layout
\begin_layout Standard
.A0 -
\end_layout
\begin_layout Standard
.A1 -
\end_layout
\begin_layout Standard
.SCL -
\end_layout
\begin_layout Standard
.SDA -
\end_layout
\begin_layout Standard
.WP
\end_layout
\begin_layout Subsection
\begin_inset LatexCommand \label{sub:Switches-&-Resistors}
\end_inset
Switches
\begin_inset LatexCommand \index{Switches}
\end_inset
& Resistors
\begin_inset LatexCommand \index{Resistors}
\end_inset
\end_layout
\begin_layout Standard
The
\emph on
switch
\emph default
module is a model of a simple two terminal switch.
It may be controlled either from the command line or the breadboard gui.
The
\emph on
switch
\emph default
module's open and closed resistance are controlled by attributes.
Thus a two terminal resistor can be modeled as a switch that is always
closed (or open).
\end_layout
\begin_layout Subsubsection*
Attributes
\end_layout
\begin_layout Standard
.Ropen - Switch resistance in ohms when the switch is opened.
\end_layout
\begin_layout Standard
.Rclosed - Switch resistance in ohms when the switch is closed.
\end_layout
\begin_layout Standard
.state - Switch state.
When
\emph on
false
\emph default
the switch is open.
The
\emph on
.state
\emph default
attribute is writable.
\end_layout
\begin_layout Subsubsection*
I/O Pins
\end_layout
\begin_layout Standard
.A - One side
\end_layout
\begin_layout Standard
.B - The other side
\end_layout
\begin_layout Subsection
Voltage Sources
\begin_inset LatexCommand \index{Voltage Sources}
\end_inset
, Resistors
\begin_inset LatexCommand \index{Resistors}
\end_inset
, and Capacitors
\begin_inset LatexCommand \index{Capacitors}
\end_inset
\end_layout
\begin_layout Standard
The
\emph on
pullup
\emph default
and
\emph on
pulldown
\emph default
modules are two terminal devices with one terminal tied to a voltage source.
Their voltage, resistance, and pin capacitance are controllable via attributes.
\end_layout
\begin_layout Subsubsection*
Attributes
\end_layout
\begin_layout Standard
.voltage - DC voltage
\end_layout
\begin_layout Standard
.resistance - resistance in ohms between the I/O pin and the voltage source.
\end_layout
\begin_layout Standard
.capacitance - capacitance in farads between the I/O pin and ground.
\end_layout
\begin_layout Subsubsection*
I/O Pins
\end_layout
\begin_layout Standard
.pin - the only pin exposed.
\end_layout
\begin_layout Section
Third Party Modules
\end_layout
\begin_layout Standard
In addition to the standard modules, third are separately distribute gpsim
modules.
\end_layout
\begin_layout Subsection
Character LCD - HD44780
\begin_inset LatexCommand \index{HD44780}
\end_inset
\end_layout
\begin_layout Standard
This module emulates the ubiquitous HD44780 character LCDs.
\end_layout
\begin_layout Subsection
Graphic LCD - SED1530
\begin_inset LatexCommand \index{SED1530}
\end_inset
\end_layout
\begin_layout Standard
This module emulates a 100X32 pixel graphics LCD based on dual SED1350 controlle
rs.
\end_layout
\begin_layout Section
Writing new modules
\end_layout
\begin_layout Standard
A module is a library of code.
On Windows the library is a .DLL and on Unix a shared library.
There are a few details that a module must adhere to, but in general the
module has full access to gpsim's API.
\end_layout
\begin_layout Standard
The easiest way to write a new module is to start from the source code from
one of the existing modules.
For example, suppose your project produces a serial bit-stream in PPM coding
and you want to display the output during the simulation.
The external module you need is similar to the usart module but not the
same, so start by making a copy of the usart module and then modify it
to work how you need.
\end_layout
\begin_layout Standard
To be able to load your module into gpsim it needs to be in a library.
Usually you will be creating a new library just for one device, but sometimes
you'll have a few devices.
Either way, the library must declare to gpsim what devices it contains.
This is achieved with an array of Module_Types class instances, returned
to gpsim by a function named
\begin_inset Quotes eld
\end_inset
get_mod_list
\begin_inset Quotes erd
\end_inset
.
All gpsim module libraries must declare this function.
You can copy the required template from the gpsim source -- probably one
of the
\begin_inset Quotes eld
\end_inset
extras
\begin_inset Quotes erd
\end_inset
modules is slightly cleaner than the main library.
For our PPM decoder example, we might have a module_manager.cc containing
the following code:
\end_layout
\begin_layout LyX-Code
/* IN_MODULE should be defined for modules */
\end_layout
\begin_layout LyX-Code
#define IN_MODULE
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
#include
\end_layout
\begin_layout LyX-Code
#include
\end_layout
\begin_layout LyX-Code
#include "ppm.h"
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
Module_Types available_modules[] =
\end_layout
\begin_layout LyX-Code
{
\end_layout
\begin_layout LyX-Code
{ "ppm_display", "ppm_rx_iface", PpmDisplay::construct},
\end_layout
\begin_layout LyX-Code
// No more modules
\end_layout
\begin_layout LyX-Code
{ NULL,NULL,NULL}
\end_layout
\begin_layout LyX-Code
};
\end_layout
\begin_layout LyX-Code
#ifdef __cplusplus
\end_layout
\begin_layout LyX-Code
extern "C" {
\end_layout
\begin_layout LyX-Code
#endif /* __cplusplus */
\end_layout
\begin_layout LyX-Code
/*****************************************************************
\end_layout
\begin_layout LyX-Code
* get_mod_list - Report all of the modules in this library.
\end_layout
\begin_layout LyX-Code
*
\end_layout
\begin_layout LyX-Code
* This is a required function for gpsim compliant libraries.
\end_layout
\begin_layout LyX-Code
*/
\end_layout
\begin_layout LyX-Code
Module_Types * get_mod_list(void)
\end_layout
\begin_layout LyX-Code
{
\end_layout
\begin_layout LyX-Code
return available_modules;
\end_layout
\begin_layout LyX-Code
}
\end_layout
\begin_layout LyX-Code
#ifdef __cplusplus
\end_layout
\begin_layout LyX-Code
}
\end_layout
\begin_layout LyX-Code
#endif /* __cplusplus */
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Standard
This declares that this library provides one module, called ppm_display,
implemented by the C++ class PpmDisplay.
The class which implements the module must provide a static method
\begin_inset Quotes eld
\end_inset
construct
\begin_inset Quotes erd
\end_inset
to create a new instance of the class.
For example:
\end_layout
\begin_layout LyX-Code
Module * PpmDisplay::construct(const char *_new_name=0)
\end_layout
\begin_layout LyX-Code
{
\end_layout
\begin_layout LyX-Code
PpmDisplay *ppmd = new PpmDisplay(_new_name);
\end_layout
\begin_layout LyX-Code
ppmd->create_iopin_map();
\end_layout
\begin_layout LyX-Code
ppmd->create_window(_new_name);
\end_layout
\begin_layout LyX-Code
return ppmd;
\end_layout
\begin_layout LyX-Code
}
\end_layout
\begin_layout Standard
Your module will need to include stimuli for its I/O connections.
You can use the standard gpsim stimulus classes: IOPIN, io_bidirectional,
io_bidirectional_pu, io_open_collector.
In many cases, however, you will want to derive your own class from one
of them.
This will allow you to customise the actions when the node state changes.
For example:
\end_layout
\begin_layout LyX-Code
class DecoderPin : public IOPIN
\end_layout
\begin_layout LyX-Code
{
\end_layout
\begin_layout LyX-Code
private:
\end_layout
\begin_layout LyX-Code
PpmDisplay * Parent;
\end_layout
\begin_layout LyX-Code
public:
\end_layout
\begin_layout LyX-Code
DecoderPin ( PpmDisplay * parent, unsigned int b, const char * name=0
);
\end_layout
\begin_layout LyX-Code
virtual void setDrivenState(bool new_state);
\end_layout
\begin_layout LyX-Code
};
\end_layout
\begin_layout Standard
The only methods we provide here are the constructor and an overridden
\begin_inset Quotes eld
\end_inset
setDrivenState
\begin_inset Quotes erd
\end_inset
.
This is because our PPM decoder needs to be told when the input pin changes
state.
\end_layout
\begin_layout Chapter
Symbolic Debugging
\end_layout
\begin_layout Standard
gpsim maintains a symbol table.
\end_layout
\begin_layout Standard
\end_layout
\begin_layout Chapter
Macros
\end_layout
\begin_layout Standard
\end_layout
\begin_layout Standard
\end_layout
\begin_layout Chapter
Hex Files
\end_layout
\begin_layout Standard
The target code simulated by gpsim can be supplied by a hex file, or more
specifically an Intel Hex file.
gpsim accepts the format of hex provided by gpasm and mpasm.
The hex file does not provide any symbolic information.
It's recommended that hex files only be used if 1) you suspect there's
a problem with the way .cod files are generated by your assembler or compiler
OR 2) your assembler or compiler doesn't generate .cod files.
Also, you must supply a processor when loading hex files.
See the load command.
\end_layout
\begin_layout Chapter
The ICD- Not Supported in versions 0.21.0 and later
\end_layout
\begin_layout Standard
gpsim supports (partly) the first version of the ICD (as opposed to ICD2
(the round hockey-puck shaped one)).
\end_layout
\begin_layout Subsection*
Special configuration of the code
\end_layout
\begin_layout Standard
Read the MPLAB ICD USER's GUIDE.
\end_layout
\begin_layout Standard
Here's the short version:
\end_layout
\begin_layout Itemize
disable at least: brown out detection, low voltage programming and all code
protection.
It is probably good to turn of the watchdog too.
see the MPLAB ICD USER's GUIDE for more information.
\end_layout
\begin_layout Itemize
have a NOP as the first instruction.
\end_layout
\begin_layout Itemize
Don't touch RB6 or RB7.
\end_layout
\begin_layout Itemize
Don't use the last stack level.
\end_layout
\begin_layout Itemize
Don't use these registers and program words:
\newline
\begin_inset Tabular
|
\begin_inset Text
\begin_layout Standard
Processor
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Register
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
Program
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
-870/1/2
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
0x70, 0xBB-0xBF
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
0x6E0-0x7FF
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
-873/4
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
0x6D, 0x1fD, 0xEB-0xF0, 0x1Eb-0x1F0
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
0xEE0-0xFFF
\end_layout
\end_inset
|
|
\begin_inset Text
\begin_layout Standard
-876/7
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
0x70, 0x1Eb-0x1Ef
\end_layout
\end_inset
|
\begin_inset Text
\begin_layout Standard
0x1F00-0x1FFF
\end_layout
\end_inset
|
\end_inset
\end_layout
\begin_layout Subsection*
icdprog
\end_layout
\begin_layout Standard
Download and install icdprog.
\end_layout
\begin_layout Standard
Use icdprog to program the target with the hex file (
\emph on
icdprog mycode.hex
\emph default
).
\end_layout
\begin_layout Subsection*
ICD usage
\end_layout
\begin_layout Standard
Start gpsim like this:
\end_layout
\begin_layout Standard
\emph on
gpsim -d /dev/ttyS0 -s mycode.cod
\end_layout
\begin_layout Standard
, assuming the ICD is connected to the first serial port.
\end_layout
\begin_layout Standard
Now you can type 'icd' to see some information:
\end_layout
\begin_layout Standard
\emph on
**gpsim> icd
\newline
ICD version "2.31.00" was found.
\newline
Target controller is 16F877 rev 13.
\newline
Vdd: 5.2 Vpp: 13.3
\newline
Debug module is present
\end_layout
\begin_layout Standard
2.31 is the firmware version.
I have only tried this particular version...
\end_layout
\begin_layout Standard
You can step, reset, run, halt, set the breakpoint and read file registers.
It works both from the gui and the cli.
\end_layout
\begin_layout Subsection*
ICD TODO
\end_layout
\begin_layout Itemize
MPLAB has a setting for target cpu frequency, I have only tried with a 20MHz
crystal, so there may be adjustments to be made to the serial port timeout
settings in gpsim.
\end_layout
\begin_layout Itemize
The source, disassembly, watch, symbol and RAM windows works.
And the rest doesn't.
I guess the breadboard should be able to work at least for the pic, but
it doesn't.
\end_layout
\begin_layout Itemize
eeprom support
\end_layout
\begin_layout Itemize
modifying data
\end_layout
\begin_layout Itemize
Fix the UI to give more feedback about what's happening during long delays.
\end_layout
\begin_layout Itemize
Better error detection.
gpsim doesn't always see that the target is not functional.
\end_layout
\begin_layout Chapter
Examples
\end_layout
\begin_layout Standard
The
\emph on
examples/
\emph default
subdirectory contains several examples.
The
\emph on
examples/projects/
\emph default
subdirectory demonstrate sample projects that can serve as templates for
new projects.
In addition, the
\emph on
examples/modules
\emph default
subdirectory contains several examples illustrating how to use gpsim's
various modules.
Finally, as described in chapter
\begin_inset LatexCommand \ref{cha:Regression-Tests}
\end_inset
, gpsim's regression tests illustrate many powerful debugging techniques
that have not been fully documented.
\end_layout
\begin_layout Subsubsection*
usart_gui example
\end_layout
\begin_layout Standard
Each example contains a brief
\emph on
README
\emph default
explaning its purpose.
For example, the
\emph on
README
\emph default
for the
\emph on
usart_gui
\emph default
example in the
\emph on
examples/modules
\emph default
directory contains
\end_layout
\begin_layout LyX-Code
The tests the USART module with the GUI fix.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
The code for a 16f628 PIC is used.
The code first transmits a string of
\end_layout
\begin_layout LyX-Code
characters, which are instructions to the user, to the USART module which
\end_layout
\begin_layout LyX-Code
will then be displayed on its GUI.
This verifies that the USART can receive
\end_layout
\begin_layout LyX-Code
serial data.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
When the focus is on the USART GUI window, characters typed on the keyboard
\end_layout
\begin_layout LyX-Code
are sent from the USART to the PIC and then retransmitted from the PIC back
\end_layout
\begin_layout LyX-Code
to the USART.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
If all works, the typed characters will be displayed in the GUI text window
\end_layout
\begin_layout LyX-Code
of the USART.
Both transmit and receive must be functioning for this to
\end_layout
\begin_layout LyX-Code
happen.
\end_layout
\begin_layout Standard
\emph on
Fixme
\emph default
- we really need to document all of the examples!
\end_layout
\begin_layout Chapter
Regression Tests
\begin_inset LatexCommand \label{cha:Regression-Tests}
\end_inset
\end_layout
\begin_layout Standard
Starting with version 0.22.0, gpsim distributes regression tests.
The purpose of a regression test is to validate correctness.
The tests are designed to exercise many of the aspects of gpsim and gpsim's
modules.
While designed primarily for developers though, the regression tests also
serve as a rich source of examples.
There are many features gpsim's developers will tuck away into a regression
test and fail to document!
\end_layout
\begin_layout Chapter
Theory of Operation
\end_layout
\begin_layout Standard
This section is only provided for those who may be interested in how gpsim
operates.
The information in here is 'mostly' accurate.
However, as gpsim evolves so do the details of the theory of operation.
Use the information provided here as a high level introduction and use
the (well commented :]) source to learn the details.
\end_layout
\begin_layout Section
Background
\end_layout
\begin_layout Standard
gpsim is written mostly in C++.
Why? Well the main reason is to easily implement a hierarchical model of
a pic.
If you think about a microcontroller, it's really easy to modularize the
various components.
C++ lends itself well to this conceptualization.
Furthermore Microchip, like other microcontroller manufacturers, has created
families of devices that are quite similar to one another.
Again, the C++ provides 'inheritance' that allows the relationships to
be shared among the various models of pics.
\end_layout
\begin_layout Section
Instructions
\begin_inset LatexCommand \index{instructions}
\end_inset
\end_layout
\begin_layout Standard
There's a base class for the 14-bit instructions (I plan to go one step
further and create a base class from which all pic instructions can be
derived).
It primarily serves two purposes: storage that is common for each instruction
and a means for generically accessing virtual functions.
The common information consists of a name - or more specifically the instructio
n mnemonic, the opcode, and a pointer to the processor owning the instruction.
Some of the virtual functions are 'execute' and 'name'.
As the hex file is decoded, instances of the instructions are created and
stored in an array called program_memory.
The index into this array is the address at which the instruction resides.
To execute an instruction the following code sequence is invoked:
\end_layout
\begin_layout Quotation
program_memory[pc.value]->execute();
\end_layout
\begin_layout Standard
which says, get the instruction at the current program counter (pc.value)
and invoke via the virtual function execute().
This approach allows execution break points to be easily set.
A special break point instruction can replace the one residing in the program
memory array.
When 'execute' is called the break point can be invoked.
\end_layout
\begin_layout Section
General File Registers
\begin_inset LatexCommand \index{registers}
\end_inset
\end_layout
\begin_layout Standard
A file register is simulated by the 'file_register' class.
There is one instance of a 'file_register' object for each file register
in the PIC.
All of the registers are collected together into an array called 'registers'
which is indexed by the registers' corresponding PIC addresses.
The array is linear and not banked like it is in the PIC.
(Banking is handled during the simulation.)
\end_layout
\begin_layout Section
Special File Registers
\end_layout
\begin_layout Standard
Special file registers are all of the other registers that are not general
file registers.
This includes the core registers like status and option and also the peripheral
registers like eeadr for the eeprom.
The special file registers are derived from the general file registers
and are also stored in the 'registers' array.
There is one instance for each register - even if the register is accessible
in more than one bank.
So for example, there's only one instance for the 'status' register, however
it may be accessed through the 'registers' array in more than one place.
\end_layout
\begin_layout Standard
All file registers are accessed by the virtual functions 'put' and 'get'.
This is done for two main reasons.
First, it conveniently encapsulates the breakpoint overhead (for register
breakpoints) in the file register and not in the instruction.
Second, and more important, it allows derived classes to implement the
put and get more specifically.
For example, a 'put' to the indf register is a whole lot different than
a put to the intcon register.
In each case, the 'put' initiates an action beyond simply storing a byte
of data in an array.
It also allows the following code sequence to be easily implemented:
\end_layout
\begin_layout LyX-Code
movlw trisa ;Get the address of tris
\end_layout
\begin_layout LyX-Code
movwf fsr
\end_layout
\begin_layout LyX-Code
movf indf,w ;Read trisa indirectly
\end_layout
\begin_layout Section
Example of an instruction
\end_layout
\begin_layout Standard
Here's an example of the code for the movf instruction that illustrates
what has been discussed above.
Somewhere in gpsim the code sequence:
\end_layout
\begin_layout LyX-Code
program_memory[pc.value]->execute();
\end_layout
\begin_layout Standard
is executed.
Let's say that the pc is pointing to a movf instruction.
The ->execute() virtual function will invoke MOVF::execute.
I've added extra comments (that aren't in the main code) to illustrate
in detail what's happening.
\end_layout
\begin_layout LyX-Code
void MOVF::execute(void)
\end_layout
\begin_layout LyX-Code
{
\end_layout
\begin_layout LyX-Code
unsigned int source_value;
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
// All instructions are 'traced' (discussed below).
It's sufficient
\end_layout
\begin_layout LyX-Code
//to only store the opcode.
However, even this may be unnecessary since
\end_layout
\begin_layout LyX-Code
//the progam counter is also traced.
Expect this to disappear in the
\end_layout
\begin_layout LyX-Code
//future...
\end_layout
\begin_layout LyX-Code
trace.instruction(opcode);
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
// 'source' is a pointer to a 'file_register' object.
It is initialized
\end_layout
\begin_layout LyX-Code
//by reading the 'registers' array.
Note that the index depends on the
\end_layout
\begin_layout LyX-Code
//'rp' bits (actually just one bit) in the status register.
Time is
\end_layout
\begin_layout LyX-Code
// saved by caching rp as opposed to decoding the status register.
\end_layout
\begin_layout LyX-Code
source = cpu->registers[cpu->rp | opcode®_IN_INSTRUCTION_MASK];
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
// We have no idea which register we are trying to access and how it
\end_layout
\begin_layout LyX-Code
//should be accessed or if there's a breakpoint set on it.
No problem,
\end_layout
\begin_layout LyX-Code
//the virtual function 'get' will resolve all of those details
\end_layout
\begin_layout LyX-Code
// and 'do the right thing'.
\end_layout
\begin_layout LyX-Code
source_value = source->get();
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
// If the destination is W, then the constructor has already initialized
\end_layout
\begin_layout LyX-Code
//'destination'.
Otherwise the destination and source are the same.
\end_layout
\begin_layout LyX-Code
if(opcode&DESTINATION_MASK)
\end_layout
\begin_layout LyX-Code
destination = source; // Result goes to source
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
// Write the source value to the destination.
Again, we have no idea
\end_layout
\begin_layout LyX-Code
// where the destination may be or
\end_layout
\begin_layout LyX-Code
// or how the data should be written there.
\end_layout
\begin_layout LyX-Code
destination->put(source_value);
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
// The movf instruction will set Z (zero) bit in the status register
\end_layout
\begin_layout LyX-Code
//if the source value was zero.
\end_layout
\begin_layout LyX-Code
cpu->status.put_Z(0==source_value);
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
// Finally, advance the pc by one.
\end_layout
\begin_layout LyX-Code
cpu->pc.increment();
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
}
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Section
Trace
\end_layout
\begin_layout Standard
Everything that is simulated is traced -
\emph on
all
\emph toggle
of the time.
The trace buffer is one huge circular buffer of integers.
Information is or'ed with a trace token and then is stored in the trace
buffer.
No attempt is made to associate the items in the trace buffer while the
simulator is simulating a PIC.
Thus, if you look at the raw buffer you'll see stuff like: cycle counter
= ..., opcode fetch = ..., register read = ..., register write = ..., etc.
However, this information is post processed to ascertain what happened
and when it happened.
It's also possible to use this information to undo the simulation, or in
other words you can step backwards.
I don't have this implemented yet though.
\end_layout
\begin_layout Section
Breakpoints
\end_layout
\begin_layout Standard
Breakpoints fall into three categories: execution, register, and cycle.
\end_layout
\begin_layout Subsubsection
Execution:
\end_layout
\begin_layout Standard
For execution breakpoints a special instruction appropriately called 'Breakpoint
_Instruction' is created and placed into the program memory array at the
location the break point is desired.
The original instruction is saved in the newly created breapoint instruction.
When the break point is cleared, the original instruction is fetched from
the break point instruction and placed back into the program memory array.
\end_layout
\begin_layout Standard
Note that this scheme has zero overhead.
The simulation is only affected when the breakpoint is encountered.
\end_layout
\begin_layout Subsubsection
Register:
\end_layout
\begin_layout Standard
There are at least four different breakpoint types that can be set on a
register: read any value, write any value, read a specific value, or write
a specific value.
Like the execution breakpoints, there are special breakpoint registers
that replace a register object.
So when the user sets a write breakpoint at register 0x20 for example,
a new breakpoint object is created and insert into the file register array
at location 0x20.
When the simulator attempts to access register location 0x20, the breakpoint
object will be accessed instead.
\end_layout
\begin_layout Standard
Note that this scheme too has zero overhead, accept when a breakpoint is
encountered.
\end_layout
\begin_layout Subsubsection
Cycle:
\end_layout
\begin_layout Standard
Cycle breakpoints allow gpsim to alter execution at a specific instruction
cycle.
This is useful for running your simulation for a very specific amount of
time.
Internally, gpsim makes extensive use of the cycle breakpoints.
For example, the TMR0 object can be programmed to generate a periodic cycle
break point.
\end_layout
\begin_layout Standard
Cycle break points are implemented with a sorted doubly-linked list.
The linked list contains two pieces of information (besides the links):
the cycle at which the break is to occur and the call back function
\begin_inset Foot
status collapsed
\begin_layout Standard
A call back function is a pointer to a function.
In this context, gpsim is given a pointer to the function that's to be
invoked (called) whenever a cycle break occurs.
\end_layout
\end_inset
that's to be invoked when the cycle does occur.
The break logic is extremely simple.
Whenever the cycle counter is advanced (that is, incremented), it's compared
to the next desired cycle break point.
If there's NO match, then we're done.
So the overhead for cycle breaks is the time required to implement a comparison.
If there IS a match, then the call back function associated with this break
point is invoked and the next break point in the doubly-linked list serves
as the reference for the next cycle break.
\end_layout
\begin_layout Chapter*
COPYING
\end_layout
\begin_layout Standard
The document is part of gpsim.
\end_layout
\begin_layout Standard
gpsim is free software; you can redistribute it and/or modify it under the
terms of the
\begin_inset LatexCommand \index{GNU}
\end_inset
GNU General Public
\begin_inset LatexCommand \index{License}
\end_inset
License as published by the Free Software Foundation; either version 2,
or (at your option) any later version.
\end_layout
\begin_layout Standard
gpsim is distributed in the hope that it will be useful, but WITHOUT ANY
\begin_inset LatexCommand \index{NO WARRANTY}
\end_inset
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
\end_layout
\begin_layout Standard
You should have received a copy of the GNU General Public License along
with gpsim; see the file COPYING.
If not, write to the Free Software Foundation, 59 Temple Place - Suite
330, Boston, MA 02111-1307, USA.
\end_layout
\begin_layout Standard
\start_of_appendix
\begin_inset LatexCommand \printindex{}
\end_inset
\end_layout
\end_body
\end_document