Propeller 2 Assembly Language beginner guide v0.1

proppy · 2026-02-24 14:03

Hello!

I’ve been working on a practical Propeller 2 assembly language manual that walks through real-world examples using smartpins, UART, line editing/input parsing, and SPI flash access. It’s written in P2ASM/Spin2 and meant to be a hands-on reference for embedded development with the P2.

It covers topics like:

UART communication (high-speed async, echo, line input)

Interactive command input with backspace handling

Token parsing and command dispatch

State machines with optimized jump tables

SPI setup and full-duplex communication

Reading JEDEC ID from SPI flash

Streaming flash reads over UART

String handling routines (length, compare, copy, concatenate)

Number ↔ string conversions

And more

The manual is organized with explanations for each example, and every program has commentary describing how it works.

📌 Version: v0.1
📌 Repository: https://github.com/propeller-mcu/propeller2_asm

This is an early release, and I’d really appreciate feedback from the community — especially on:

Example enhancements

Clarity of explanation

Anything that’s confusing or could be improved

I intentionally waited to polish formatting until the content was solid first, so this is about substance over style. If you find it useful, great — and if not, constructive feedback is more than welcome.

Thanks!

JonnyMac · 2026-02-24 15:07

Neat. Downloaded and will get it over to the print show (I like to hold books in my hands [showing my age]).

Though it's old, too, I tried a couple of examples using Propeller Tool. I figured out that I have to download to flash (F11), open the terminal (PST), and then reset the P2. Still I was getting odd behavior from time to time.

I noticed that some of your examples jump to an end label...

  jmp     #endprog

In the print JEDEC example that label is right above the variable definitions

  endprog

  spi_command         res 1
  spi_reception       res 1
  uart_transmission   res 1
  hexadecimal_copy    res 1

I was seeing funny things in the PST window. When I add a line at endprog, everything settled down.

  endprog
    jmp  #$

Is it possible that the P2 is interpreting the variables as instructions? Or that the cog just runs out? In all of my Spin code, especially code that prints to a terminal, I go into a repeat loop so that the TX pin doesn't shutdown and send garbage to the terminal. Am I missing something?

proppy · 2026-02-24 15:24

@JonnyMac said:

Is it possible that the P2 is interpreting the variables as instructions? Or that the cog just runs out? In all of my Spin code, especially code that prints to a terminal, I go into a repeat loop so that the TX pin doesn't shutdown and send garbage to the terminal. Am I missing something?

Thank you for the feedback! Most likely yes! That's because the jmp literally jumps to endprog. The only thing is, on FlexProp, I don't seem to run into that issue. But possible it may be an issue if using PNut or other software, since it might see those variables and just execute them, basically executing garbage. I do not have PNut but this helps the manual since jmp #$ should work in FlexProp.

Wuerfel_21 · 2026-02-24 15:30

Letting the program counter just run off is definitely an error. You need to either enter an infinite loop or issue a cogstop. What happens afterwards will (in the case of very short programs) largely depend on stale RAM contents, which might differ based on a number of things. (If you have the debugger enabled, it should set unused memory to zero on startup...)

JonnyMac · 2026-02-24 17:14

...on FlexProp, I don't seem to run into that issue...

It's work, I know, but I suggest you ensure your code works with PNut, FlexProp, and Spin Tools. I try to do this with anything I release to the public.

proppy · 2026-02-24 17:22

@JonnyMac said:

...on FlexProp, I don't seem to run into that issue...

It's work, I know, but I suggest you ensure your code works with PNut, FlexProp, and Spin Tools. I try to do this with anything I release to the public.

Oh I don't disagree. I just updated the repository with the fix. Also, you may want to get the pdf again before printing. I refreshed the examples in that as well. For PNut, I may need to dig up a machine and put windows on it, so that part may take a bit but will do this before official v1.0 though. Thank you!

JonnyMac · 2026-02-24 17:25

PNut is not a big program, it will probably run in a VM.

ersmith · 2026-02-24 17:30

PNut works reasonably well under Wine. Getting the serial communication to work is a bit fiddly, but you can always compile the binary and then download it with loadp2.

proppy · 2026-02-24 17:34

@JonnyMac said:
PNut is not a big program, it will probably run in a VM.

@ersmith said:
PNut works reasonably well under Wine. Getting the serial communication to work is a bit fiddly, but you can always compile the binary and then download it with loadp2.

Oh really? Perfect! Thanks for that. I do have a FreeBSD machine with Wine so i can try it out there.

Rayman · 2026-02-25 02:55

Have to wonder if would be better to use Debug rather that hard coded uart…

proppy · 2026-02-25 03:38

@Rayman said:
Have to wonder if would be better to use Debug rather that hard coded uart…

I think it's good for people to learn the smartpin stuff at the lower level, at least that was my experience. I would have to test if FlexProp Debug is the same as PNut as well. It may not be a bad idea to add DEBUG as a shortcut at least though! Thank you!

evanh · 2026-02-25 06:37

Yes, the UART mode is a good one to actually setup and use.

That's something I need to add to my wish list of future new hardware - Merge the async and sync serial modes so that a mix of the features can be selected from. Namely providing for clocked start and stop bits. Such a device would've been able to handle I2C and 1-bit SD.

evanh · 2026-02-25 08:10

simclk ... Never seen that mentioned anywhere to do with the Prop2.

evanh · 2026-02-25 08:15

In your various examples of setting up smartpins, it is advised to first always do a DIRL to ensure the smartpin is disabled before configuring. This covers the more real world scenarios where smartpins get reconfigured instead of just an initial config. Often a pin mode needs switched in and out repeatedly.

evanh · 2026-02-25 08:27

The flush routine could actually check the smartpin for completion. Here's an old one of mine:

'Wait for comport transmitting to complete
'  input:  (none)
' result:  (none)
'scratch:  (none)
'
waittx
                rqpin   inb, #DIAGTXPIN   wc    'transmiting? (C high == yes)
        if_nc   ret wcz
                jmp     #waittx

evanh · 2026-02-25 08:37

In the "WAITX vs NOP" topic you mention that instructions execute in one clock cycle. This is incorrect, base instruction execution takes two clock cycles.

I do wonder where your info is coming from? ChatGPT maybe?

EDIT: Ah, maybe some of this pertains to very early FPGA development where it was indeed an instruction per clock. That became known as the Prop2-Hot design. Which would probably explain the simclk reference as well.

For future documenting, anything you find prior to year 2020 can be discarded as not valid for finished Prop2 chips.

proppy · 2026-02-25 13:16

@evanh said:
Yes, the UART mode is a good one to actually setup and use.

Thank you. Had a lot of help from the forum in my earlier post on how to do it.

@evanh said:
simclk ... Never seen that mentioned anywhere to do with the Prop2.

Ah, closer to the beginning of the manual. I can remove this. It is not apart of the P2 chip itself but is it something I saw in a code example.

@evanh said:
The flush routine could actually check the smartpin for completion. Here's an old one of mine:
'Wait for comport transmitting to complete
'  input:  (none)
' result:  (none)
'scratch:  (none)
'
waittx
              rqpin   inb, #DIAGTXPIN   wc    'transmiting? (C high == yes)
      if_nc   ret wcz
              jmp     #waittx

This seems oddly familiar. I think i might have asked something or seen someone in a forum post about this. I'll check it out.

@evanh said:
In the "WAITX vs NOP" topic you mention that instructions execute in one clock cycle. This is incorrect, base instruction execution takes two clock cycles.

I do wonder where your info is coming from? ChatGPT maybe?

EDIT: Ah, maybe some of this pertains to very early FPGA development where it was indeed an instruction per clock. That became known as the Prop2-Hot design. Which would probably explain the simclk reference as well.

For future documenting, anything you find prior to year 2020 can be discarded as not valid for finished Prop2 chips.

Yes actually, I was looking for beginner gotchas. The exact start of the rabbit hole was here, among others:
https://forums.parallax.com/discussion/167871/who-will-be-prop2s-biggest-competition/p2

proppy · 2026-02-25 15:21

I have made the proposed updates to the document/code so far and put them on the front page of the github.
The following outstanding points i need to test a bit:

Debug rather that hard coded uart…
The flush routine could actually check the smartpin for completion.
suggest you ensure your code works with PNut, FlexProp, and Spin Tools.

Thanks everybody for all the help!

Propeller 2 Assembly Language beginner guide v0.1

Comments