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

[Joerg Wunsch]

David McNab <address@hidden> wrote:

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

Well, if you've got WinAVR, it comes there for free.  If you've got
any kind of Unix distribution that includes the GNU assembler, one
should hope it also ships a copy of the GNU assembler info pages.

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

It basically is.  The lack of the AVR-specific details in the
assembler manual has been a bug.  Other architectures did go and
document their specific stuff in the GAS manual.  I think this has
historical reasons: when AVR-GCC was started by Denis Chertykov, he
made it emit code for another assembler that was already available by
that time, so he didn't have to port GNU binutils to the AVR as a
prerequisite.  When the port of GNU binutils was done later (either by
Denis or by Marek Michalkiewisz, I don't know for sure), they've got
plenty of things to do, and eventually forgot to also add the target-
specific documentation.

Again, as most people are interested in the C part of the game, the
assembly stuff could be seen as some kind of "private negotiation"
between the compiler and the assembler, since most people wouldn't
even look at the generated assembly code at all.  So it's at least
understandable the missing documentation has never raised too many
questions about it.  I guess those who really wanted to know
eventually figured it out by looking at the GCC-generated code.

(Generating documentation index)

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

Well, building the documentation already has such a large number of
prerequisites, another one (like a scripting language interpreter)
wouldn't matter at all, at least as long as it's a commonly used one
like the languages you mention.  Personally, I've been using Perl for
maybe 15 years now, so I never really got a need for another scripting
language, but as Ted Roth left us some Python code, and some guys in
my job also prefer that language, I can live with that one as well.
(My only gripe with Python is that they made white space a
syntactically significant element.  This one is really stupid.)

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

Ah, OK, technically that's not macros but operators.  And yes, these
belong to the target-specific parts of GAS that used to lack
documentation so far.  I hope that has been fixed now (but didn't look
at it myself yet).

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

No, they must come from whatever environment you've been looking at.
avr-libc uses a few of these internally.  Their definition files are
in the common/ subdirectory.  However, they are purely meant for
library internal use, and are not being exported.

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

That should be simple, yes.

Code attached (tested for an ATtiny26).

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

But what's the purpose?  The code already takes just 162 bytes, or
about 8 % of the smallest processor where this demo could be run at,
the ATtiny26.  It cannot be run on an ATtiny13 because it lacks enough
IO pins to drive the LEDs.  Even on the ATtiny26, you'd have to blow
the RSTDISBL fuse in order to access the 8th LED.  The generated
assembly code is about as tightest as possible, so the only thing you
could really save is the C startup code.  But then, will you get any
money back from Atmel for not using the entire flash ROM? ;-)

So this is rather a typical example for why one would *not* want to
resort to assembly, if C could do the job adequately, and within *way*
less of development time.  (I wouldn't have written you the example in
assembly within those last 10 minutes it took me to prepare the C one.
OK, it will/would take another hour or two to prepare the
documentation for it.)

That's what I meant with real-world examples.  The existing assembly
demo at least had a real "story" behind it: to get around the fairly
limited resources of the ATtiny13 that has been the original target,
namely its lack of a second timer.

Btw., the bargraph demo wouldn't touch the area of passing arguments
from C to asm functions at all, as simple as it turned out to be.
It's even smaller than the original LED flasher demo.

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

OK, fine with me.  Are you willing to also contribute the doxygen
documentation? ;-)  (So far, for all of the examples, preparing the
docs took me much more time than preparing the actual code.)

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

I don't mind, as long as it's really "live".  I know the Wiki from
www.mikrocontroller.net is, but that's German only.  So far, the best
international resource is still avrfreaks.net, but they don't have a
Wiki.  Maybe we should convince them of introducing one?  But that
could become hard, as I can imagine Atmel (as the company hosting the
service) wouldn't want to be held responsible for the contents when
anyone on earth could modify that contents.

So it's simply the other way 'round: as soon as www.avrwiki.com offers
enough value/contents that people find it worth the while, it could
deserve a link on the avr-libc pages.  I realize that's some kind of
barrier or critical mass situation, but it certainly doesn't make much
sense to place links to something that could eventually perhaps maybe
become a reasonable resource of knowledge some day.

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

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

bargraph.c
Description: Text document