Program gavrasm

AVR Assembler for ATMEL AVR-Processors
======================================

Command line Assembler for ATMEL AVR-Processors of the types
- AT90S
- ATtiny and
- ATmega.

For Linux i386 pre-compiled executable : gavrasm
For DOS resp. Win32 compiled executable: gavrasm.exe
Sourcecode for fpc-Pascal

Calls and options
-----------------

Call: gavrasm [-abelmqsw] SourceFile[.asm]
   Parameters:
     a: Switch output of ANSI-chars on/off
        default is on (Linux) resp. off (Dos, Win)
     b: Extended error comments for beginners
        default is off
     e: Longer error messages
        default is off (short error messages)
     l: Suppress output of the LIST-file
        default is LIST-file output on
     m: Suppress listing of expanded macros
        default is listing on
     q: No output of messages on the command line (quiet)
        (except: headers and forced messages!)
        default is output on
     s: Output a list of symbols in the LIST-file
        default is no symbol list
     w: Enable wrap-around
        default is wrap-around off
   Output files:
     SourceFile.lst ... Assembler-Listing, Textfile
     SourceFile.hex ... Code in Intel-Hex-format, Textfile
     SourceFile.eep ... EEPROM-content in Intel-Hex-format, Textfile
     SourceFile.err ... Error messages (if any), Textfile

Call: gavrasm [-?hdt]
   Parameters:
     ?: List of options
     h: List of options
     d: List of supported directives
     t: List of supported AVR types

Remark for the option a:
   The Linux version outputs ANSI code sequences by default,
   with other OS's this option is disabled by default. The
   option a inverts this switch under all operating systems.


Specialties of this Assembler
-----------------------------
Following only the special properties of this assembler are
discussed. All properties not mentioned explicitly, work like
in other assemblers, so these are compatible with others
(e.g. with the ATMEL(R)-assembler).

a) Main differences resulting in error and warning messages
   for code that assembles correct (without any errors and
   warnings) with other assemblers:
* gavrasm does not accept labels and directives on a single
  line, directives must all start in column 1 of a new line.
  An error messages warns about that.
* gavrasm does not allow instructions to begin in column 1
  of a line. Lines with instructions must start with a label,
  a blank or a tab character in column 1. This results in an
  error message.
* Header files for the AVR type (*def.inc) are not necessary,
  gavrasm knows them all by itself. Header files for known
  AVR types, included using the INCLUDE directive, are ignored,
  the file is not read. A warning is given. Instead of reading
  the header file, gavrasm identifies the AVR type from that
  line and, if recognized, defines its own AVR type-specific
  symbol set. Be aware of that if you change the header file
  for an AVR, because these changes don't come into effect
  under gavrasm. In contrast to other assemblers, the symbols
  of the AVR type are already defined with the DEVICE directive,
  including header files is no longer necessary.
* Filenames (e.g. in the INCLUDE directive, usually do not
  need to be in quotes. Under Linux always use quotes
  ("...") for the filename!
* Constant displacements in relative jump- or branch-
  instructions, usually written like " brcc PC+10" (where
  PC stands for PROGRAM COUNTER), are already recognized
  if the displacement is preceeded by a '+' or '-'
  character, like " brcc +10". The use of the notation PC+10
  is optional.

b) Source code is available and documented:
* FPK-Pascal, written and tested for Linux-(i386), DOS-(go32v2)
  and Win32-FPK (use latest version, older versions have problems
  with some of the Pascal instructions)
  (FPK-Compiler available at http://www.freepascal.org)
* Source code files provided:
  gavrasm.pas:  Main program file
  gavrdefs.pas: Unit that provides all symbols of all supported
                AVR types, *def.inc-Include files no longer needed
  gavrif.pas:   Unit providing nested if/else/endif support
  gavrinst.pas: Unit with the instruction set of the AVR's
  gavriset.pas: Unit with processor-specific instruction set
                structure
  gavrlang.pas: Unit for language support (currently available
                in an english (gavrlang_en.pas) and german
                gavrlang_de.pas) version
  gavrline.pas: Unit to split the asm lines into pieces
  gavrmacr.pas: Unit for Macro-processing
  gavrout.pas:  Unit for Hex output
  gavrsymb.pas: Unit for symbol-processing
  gavrtype.pas: Unit for supported AVR-Types and their properties
* Prior to compilation: copy the language file gavrlang_en.pas
  and rename it to gavrlang.pas!
* Test file for checking of the assembler:
  instr.asm:    Test file with all AVR instructions

c) Extra directives (Pseudo opcodes):
* DEVICE now automatically provides all symbols of the respective
  AVR type, forget the *def.inc-files, you'll never need them any
  more.
* The EXIT-directive without conditions works normal (interrupts
  further assembling process of the currently processed file)
  and is compatible with other assemblers. If an additional
  parameter is  given, usually a comparison, this is interpreted
  as a boolean value. If this is 1 (TRUE) the EXIT directive is
  executed, providing a conditional stop of the assembling
  process (stops the assembling process completely). This
  conditional EXIT directive also works within INCLUDE files.
  This feature can be used to check for error conditions during
  the assembly process (e.g. stop if limits for certain symbol
  values are exceeded, as an overflow detection).
  This directive can, in part, be exchanged with the directive
  .ERROR, that produces an error message.
* Additional .IF, .ELSE, .ELIF and .ENDIF directive: .IF (condition)
  assembles the following code only if the condition is true (1),
  otherwise branches either to the code after .ELSE, .ELIF or .ENDIF.
  Allows nested .IF, .ELSE, .ELIF and .ENDIF directives of any depth.
* The .IFDEVICE parameter directive compiles the following code,
  if the type specified by the parameter is equal to the one
  specified in the .DEVICE statement.
* .IFDEF and .IFNDEF tests for defined and unsdefined symbols
  and works like the .IF directive.
* .MESSAGE displays a message (in "..." as parameter) on the list
  output, which is not suppressed in the quiet-mode.
* .ERROR forces an error with a message (in "..." as parameter) on
  the list output and in the error textfile.
* Additional .SETGLOBAL p1,p2,[...] directive to export local
  macro symbols. Otherwise symbols defined within a macro are
  completely local and cannot be used outside of the macro. Be
  careful with that feature, it might be source for errors.
* Recursive .INCLUDE-directive with unlimited depth. Under Linux,
  always use quotes for the filename ("...").
* List of supported directives available by gavrasm -d

d) Makros:
* Extended macro capabilities:
  - recursive macro calls without limitations
  - extended parameter checking within the macro definition, not
    only at the macro call itself
  - all labels and symbols in macros are defined locally, they
    are not accessible from outside the macro, improves error
    recognition
  - export of local symbols by use of the SETGLOBAL directive
  - labels in macros are correct even during forward use and if
    used in recursive calls
  - optional use of .ENDM or .ENDMACRO to close the macro definition
  - List of all defined and used macros in the listfile, if the symbol
    list is switched on with -s (and by not suppressing list output
    on the command line by not using the -l option or by .LIST in the
    source code)

e) Improved error detection, commenting and syntax checking:
* Extended symbol checking:
  - exact symbol type checking (cases R for registers, C for
    constants, V for variables, T for AVR type definitions,
    M for local macro labels, L for global macro labels)
  - the use of mnemonics as symbol names is prohibited,
    excludes those used by ATMEL within some older header
    files (accepts OR and BRTS as a symbol name)
  - extended recognition of undefined symbols
* Extended error commenting and warnings (more than 100
  error types, 8 warning types)
* Enhanced syntax commenting for beginners (option b) for
  instructions and directives in the list file
* Extended calculation check (Over- and Underrun of internal
  32-bit-Integer values)
* Extended characters in literal constants and strings: ';',
  '''', '\n', '\\', "abc\n\j", "abc;def"
* Separator character (dots, '.') in binary- and hex-numbers
  for improved readability of the source code (e.g. 0b0001.0010,
  $124A.035F, 0x82.FABC)
* BYTE1-function implemented (similiar to BYTE2 etc.)
* Allows constant displacement in relative jumps, e.g. rjmp +10 or
  brcc -3 (displacement must start with + or - in that case)

f) Supported AVR-types:
* ATtiny: 11, 12, 13, 15, 22, 25, 26, 28, 45, 85, 2313
* AT90C: 8534
* AT90S: 1200, 2313, 2323, 2333, 2343, 4414, 4433, 4434, 8515,
         8535
* ATmega: 8, 16, 32, 48, 64, 83, 88, 103, 104, 128, 1280, 1281,
          161, 162, 163, 165, 168, 169, 2560, 2561, 323, 325, 
          3250, 603, 640, 645, 6450, 8515, 8535
* AT86RF401
* List of supported AVR types with gavrasm -t

g) Language versions currently supported:
* English, German (just copy the file avrlang_xx.pas to avrlang.pas
  by overwriting it and recompile)

h) Open issues and unresolved errors:
* none.

Versions and Changes
--------------------
Latest versions at http://www.avr-asm-tutorial.net/gavrasm/index_en.html

April 2005: Version 1.3
- Corrected: EEPROM capacity of the ATmega104 and 128
- Added: Support for types ATmega 1280, 1281, 2560, 2561 and 640

March 2005: Version 1.2
- Corrected: Error in bit WGM02 of port TCCR0B in the ATtiny13
  constants
- Corrected: Missing parameters in a number of instructions were
  accepted without an error
- Added: Support for the new types ATtiny25, 45 and 85

January 2005: Version 1.1
- Corrected: Error in the number of warnings
- Corrected: Error in using SETGLOBAL
- Corrected: Error in using underscore in macro names
- Added: Support for using the currect program counter PC as a variable,
  e.g. in RJMP PC+3 or brcc PC-2.

October 2004: Version 1.0
- Added: Support for new types ATmega325/3259/645/6450
- Changed: Complete rewriting of the directives
- Added: New directives .ERROR, .MESSAGE, .ELIF, .IFDEF and .IFNDEF
  for enhanced compatibility with the ATMEL assembler
- Added: Error output to a separate error file source.err.

March 2004: Version 0.9
- Added: Support for the new types ATmega48/88/168

Febrary 2004: Version 0.8
- Corrected: Error with setting the symbol RAMEND removed
- Corrected: Some SRam settings for older ATmega types were false
- Corrected: Assembler did not run in the short error message mode
  by default

October 2003: Version 0.7
- Added: Support for new type ATtiny2313
- Added: .IFDEVICE directive
- Changed: Reliability of ATtiny22 instruction set now fine

September 2003: Version 0.6
- Corrected: Error when using negative numbers in binary operations
- Corrected: Error with type checking in .DEVICE statement
- Added: def.inc include files now trigger the internal symbol defini-
  tions, no error message any more, a warning is given and the def.inc-
  file is not read
- Changed: Complete instruction set reworked
- Added: Several older device types, warning for undocumented types
- Added: Nested .IF, .ELSE and .ENDIF directives

August 2003: Version 0.5
- Corrected: LD/ST instruction for type AT90S1200 added,
  resulted in an error message in previous versions

July 2003: Version 0.4
- Corrected: Misleading error message when using an undefined
  register
- Added: DEVICE now adds all predefined symbols, as listed in
  the data sheet of the respective processor (these were
  previously provided by def.inc-files). Attempting to include
  a *def.inc-file results in an error message!
- Added: Support for the new type AVRtiny13 (even before ATMEL
  has released its def.inc!)

June 2003: Version 0.3
- Corrected: Detection of double labels improved (ran into
  internal compiler error)
- Corrected: Constant expressions starting and ending with a
  bracket lead to a strange error message, therefore removed
  the support for macro calls with parameters in brackets

May 2003: Version 0.2
- Added: SETGLOBAL directive for export of local symbols in
  macros
- Added: Wrap-around allowed in relative jumps/calls. Wrap is
  also possible in relative (conditional) branches (BRCC etc.),
  difference to the ATMEL assembler!
- Fixed: Addressing in hex-file now compatible with Studio/Wavrasm
  (byte-oriented, not word-oriented, also handles multiple .ORG
  directives correct
- Fixed: LSL and LSR instruction for AT90S1200 are valid, invalid
  error message in version 0.1
- Fixed: Labels, variables and symbols starting with an underscore
  are now accepted
- Fixed: Double division x/y/z yielded false result, corrected
- Fixed: Instructions starting in column 1 of a line produced a
  misleading error message, added hint
- Fixed: directives that don't start in column 1 of the line but are
  preceded by a label were not recognized, error message added
- Added: Command line option E for shorter (default) or longer
  error messages

December 2002: Version 0.1 Beta (first release)

Terms of use of this software
-----------------------------

- Copyright for all versions: (C)2002/2003/2004 by Gerhard Schmidt
- Free use of the source code and the compiled versions for non-
  commercial purposes. Distribution allowed if the copyright
  information is included.
- No warranty for correct functioning of the software.
- Report errors (especially any compiler errors) and your
  most-wanted features to gavrasm@avr-asm-tutorial.net (Subject
  "gavrasm 1.2"). If errors occur, please include the source code,
  any include files, the list and the error file.
