pPropellerSim - rosco-pc/propeller-wiki GitHub Wiki

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.

• 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

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

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.

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.

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.

This panel allows to view the current cog's memory contents and to modify them.

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.

*** Not yet implemented

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.

The editor supports syntax highlight, so instructions, conditions, numbers, symbols and comments are displayed with unique colors for easy identification.

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

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.

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

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

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.

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.

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

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.

• HUB instructions, besides read and write the rest are not (yet) implemented

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.

The compiler has been rewritten from previous version (starting at 0.7.x) to match the features of the pLMMAss (pacito LMM Assembler).

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

Alignmentis used to align portions of data/code to specific boundaries

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