On Wed, 2007-02-28 at 15:21 +0100, Joerg Wunsch wrote: > David McNab <[EMAIL PROTECTED]> 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 _______________________________________________ AVR-GCC-list mailing list AVR-GCC-list@nongnu.org http://lists.nongnu.org/mailman/listinfo/avr-gcc-list