Documentation?

Jack Buffington

I have a new project that I am about to launch into that I would like to use C for since parts of the program just wouldn't fit within a single COG so I can't use assembly and spin is so strange and slow that I'm not sure what to make of it. Is there a beta version of some documentation for how to use this compiler? I have poked around but haven't found much. I have found some of what I am looking for but not all of it.

Things that I would be interested in knowing are:

• How to add inline assembly language
• What variable types are available when writing for the Propeller and how many bits wide are they? I'm assuming that int is 32 bits. Is that correct?
• How to access things specific to the propeller like

[LIST=1|INDENT=1]
[*]HUB RAM vs COG RAM
[*]launch a cog / kill a cog
[*]access timers
[*]read the PAR register
[*]How to access the lock bits
[*]How to mix C with native spin or assembly programs. For example, if I already have an IO program that can communicate with an external device that was written in assembly or spin and runs within a single COG, can I make that play nicely with C programs?
[/LIST]

ersmith

The Wiki on the propgcc page (http://code.google.com/p/propgcc/w/list) contains a fair amount of documentation, as does the GCC manual which you can download from http://propgcc.googlecode.com/files/gcc.pdf (you'll mostly be interested in the Propeller specific portions of that one).

Some quick answers to your questions:

• Inline assembly is added with __asm__("assembly code goes here in a string"). The GCC manual has more details, including how you can pass arguments to the assembly and get results from it, but the basic form is just to put your assembly in a string inside __asm__, with \n for newlines.
• Signed and unsigned integers are available in sizes from 8 to 64 bits. The best way to get the size you want is to include <stdint.h> (a C99 standard header file) and use "int8_t", "uint16_t", "int32_t", and so on. Plain "int" is 32 bits, but it's better to use int32_t when you need exactly that many bits. Floats are 32 bits and doubles 64 bits by default, but this can be changed with -m32bit-doubles. "long double" is always 64 bits.
• Briefly:

1. COG RAM is only accessible one long at a time, via variables declared as __attribute__((cogmem)); otherwise it is used for code storage. HUB RAM is the default area for all data.
2. The file <propeller.h> has the functions you probably want (cogstart, cogstop, and so on). It is found in propeller-elf/include/propeller.h under the top level PropGCC installation directory.
3. All the hardware registers are also declared in <propeller.h>.
4. The PAR register is passed as the parameter to main() in a program built in COG mode. PAR is also, of course, declared in <propeller.h>.
5. There are builtin functions for the lock bits (again, see <propeller.h>).
6. The toggle demos illustrate a number of ways to mix C and assembly, or LMM C and COG C. Mixing Spin code is not supported, although there is a third party tool spin2cpp (http://code.google.com/p/spin2cpp) which can convert Spin code to C or C++.

There is certainly room for improvement in the documentation, of course, but the wiki is growing, and any contributions are welcome!

Eric

jazzed

Eric, thanks for pointing out those links and the other feedback.

Additionally, much of GCC is documented in gcc.pdf
The libraries provided to date are at www.parallax.com/propellergcc
Sorry that things are a little scattered right now.

Official Parallax documentation is coming soon.

jac_goudsmit

Jack Buffington wrote: »

I have a new project that I am about to launch into that I would like to use C for since parts of the program just wouldn't fit within a single COG so I can't use assembly and spin is so strange and slow that I'm not sure what to make of it. Is there a beta version of some documentation for how to use this compiler? I have poked around but haven't found much. I have found some of what I am looking for but not all of it.

Eric and Steve already answered your questions I think, but I'd like to point out that you appear to be exactly the audience for my in-depth document on the Google Code wiki: http://code.google.com/p/propgcc/wiki/PropGccInDepth

Inline Assembly is not part of that (I'm thinking of writing another document about that) but I have a project online that uses extensive inline Assembly, see: https://github.com/jacgoudsmit/Propeddle/blob/master/Software/p6502control.cogc

Hope this helps!

===Jac

photomankc

Very nice document you wrote there! Helps drag a lot of bits and pieces into one location.