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

[Erik Christiansen]

On Wed, Feb 28, 2007 at 10:27:42AM +1300, David McNab wrote:
> 
> But - I've been having a hard time with learning avr-gcc, largely due to
> the way the documentation (or lack of it) is organised.
> 
> To give some examples:
>  - 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

$ info as

For me, "* Pseudo Ops::                  Assembler Directives"
is 6th from the bottom. That stuff isn't avr-as specific.

>  - 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
>  - there's no definitive list of assembler macros
>  - 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

One thing that wasn't well documented when I started was the lo8/hi8
operators for data (byte addressed) and program (word adressed) address
loading. The macros I use to simplify my assembler coding show the usage
of the operators, even if you don't find them attractive for your
coding:

; Data Pointer initialisation of a register pair.
; Usage:
;        dptr  Y,some_data
;        ld    r16,Y          ; OR lpm r16,Y if some_data is in flash.

   .macro dptr reg,addr
   ldi   \reg,lo8(\addr)
   ldi   \reg + 1,hi8(\addr)
   .endm

; Program Pointer initialisation of a register pair.
; Usage:
;        pptr  Z,program_address
;        icall

   .macro pptr reg, addr
   ldi   \reg, pm_lo8(\addr)       ; Does byte_address/2,
   ldi   \reg + 1, pm_hi8(\addr)   ; for use with icall.
   .endm

Apart from reducing the typing required, it isn't necessary to fuss with
excessively low level detail each and every time, just because we're
using assembler. :-)

Erik