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


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

Assembler View


pp-man.png

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:

address 496. Display is updated every 100,000 cycles (approx).
It does not erase 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).

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:

of this address is equals to the supplied value.
of this address is not equal to the supplied value.

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.

pp-editor.png

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.

destination was found
(garbage), was found at the end of a line.

Syntax


Normal Propeller Tool syntax is supported with some caveats:


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.

pp-hmd.png

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:

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




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.