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

[David McNab]

On Wed, 2007-02-28 at 15:21 +0100, Joerg Wunsch wrote:
> 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.

WormFood on the irc.freenode.net#avr kindly tossed me a link to the gnu
'as' manual. But he did mention that it was buried deeply on the gnu
site, and that it took him/her several attempts and searches to find it.

> 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.

If there's no AVR-specific toolchain doco, then I could see the libc
doco as a good temporary place to put it.

But sooner or later, the doco does need to be separated between
toolchain programs and libraries.

> >  - 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!

That's a lamentable limitation in doxygen. Most of the other
source-code-markup doco systems have an index feature, such as epydoc,
javadoc etc.

It's easy to cut a python/perl/ruby script to spider the doxygen pages
and generate a master index. I could do a Python one, if anyone could
assure me that it would be taken up.

Another option is to feed the doxygen pages and ancillary hand-written
pages into a cacne and search engine combo such as WWWOFFLE plus
ht://dig; throw 'wget -r' at it and you'd end up with one really nice
database and index. But that's not appropriate for distribution.

> >  - there's no definitive list of assembler macros
> 
> What kind of macros are you talking of?

lo8(), hi8(), pm() etc - that is, if there's any more where these have
come from.

I've also bumped into a few assembler macros such as FUNCTION(). Are
these officially supported?

> 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.

Some folks, however, would quickly turn their minds to the C+assembler
angle, especially when they throw a bit of pure C at the toolchain, look
at the code size and think 'yikes!' at the prospect of fitting it all
into a 2k MCU.

> >  - 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.

Forums are only as good as their search engines. Even if a forum has a
good search engine that allows google-like binary expressions and
full-text search, there's still a degree of mental labour involved.

> Having said this, I'm always all ears for ideas for more example
> projects.

One idea - a 'bar graph' which regularly reads an ADC pin, shifts the
10-bit analog value down to 3 bits, then lights one of 8 LEDs.

This could be done in several versions - one in pure C, then successive
versions which replace more and more of the C with assembler routines.

>   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".

I'm working on a bytecode interpreter, which executes a combination of
bytecode functions and primitive C functions. If I get that working to
my satisfaction, I'll submit that as well, since it it's low to medium
complexity and demonstrates some issues of C assembler interfacing.

> > 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.

Agreed.

Again, I suggest that a wiki such as www.avrwiki.com might be the
perfect place to hold a gcc-avr/avr-libc knowledgebase. Putting the
knowledgebase wiki to use would only require a single link from the
avr-libc homepage to a single portal page on that wiki, and writing that
portal page in such a way as to motivate contributions.

This would take a huge burden off the avr-libc developers/maintainers
and promote a greater sense of community. It would also encourage people
to help build a very accessible knowledgebase which would cut newbies'
head-scratching by orders of magnitude.

At the moment, avrwiki.com only has a single gcc-avr/avr-libc related
page, a howto for building the toolchain. There's unlimited scope for
using this wiki to build up a huge and very welcoming resource. I know
I'd much rather surf a wiki than trawl through forum archives, and I'm
sure I'm not the only one who feels this way.

What do you think?

Cheers
David