Shop OBEX P1 Docs P2 Docs Learn Events
PropGCC Documentation — Parallax Forums

PropGCC Documentation

SRLMSRLM Posts: 5,045
edited 2013-01-16 22:54 in Propeller 1
Where can I send documentation update requests? For example, the following are some of the things that could use better documentation that I ran into in the last couple of hours:

1. Locks. What are the semantics (ie, variable size...) and Did You Know? that the user has *7* (not 8) locks available? (source)
2. CMM vs. LMM: I find that LMM is roughly 2x bigger and 3x faster in practical applications (in my case, I2C bus).
3. Does a cogstart require that shared variables be marked as volatile?
4. Is CNT unsigned?
5. Why doesn't lockclr actually return anything (like in the Propeller manual)?
6. Is right shift arithmetic or logical? How do I choose?
7. Where is the PropGCC documentation? sites.google.com, learn.parallax.com, the wike on code.google.com, ...? All of the above?
8. Can the formatting on this page be improved? Specifically, the font face should be changed in some instances (code should be monotype).
9. Types seem to be missing completely from propeller.h. What are they?
10. And so on...

To be clear, I'm not asking for answers to these specific questions, I'm asking where they can be submitted for inclusion in the documentation. And if I can contribute directly to the documentation, I'd be willing to do that.

Comments

  • mindrobotsmindrobots Posts: 6,506
    edited 2013-01-15 19:36
    For now, unless a better solution comes along, could you open up an issue on the PropGCC wiki for documentation. Please include these items and any other items you find lacking. We are starting an effort to gather, sift through refine and consolidate the documentation. The items you list are some of the exact items we are addressing.

    It you would like to contribute any documents we can make arrangements for that also.

    This thread is going into my collection of things to document.

    Thanks!

    The Documenters
  • ersmithersmith Posts: 6,054
    edited 2013-01-16 08:29
    SRLM wrote: »
    Where can I send documentation update requests?
    Opening an issue on the propgcc Google page is a good way. Posting here works too :-).
    1. Locks. What are the semantics (ie, variable size...) and Did You Know? that the user has *7* (not 8) locks available? (source)
    Which locks to you mean? From the last sentence you seem to mean the hardware locks, which are 1 bit and have the hardware semantics specified in the Propeller manual. You could instead choose to use the 32 bit _atomic_t type from <sys/thread.h>, of which you can declare as many as you want.
    3. Does a cogstart require that shared variables be marked as volatile?
    Yes. This is standard C.
    4. Is CNT unsigned?
    Yes.
    5. Why doesn't lockclr actually return anything (like in the Propeller manual)?
    We didn't think users would very often need the return value of lockclr, and it takes another instruction to get this out of the carry flag. Did we miss some use case?
    6. Is right shift arithmetic or logical? How do I choose?
    unsigned expressions do a logical shift, signed ones do an arithmetic. This is the convention adopted by virtually all C compilers, although the C standard only specifies that unsigned shift right is logical.

    Thank you for the suggestions, and we'll work to improve the documentation.

    Eric
  • jazzedjazzed Posts: 11,803
    edited 2013-01-16 09:31
    Problems that are not immediately resolved should be reported on the Propeller-GCC issues page so that we can track them.
    SRLM wrote: »
    9. Types seem to be missing completely from propeller.h. What are they?

    Hi there. It's not clear what you mean. Almost everything in propeller.h itself is a macro which does not use types. The cogstart function is typed. We are looking at adding some things for P2 compatibility later and they will be typed.

    The formatting you mentioned mostly comes from doxygen tool output, but I had to change some formatting and links for google code. I thought the formatting was fine.

    We can add you as a contributor if you would like to make changes. If you have a google ID, PM it to me and I'll add you.
  • SRLMSRLM Posts: 5,045
    edited 2013-01-16 22:54
    jazzed wrote: »
    Problems that are not immediately resolved should be reported on the Propeller-GCC issues page so that we can track them.



    Hi there. It's not clear what you mean. Almost everything in propeller.h itself is a macro which does not use types. The cogstart function is typed. We are looking at adding some things for P2 compatibility later and they will be typed.

    The formatting you mentioned mostly comes from doxygen tool output, but I had to change some formatting and links for google code. I thought the formatting was fine.

    We can add you as a contributor if you would like to make changes. If you have a google ID, PM it to me and I'll add you.

    I tend to use Propeller.h as a reference for all things PropGCC Propeller. Even if they are macros, I think it would be nice to restate the underlying type (that it ultimately compiles to) to help prevent problems. For example, is OUTA signed or unsigned (in regards to right shift in particular). I know it might not be necessary ("the user could always look at where _OUTA is defined", and so on), but it would be nice.

    Sure, I'd be happy to flesh out documents as I learn something new.
Sign In or Register to comment.