2004-10-21  Joerg Wunsch <address@hidden>

	* doc/api/assembler.dox: Add section about gas
	pseudo-ops and AVR-specific operators
	* doc/api/faq.dox: add xref to that section here.

Index: doc/api/assembler.dox
===================================================================
RCS file: /cvsroot/avr-libc/avr-libc/doc/api/assembler.dox,v
retrieving revision 1.4
diff -u -u -r1.4 assembler.dox
--- doc/api/assembler.dox	30 Mar 2003 21:36:00 -0000	1.4
+++ doc/api/assembler.dox	21 Oct 2004 21:13:50 -0000
@@ -1,4 +1,4 @@
-/* Copyright (c) 2002, Joerg Wunsch
+/* Copyright (c) 2002,2004, Joerg Wunsch
    All rights reserved.
 
    Redistribution and use in source and binary forms, with or without
@@ -260,4 +260,68 @@
 obviously, should end in a \c reti instruction.  (By default, a jump
 to location 0 would be implied instead.)
 
+\section ass_pseudoops Pseudo-ops and operators
+
+The available pseudo-ops in the assembler are described in the GNU
+assembler (gas) manual.  The manual can be found online as part of the
+current binutils release under http://sources.redhat.com/binutils/.
+
+As gas comes from a Unix origin, its pseudo-op and overall assembler
+syntax is slightly different than the one being used by other
+assemblers.  Numeric constants follow the C notation (prefix \c 0x for
+hexadecimal constants), expressions use a C-like syntax.
+
+Some common pseudo-ops include:
+
+- \c .byte allocates single byte constants
+
+- \c .ascii allocates a non-terminated string of characters
+
+
+- \c .asciz allocates a \\0-terminated string of characters (C string)
+
+- \c .data switches to the .data section (initialized RAM variables)
+
+- \c .text switches to the .text section (code and ROM constants)
+
+- \c .set declares a symbol as a constant expression (identical to
+  \c .equ)
+
+- \c .global (or \c .globl) declares a public symbol that is visible
+  to the linker (e. g. function entry point, global variable)
+
+- \c .extern declares a symbol to be externally defined; this is
+  effectively a comment only, as gas treats all undefined symbols
+  it encounters as globally undefined anyway
+
+Note that \c .org is available in gas as well, but is a fairly
+pointless pseudo-op in an assembler environment that uses relocatable
+object files, as it is the linker that determines the final position
+of some object in ROM or RAM.
+
+Along with the architecture-independent standard operators, there are
+some AVR-specific operators available which are unfortunately not yet
+descriebed in the official documentation.  The most notable operators
+are:
+
+- \c lo8 Takes the least significant 8 bits of a 16-bit integer
+
+- \c hi8 Takes the most significant 8 bits of a 16-bit integer
+
+- \c pm Takes a program-memory (ROM) address, and converts it into a
+  RAM address.  This implies a division by 2 as the AVR handles ROM
+  addresses as 16-bit words (e.g. in an \c IJMP or \c ICALL
+  instruction), and can also handle relocatable symbols on the
+  right-hand side.
+
+Example:
+\verbatim
+	ldi	r24, lo8(pm(somefunc))
+	ldi	r25, hi8(pm(somefunc))
+	call	something
+\endverbatim
+
+This passes the address of function \c somefunc as the first parameter
+to function \c something.
+
 */
Index: doc/api/faq.dox
===================================================================
RCS file: /cvsroot/avr-libc/avr-libc/doc/api/faq.dox,v
retrieving revision 1.34
diff -u -u -r1.34 faq.dox
--- doc/api/faq.dox	21 Jul 2004 21:45:59 -0000	1.34
+++ doc/api/faq.dox	21 Oct 2004 21:13:55 -0000
@@ -56,6 +56,7 @@
 -# \ref faq_clockskew
 -# \ref faq_intbits
 -# \ref faq_fuselow
+-# \ref faq_asmops
 
 \section faq_volatile My program doesn't recognize a variable updated within an interrupt routine
 
@@ -1197,5 +1198,11 @@
 
 <small>Back to \ref faq_index.</small>
 
+\section faq_asmops Which AVR-specific assembler operators are available?
+
+See \ref ass_pseudoops.
+
+<small>Back to \ref faq_index.</small>
+
 */