View Full Version : Expanding on the "assembly language reference" in the Propeller manual..

01-19-2008, 02:41 PM

I find the assembly language ·reference in the original Prop manual V1.01 very limiting.
Very few of the asm instructions have actual examples of what the instruction
does .. the·3 instructions ·that I found needed further exploration for a little exercise
where the following ROR·· ROL·· and SAR.

So see attached some stuff I did today.
This will become part of·our ·ASM tutorial for our PropBus system.
More will be added as we have time..

Format of the file updated and re_posted 20JAN 2008

Cheers Ron Mel OZ

Post Edited (OzStamp) : 1/20/2008 9:52:16 AM GMT

01-19-2008, 05:44 PM
That is really nice! I have some comments to it:
(a) You have the instruction in the last column, its result is seen in the next row; I myself should expect it the other way round: giving the instruction leftmost, and seeing the result just right to it in the same column.

(b) You have to state C and Z in adition to the 32 bits

(c) ROR, SAR are extremely simple instructions that would not need such an amount of examples

(d) It is not possible to sneak out with so little explicite explainations as you do. Examples - even good examples - are rarely self explaining. This is a prejudice of people who have just understood the situation http://forums.parallax.com/images/smilies/smile.gif
Try it with WAITPNE please, to see my point!

(e) It is most helpful for some people to learn what certain instructions are meant for, i.e. not only give the working, which could be easily seen by all the debuggers and simulators we have, but WHY this is so, and what and under which circumstances it shall be used for (cf. SUBXS, MUX, DJNZ)

Post Edited (deSilva) : 1/19/2008 10:50:05 AM GMT

01-19-2008, 06:01 PM
Hi DeSilva.

To be a good asm coder I think the following ingredients are a must have...

1 Understand what the instruction does exactly ( yes and the status of the respective flags... good pointer)
2 know where to use the particular instruction..
3 also I found that in order to be good at this sort of stuff a good understanding of mathematics helps as well.

I recall about 25 years while at the time playing with the Z80 and other chips the excellent books that were out..
One comes to mind from Rodney Zaks it was an awsome book.. still got that book.
Over the years have mainly used PLC's for factory automation applications so aware of all the various instructions
but at a different level.. using a PLC you really have no concerns for Z C flags.. the programming software takes care of all that.

Anyway got your pointers.. (SAL you meant SAR )
Read thru your tutorial many times .. lots of good stuf there as well..

Anyway we will keep on exploring the stuff to grow our understanding of it all.
A little bit every day makes a big difference after a few weeks.

Cheers Ron

01-19-2008, 11:35 PM
The two instructions I find really hard to comprehend through their descriptions are RCL and RCR ...

Result: Value has Bits copies of C rotated left/right into it.

Explanation : RCL/RCR performs a rotate left/right of Value, Bits times, using the C flag’s
original value for each of the LSB's/MSBs affected.

I wouldn't be confident that this is a rotate-through-carry as found on other micro's, a fill with C-bit value from right or left, or something else entirely, without trying it and analysing the results. The "C flag's original value" suggests a fill, but "rotate" suggests some rotation not a shift.

A couple of code examples would make it much clearer what is happening without everyone having to determine exact functionality themselves.

I think there are a number of places where the descriptions could be slightly re-written to make the intent much clearer, for example with 'jmp' ...

Address (s-field) is the register or a 9-bit literal whose value is the address to jump to.

The following I think is even clearer to understand and not much more verbose ...

Address (s-field ) is a 9-bit literal value of address to jump to or a 9-bit register address of a register which holds in its lower 9-bits the address to jump to.

Those familiar with assembler elsewhere just need to check that a command does what they expect ( RCL, RCR etc ) and will often code as they think they should with reference to other code they've seen and generally get it right. They aren't really interested in the descriptions unless behaviour is different to expected ( SHL, SHR etc ) or particularly complicated at first glance ( JMPRET ).

Those unfamiliar need more help and explanation, and the descriptive documentation should IMO be aimed at those who need it most.

Such explanations can be added to the Wiki, third-party tutorials and references but the Propeller Manual would be the best place as it's where most people go first.

01-19-2008, 11:44 PM
@ Ron : I don't particularly like the way you've done it in the PDF, and "ORG" is a particularly bad choice for register name.

I agree with deSilva (a); "starting with this value X, apply this operation, the result is, C and Z are set as follows" is a more readily comprehensible format.

I don't like the grid / table style and separated bits; $0000_0000 (or %) would be clearer to me and much more compact.

01-19-2008, 11:56 PM
Well, I will agree that the assembly section of the manual is very lame. Critical information is omitted (such as proper use and benefits of RES). It seems they put all their efforts into the SPIN section and left just bare bones in the ASM section. It would be nice to know if they are planning on updating the manual with more info in the ASM section...

01-20-2008, 01:09 AM
@Rayman: Your criticism is fine, but when you want any results, just give me a list, and I add it to the "Tutorial". I have read many complains about flaws and shortcomings of the Chapter 5 of the Manual, but I think mst are halfhearted... It is not much work to include it all in my Tutorial as an appendix if really needed.

However the real needs are still dark: "better", "more explicit", "usage", "more exmples"??

I think the main mis-understanding is to expect you can LEARN assembly from Chapter 5, as you can LEARN SPIN from Chapter 3 (with some reference to chapter 4). Of course you cannot!

It is also annoying that there are yo many errors in Chapter 5, so you always have to consult the ERRATUM. For an experienced assembly programmer the Parallay information is however sufficient.

01-20-2008, 04:50 PM

Format of PDF updated see original post on top with new file

Ron Mel OZ