Propeller 2 Documentation Nomenclature?

JonTitus

It would help new users of the Propeller 2 if the documentation (v33) included a Nomenclature section that would explain notation such as:

D/#
S/#
WC, WZ, WCZ
#S
S
#D
D

and so on. I'm confused and would like to know what these things mean. Also, I have no idea what the following information means. Explanations at the start of these instructions would help.

EEEE 0000000 CZI DDDDDDDDD SSSSSSSSS

Final point. The PAD_IO Modes diagram is almost unreadable. Could we have it in black type on a white background? Again, there's no explanation of what these columns mean or how to interpret them.
Thanks. --Jon

Rayman

go to propeller.parallax.com and find instruction spreadsheet and docs

evanh

Here's an alternative for Pad IO Modes - https://forums.parallax.com/discussion/comment/1452036/#Comment_1452036

And Rayman and I have just been improving a block diagram of the I/O to go with that - https://forums.parallax.com/discussion/171420/smartpin-diagram/p1

Rayman

Assembly instructions have a format like this:

EEEE 0000000 CZI DDDDDDDDD SSSSSSSSS	ROR     D,{#}S   {WC/WZ/WCZ}	Rotate right.           D = [31:0]  of ({D[31:0], D[31:0]}     >> S[4:0]). C = last bit shifted out if S[4:0] > 0, else D[0].  *

That first part divides the 32 bit instructions into different bit fields like D..D and S..S (these are destination and source bits, 9 bits each)
Most instructions have a format like: ROR D,S where D is "destination" and S is "source"
You can also add in WC, WZ, WCZ after which is for "write carry flag", "write zero flag", "write both flags" This is also the CZ bits in the binary part on the left.

Assembly instructions can also have a prefix, like "if_c" for "if carry flag is set". This is coded into the EEEE bits in the instruction. See bottom of spreadsheet for how.

The "0000000" is the code for the ROR instruction.

The reason for the # is because source can be either an immediate (actual value) or the number of the register to be used. The I bit decides this.

Rayman

The format is really close to that of P1 where there is a pretty good manual.
You might want to look at the assembly section of that for clues...

https://www.parallax.com/sites/default/files/downloads/P8X32A-Web-PropellerManual-v1.2.pdf

JonTitus

Thanks for your comments. The Propeller Manual (Version 1.2) has useful information and I understand the use of D and S as register identifiers, and #D and #S as literal values. But, I still don't know what the documentation means with the notations, D/# or S/#. Do those mean literal OR address in these bit spaces? The original Prop documentation uses the notation <#>Source, or <#>S. Why adopt a new notation that can confuse people? What does {#}D mean? Is that the same as D/# or#D, or something else? The Prop-2 documentation might include a "Syntax Definitions" section similar to that in the Propeller Manual on page 46. Without better clarity and explanations, readers will quickly get frustrated and switch to another microcontroller.

As a hardware-mainly guy I'm most interested in the Smart Pins. They are "loaded" with interesting operations. But on the third page in the SMART PINS section, the document notes, "The table below shows the %P..P bits as M[12:0]:"

Wait... on the previous page the document shows five M bits: ...PPP_TT_MMMMM_0

Are we talking about the same "M" bits? Why do two sets of bits have the same notation? Why not stay with P, as in (P[12:0])? This is the type of documentation problem that will drive hobbyists and engineers alike batty.

I've worked as a technical writer and understand the problems people face when they create documents and manuals. It takes time to get the facts straight and then to add text that helps readers. I hope you'll take my comments as helpful and not critical. I hope more information about the smart pins comes out soon.

Cheers. --Jon

rogloh

JonTitus wrote: »

Thanks for your comments. The Propeller Manual (Version 1.2) has useful information and I understand the use of D and S as register identifiers, and #D and #S as literal values. But, I still don't know what the documentation means with the notations, D/# or S/#. Do those mean literal OR address in these bit spaces?

Yes. And {#}D means the same as D/#. It's either a register address or a literal (constant) argument.

Also in that Smartpin diagram M[12:0] means the same as the %P..P bits in other places, not the MMMMM bits in ...PPP_TT_MMMMM_0. The diagram is just old and of sync with the docs. It needs an update, yes.

Alexander (Sandy) Hapgood

The people who follow these forums regularly have a better idea of the instruction set and how everything fits together. The P1 had a pretty good instruction manual but the P2, so far, doesn't have one. There are some spreadsheets but nothing useable for people who aren't in the know.

If P2 is to gain any traction in the market then documentation will have to improve. People are too busy to invest time in a poorly documented product.

JonnyMac

Keep in mind that the P2 hasn't yet been formally released. Documentation is difficult; I'm sure good stuff will come.

evanh

The M[12:0] is symbol reference to the schematics for the custom IO pad ring. So it won't be changing unless those symbols get changed. Just have to get used to knowing that they're the same as WRPIN's P field.

I would guess the finished prop2 manual will not include that Pad IO Modes table as is. The information in it will be reformatted to suit WRPIN.

JonTitus

Again, many thanks for your thoughts. I'm happy to help with the documentation and will continue to post suggestions, particularly about the Smart Pins section. Is there an editable version of the current documentation I could "play" with? On GITHub? I'll share anything I modify, add, delete... --Jon

Rayman

You can make suggestions on the doc file at propeller.parallax.com... I do...

JonnyMac

I believe public edits are enabled on Chip's Google docs
-- https://docs.google.com/document/d/1gn6oaT5Ib7CytvlZHacmrSbVBJsD9t_-kmvjd7nUR6o/edit#heading=h.1h0sz9w9bl25

JonTitus

Thanks, Jon.