Is FullDuplexSerial Annotated or Documented Anywhere?

coryco2

I have been playing with the FullDuplexSerial object recently, and was thinking how useful it would be for coding newbies (e.g. me) to have the function of each line of code documented/annotated in plain English, for the purposes of education and customization. Does anyone know if such an exposition of this object exists anywhere? If not, would anyone else be interested in seeing this done?

localroger

Some of the modified versions (with bigger and variable buffers and whatnot) are better documented, but none I've seen to the level you're asking. FDS is actually a pretty sharp bit of coding, which makes creative use of the PASM JMPRET instruction to hop between its transmit and receive "threads." This is a technique that is pretty unique to the Propeller and very obscure until you "get" it, and in fact it was reverse engineering FDS by which I figured out how that worked. That's what makes the FDS code seem hard to follow; when you understand how the JMPRETs are passing control back and forth it actually becomes quite simple to follow.

It is kind of a problem that we don't have any good high level tutorials for this kind of thing, and the classic Parallax objects like TV, VGA, and FDS are very clever, elegant, and sparsely commented so that everyone who wants to write a video or serial driver ends up having to half-way invent it from the ground up.

localroger

A little elucidation:

In PASM there is no such instruction as CALL. CALL is a macro. When you CALL a subroutine, you are actually issuing a JMPRET dest_RET, #dest. What this means is that control is transferred to #dest, but the return address (the address after the JMPRET) is written to the S field of the PASM location dest_RET. That's why if you use CALL you have to label the return instruction of your routine with a label routine_name_RET. That RET is also a macro, which generates a JMP, and when the CALL JMPRET writes its S field it becomes a JMP back to where the CALL occurred.

That's how it works NORMALLY.

In a codestream like FDS, you manually issue a JMPRET that specifies a "return" point other than a "RET" macro. You can use this to pass off control between code streams each of which might need to bail at multiple points to let the other do processing; each process uses JMPRET to write the point at which it must be re-entered when the other process is done. FDS uses this to let its transmit and receive threads each execute asynchronously as if, except for the JMPRETs, each thread has sole control of the Cog.

coryco2

Thanks for your comments. That helps a bit.

pedward

FullDuplexSerial is the first Gold Standard object, if you download the Gold Standard zip, it should have docs and samples. That said, it doesn't discuss the theory , just use details.

Tracy Allen

I put together a little tutorial pdf, attached, about how the jmpret mechanism works specifically for full duplex serial. The Prop manual has a nice enough description of the mechanism, but sometimes it helps to have a specific example.

RS_Jim

Tracy,
Thanks, that is great!
Jim

coryco2

Indeed! Thanks, Tracy.

Thanks also to pedward! I was unaware of "Gold Standard" objects until I found http://www.parallaxsemiconductor.com/goldstandard and the much better-documented version of FullDuplexSerial there.