pPropellerSim
Title: | pPropellerSim |
Author: | 67.11.90.193 |
Published: | Mon, 25 May 2009 02:19:42 GMT |
pPropellerSim
It is a Parallax Propeller Simulator with a twist it allows you to edit, compile and debug your assembler code. In that sense it is not a complete simulator, but has enough to let you program comfortably.
Note: This program requires java v1.5 or better to run. If you want to make it run
under java 1.4, just remove the generics used in FormCloseEvent class, java.util.Vector
refs and related. That was added to avoid the v1.5 compiler's complaints.
It is assumed through this manual that the reader is familiar with the Propeller
terminology. If this is not the case, please read the Propeller Manual first.
Features
- Display a disassembled view of COG instructions
- Single-step, etc debugging capabilities
- Load .binary files (Spin instructions are discarded) directly to the first cog's memory
- Compiler / Editor
Parallax syntax (what else)
_ as number separator
equates/defines/=
Built-in editor, assembler source files can be loaded, saved, compiled and debugged.
.binary files can be edited (copy source). Symbols are shown in assembler view, but not labels
- Memory dump uses symbols and highlight recently modified long (when in screen), no undo/redo
- Binary files, plain binary without headers, can be loaded and saved (always saves 496 longs)
- Breakpoints on Read/write or execute, accessible through a pop up menu in the Memory Dump
Assembler View

This panel shows the contents of COG 0's memory as disassembled instructions.
Labels and symbols are used for every memory (in COG's address space) accessing instruction.
This symbols are either generated when a binary file is loaded or taken from the recently
compiled source file (in editor).
The buttons in the Toolbar (run, stop, step-over, step-into, run-to-cursor and compile), and the commands
with the same names on the Run menu have the same actions:
- Run : Starts the cog at the current PC till a breakpoint is reached or the program reaches
address 496. Display is updated every 100,000 cycles (approx).
- Stop : Stops the current running program if any (at 100,000 cycles boundaries).
- Step-over : Runs till next instruction is reached, useful for subroutines (call instructions).
- Step-into : Runs just one instruction
- Run-to-cursor : Runs till the PC reaches the position of the cursor
- Warm reset : Resets the cog. PC and C and Z flags are reset (0, cleared and cleared, respectively).
It does not erase memory.
- Cold reset : reset the Hub, and COG(s). Erases all memory and PC and C and Z flags
- Compile : Compiles the current editor file to COG's memory
Simulator
The included simulator tries to simulate cycle-exact operation (if that it is possible). So what
you would expect in a real propeller (between the limitations described) should be reproduced
here. Self-modifying code has the same caveats as a real Propeller does.
The Propeller works with a sort of 4 stage machine. (As described by Paul Baker).
- Source fetch
- Destination Fetch
- Execution
- Write-back
Instructions that need more than 4 cycles are delayed at the execution stage, well is what I believe,
and what I implemented. Next instruction fetch occurs at the execution stage. So Self-modifying code,
can not successfully modify the next instruction and execute the new modified instruction if there is
no other instruction in-between because the old instruction was already fetched. Jump instructions some-how
avoid a "delay-slot", fetching the destination during source fetch, I did it also in the execution stage.
The Hub synchronization scheme is also implemented, so synchronization is needed to complete HUB
instructions. Enough wait states are used till the Hub is synced to the Execution stage (where
I believe the sync occurs).
Several threads at Parallax Forums describe part of the behavior implemented here, the rest, was
gess-work. I did not peek at GEAR so I do not know how it was implemented there.
Any new info is of course welcome.
Breakpoints
A breakpoint can be set/reset at he current SELECTED row by tapping with the right mouse button
(CTRL-tap in one button mice) to pop-up the Breakpoint's menu, in the assembler view pane.
The options are:
- Set breakpoint : Sets an execution breakpoint.
- Set read breakpoint : Sets a breakpoint for a read instruction on this address
- Set write breakpoint : Sets a breakpoint for a write instruction on this address
- Set breakpoint (eq) : Sets a breakpoint that is going to be triggered when the contents
of this address is equals to the supplied value.
- Set breakpoint (ne) : Sets a breakpoint that is going to be triggered when the contents
of this address is not equal to the supplied value.
- Clear breakpoint : Clears all breakpoints for this address.
- Clear all breakpoints : Clears all breakpoints for all addresses
Some breakpoints are exclusive, that means they cannot be set at the same address: eq and ne.
Registers View
This panel shows the current state of hardware registers, CNT, PC and flags. Newly modified
registers are red marked. To change the status flag you can simply tap with the mouse button over it.
The PC can be modified with the provided field, with immediate fetch of new instruction.
COG Memory Dump
This panel allows to view the current cog's memory contents and to modify them.
Value Modification
To modify the contents of a long, just tap over its value, and an editing field will be shown
with the current value. An HEXADECIMAL value between 0 and ffffffff is expected. No '$' symbol
is needed. Optionally an assembler instruction can be entered, in the same form as in the editor.
Current symbols can be used for source/destination fields, but not symbols will be created
during the compilation phase. An input will be accepted only when its contents are valid.
The trace column shown how many times a instruction was fetched, as a sort of profiling hint.
Hardware
Editor
The editor is a simple text editor, used to edit source code (assembler) prior to be compiled.
The Compile button is used to compile this source and to load the compiled version directly
into the cog's memory (starting always at address 0).
The cursor position is shown at the lower left position, starting at 1, 1.

Syntax highlight
The editor supports syntax highlight, so instructions, conditions, numbers, symbols and comments
are displayed with unique colors for easy identification.
Compiler
The compiler is a simple-yet-straightforward two-pass assembler. Symbol creating as well as sizing
take place on the first pass, while code is generated in the second pass. A listing file is created
every time a compile is done. its name is the assembler file's name plus ".lst".
Errors
Detected errors are going to be displayed in the status bar (lower left panel). Several errors
can be detected, the culprit is normally shown between parentheses, with the line number:
Compilation successful : No errors detected.
- Duplicated symbol : the symbol was defined more than once.
- Condition unknown : the condition was not recognized, probably was misspelled.
- Instruction unknown : the instruction was not recognized, probably was misspelled.
- Symbol not found : A symbol was used, without being defined.
- Duplicated wz or wc field : The modifier (effect) was present more than once.
- Argument(s) missing : An instruction requiring one or two arguments are missing one or both.
- Destination read-only : An attempt to use a read-only register (between 0x1f0 and 0x1f3) as
destination was found
- Garbage at end of line : Extra not needed arguments, not properly quoted comments, etc
(garbage), was found at the end of a line.
Syntax
Normal Propeller Tool syntax is supported with some caveats:
- No ORG directive is supported, not needed, code always starts at 0.
- No RES meta command is supported, nor it has any use at this point, use long 0 instead.
- No multi-line-comments are supported, just single lines with '
The rest should work without problems.
Note: A call missing the corresponding 'xx_ret' symbol is going to give a "Symbol not found error".
Load/Save
Programs (in text form, i.e. not compiled) can be loaded/saved with ctrl-o/ctrl-s or from the
File menu with ease. The default (fixed) invented extension is '.pasm'.
Hub Memory Dump
This frame provides a rapid way of peeking at the contents of the Hub memory.
Included functions are load/save the contents to a binary file ('.bin'), search and fill.

Search
The search button allows to search for the text/pattern in the search field.
An ASCII text can be entered directly, up to 24 characters are going to be used.
A HEX pattern can be entered when it begins with a '$' sign. Just one '$' is needed.
Hexa characters are composed of one or two Hex digits, separated by spaces, or in the case
of only two-digit hex values, no spaces:
$12 34 56 is the same as $123456, usw.
Fill
This function allows to fill the (writable) area of the hub's memory with a defined pattern.
Options are:
- Random values: pseudo random values are used
- Incremental value : a counter from 0 to 255 is used
- Pattern : with the same value
- Clear all memory : It clears (writes with zero) the hub's memory
- Apply : applies the operations
- Cancel : dismisses the dialog
Keys, Commands and menus
File Menu
CTRL-N New : Cold resets the Propeller (does not clear the editor)
Open Propeller tool binary : Opens a .binary file in the assembler view, ram of cog 0
(compiled with Propeller Tool)
Open binary : Opens a file as binary in the assembler view, ram of cog 0
(compiled with this pPorpellerSim).
Save binary : Saves the contents of the cog 0 ram as binary
CTRL-O Open assembler : Opens a text file (.pasm extension) in the editor,
previous content is lost without warning, cog 0 memory
is unaltered
CTRL-S Save assembly : Saves the contents of the editor as a text file (.pasm
etension)
CTRL-Q Exits the pPropellerTool
Recently opened files are added to the Recent open files menu
Edit Menu
Normal Undo, Copy, Paste stuff.
Copy to Editor : Disassembles the contents of the cog 0 memory (show in
assembler view and memory dump) and transfers it to the
editor. Previous contents of the editor are lost without
warning.
CTRL-UP Cursor Up Assembler view cursor movement, one row up
CTRL-DOWN Cursor down Assembler view cursor movement, one row down
Configuration Opens config Panel, usual color stuff and
the switch to turn on/off autosave of source file
before compilation
Run Menu
F10 Compile : Compiles the contents of the editor and transfers them
to the cog 0 ram. Previous contents of the cog 0 ram are
lost without warning. Symbols are preserved and used in
the assembler view.
F5 Run : Runs the contents of cog 0 ram starting at the current PC
if Address 496 (PAR) is reached, execution stops
F4 Run to cursor Runs the contents of cog 0 ram starting at the current PC
till the position of the current cursor
F8 Step over Runs till next instruction is reached starting at the
current PC
F7 Step into Runs current instruction, goes into CALLs
Data Menu
Hub Memory Dump Displays the Hub memory dump frame
Program Device Placeholder for when the programming of
propellers works
Copy HUB RAM to COG RAM allows to copy up to 496 longs from HUB RAM
back to COG RAM.
Known bugs
- HUB instructions, besides read and write the rest are not (yet) implemented
Propeller programming
NOTE: this was removed because... it does not work :-(
In order for pPropellerSim to be able to program Propeller chips, some libraries and
java extensions should be installed in your computer, i.e. RXTX and Sun Java Comm extension.
http://java.sun.com/products/javacomm
For GNU/Linux, I'd suggest you visit:
www.rxtx.org
For MacOS X, A good source of files and information is available at:
http://www.uow.edu.au/~phillip/MacInOut/serial.html
Note: is important that the directory /var/lock can be written by the members of
the group uucp, change permissions and ownership to reflect that!
For Winblows users, there is some info at www.rxtx.org, but I did not test it.
In the Programming Device Frame, (Data menu -> Program device), select the port
where the programming dongle resides. (Under linux choose something like /dev/ttyUSB0)
and for MacOS X choose /dev/tty.usbserialxxxxx.
Verify that a Propeller can be found on that port pressing the button "Discover".
Now that the propeller was found, you can program it (you can avoid the discover step
if you know for sure that a Propeller dongle/Propeller chip is connected and they work).
From the panel on the left choose the source, a PropellerTool compiled .binary file or
the current contents of the HUB memory. Press the button "Program" and if everything
goes without problems, your device should be programmed in few seconds. Any errors
found will be promptly reported.
Assembler compiler
The compiler has been rewritten from previous version (starting at 0.7.x) to match the features of the
pLMMAss (pacito LMM Assembler).
Sections (.section <type> <name>)
Sections separate symbol creation into different groups
HUB : flat address space, addresses have a byte granularity
COG : flat, used for code that will be loaded in to a cog's memory,
addresses have a long granularity (and symbols will start at
adress 0 after the section .directive)
LMM : addresses have a long granularity
Alignment (.align <power-of-two)
Alignmentis used to align portions of data/code to specific boundaries
Globals (.global <symbol_name>)
Globals are all symbols declared with this directive, that will create a byte
aligned symbol useful to get the absolute address of a long aligned variable.
Example
Example Program skeleton to be used when compilation to COG RAM is used
' starts here
.section COG cog0
start mov x,PAR
<...>
x long 0
'ends here
In the case where compilation to HUB memory is desired (not implemented) other
sections and globals can be used.
Arithmetic expressions
Arithmetic expressions need to be written _without spaces_. That will be fixed sort of soon :-)
The expression 0-0 as destination (zero minus zero) gets interpreted as a symbol, needs fixing.