Re: [avr-gcc-list] avr-gcc 'documentation'

[Joerg Wunsch]

David McNab <address@hidden> wrote:

>  - avr-as pseudo-ops - there seems to be no thorough list of
>  these. For example, I had to look through list archives to learn
>  how to declare a buffer in SRAM via the '.skip' pseudo-op

That's available in the GNU assembler manual.  Note that the GNU
assembler manual does not document each target's native instruction
set, as that is supposed to be published by the vendor.  Everything
else ought to be there.

As for the AVR-specific operators (like lo8 and hi8 and such), their
documentation has been lacking so far, but I've been told it has been
added into the binutils tree meanwhile, so they are supposed to be
documented with the next release.  For the time being, the avr-libc
documentation tried to fill that gap.

>  - a good part of the C API is well documented via doxygen, but
>  there is no consolidated global index of everything. Such an index
>  would prove a huge boost

If you know how to convince doxygen to produce that index, your
patches are more than welcome!

>  - there's no definitive list of assembler macros

What kind of macros are you talking of?

Btw., most people using the GNU tools don't focus on assembly language
at first, that's why the major part of the avr-libc documentation
concentrates on C rather than assembly.

>  - I can count the code examples on my left hand. There really need
>  to be several dozen examples shipped in /doc/examples in the
>  avr-libc distribution, ranging from the simplest to the more
>  complex

Well, the avr-libc examples are meant as some kind of "getting
started" only (but then, they are maintained by the avr-libc
maintainers, so with new releases, they are usually kept well up to
date).  Once you've got the first steps behind you, there's plenty of
examples that can be found on the Internet.  E.g. you could go to the
"Academy" of avrfreaks.net.

Having said this, I'm always all ears for ideas for more example
projects.  It's a bit of work to craft them, but it's also some fun.
If you've got something you'd really like to see, tell me about it.
I'm most interested in realistic examples, rather than anything that
sounds too much "artificial".

> To give an example of great microcontroller compiler doco, consider the
> PIC CCS C compiler manual:

Sure, a commercial vendor usually has a different focus here.  After
all, there's usually a single team who produces the software and
documentation, while we have three major teams (binutils, GCC,
avr-libc).  Out of these, only the latter is focused on the AVR, and
thus the avr-libc documentation aims to be something like the bracket
to summarize everything, but obviously, it cannot (and should not)
replace the more detailed (but not AVR-specific) documentation for
binutils and GCC.

-- 
cheers, J"org               .-.-.   --... ...--   -.. .  DL8DTL

http://www.sax.de/~joerg/                        NIC: JW11-RIPE
Never trust an operating system you don't have sources for. ;-)