Programm gavrasm

AVR Assembler fuer ATMEL AVR-Prozessoren
========================================

Kommandozeilen Assembler fuer ATMEL AVR-Prozessoren der Typenreihen
- AT90S
- ATtiny und
- ATmega.

Fuer Linux i386 compilierte ausfuehrbare Datei:     gavrasm
Fuer Dos bzw. Win32 compilierte ausfuehrbare Datei: gavrasm.exe
Quellcode in fpc-Pascal

Aufrufe und Optionen
--------------------

Aufruf: gavrasm [-abelmqsw] quelldatei[.asm]
   Parameter:
     a: Ausgabe von ANSI-Zeichen umschalten (An/Aus)
        Default ist An (Linux) bzw. Aus (Dos, Win)
     b: Erweiterte Syntaxkommentierung fuer Anfaenger (nur bei e!)
        Default ist Aus (kein zusaetzlicher Kommentar)
     e: Laengeres, ausfuehrlicheres Format fuer Fehlermeldungen
        Default ist Aus (kurze Fehlermeldungen)
     l: Ausgabe der LIST-Datei unterdruecken
        Default ist LIST-Datei-Ausgabe an
     m: Expansion von Makros nicht listen
        Default ist List ein
     q: Keine Ausgabe von Meldungen auf der Kommandozeile (quiet)
        Ausnahme: Erzwungene Meldungen (.MESSAGE)
        Default ist Ausgabe eingeschaltet
     s: Ausgabe der Liste der Symbole im Listing an
        Default ist keine Symbolliste
     w: Ermoegliche Wrap-around
        Default ist Wrap-Around ausgeschaltet
   Ausgabedateien:
     quelldatei.lst ... Assembler-Listing, Textdatei
     quelldatei.hex ... Code im Format Intel-Hex, Textdatei
     quelldatei.eep ... EEPROM-Inhalt im Format Intel-Hex, Textdatei
     quelldatei.err ... Fehlermeldungen falls zutreffend, Textdatei

Aufruf: gavrasm [-?hdt]
   Parameter:
     ?: Liste der Optionen
     h: Liste der Optionen
     d: Liste der unterstuetzten Direktiven
     t: Liste der unterstuetzten AVRTypen

Erlaeuterung zur A-Option:
   Unter Linux ist die Ausgabe von ANSI-Codesequenzen per
   Default eingeschaltet, bei anderen OS abgeschaltet. Mit der
   A-Option wird diese Voreinstellung bei allen Betriebs-
   systemen invertiert.


Eigenschaften des Assemblers
----------------------------
Im folgenden sind nur die Besonderheiten dieses Assemblers
beschrieben. In der Regel ist dieser Assembler kompatibel mit
anderen AVR-Assemblern (z.B. dem ATMEL(R)-Assembler).

a) Unterschiede dieses Assemblers, die zu Fehlermeldungen und
   Warnungen bei Code fuehren, der unter anderen Assemblern
   fehlerfrei assembliert wird
* gavrasm akzeptiert keine Direktiven in Zeilen, die mit
  einem Label beginnen. Direktiven werden grundsaetzlich nur
  dann akzeptiert, wenn sie mit einem Punkt in Spalte 1
  beginnen. Eine Fehlermeldung zeigt dies an.
* gavrasm akzeptiert keine Instruktionen, die in Spalte 1
  einer Zeile beginnen. Instruktionen muessen immer durch
  ein Label, ein Leerzeichen oder ein Tabulatorzeichen von
  Spalte 1 abgesetzt sein. Eine Fehlermeldung zeigt dies an.
* Die Header-Dateien von ATMEL(R), die die Symbole des ver-
  wendeten AVR-Typs enthalten, koennen mit der .INCLUDE-
  Direktive angegeben werden. Die Angaben zu der Datei
  werden aber von gavrasm ignoriert, die Datei wird nicht
  gelesen. Stattdessen wird aus dem angegebenen Dateinamen
  der AVR-Typ extrahiert und die intern im gavrasm gespei-
  cherten Symbole fuer diesen Typ gesetzt. Dies sollte man
  beachten fuer den Fall, dass die Header-Dateien vom User
  manuell geaendert oder ergaenzt wurden. gavrasm ignoriert
  wegen dieses Verhaltens die in der Headerdatei vorgenom-
  menen Aenderungen.
  Im Gegensatz zu anderen Assemblern werden die Symbole
  des betreffenden Typs bereits mit der DEVICE-Direktive
  festgelegt, ein Einlesen von Header-Dateien ist ueber-
  fluessig.
* Dateinamen (z.B. in der INCLUDE-Direktive) muessen nicht
  in Gaensefueszen angegeben werden. Dies gilt nicht fuer die
  Linux-Version, hier muessen Dateinamen in Gaensefueszen ein-
  geschlossen werden ("...").
* Absolutwerte z.B. bei Sprungdistanzen werden bereits dann
  erkannt, wenn die Sprungdistanz durch ein Vorzeichen
  eingeleitet wird, wie z.B. " brcc +10". Die Verwendung von
  PC+10 ist optional.

b) Verfuegbarer Quellcode:
* FPK-Pascal, fr Linux(i386), DOS (go32v2) und Win32
  Zum Kompilieren die neuesten Versionen des Compilers verwenden,
  aeltere Versionen haben Probleme mit einigen Pascal-Instruktionen
  (FPK-Compiler ueber http://www.freepascal.org erhaeltlich)
* Dateien:
  gavrasm.pas:  Hauptdatei
  gavrdefs.pas: Unit mit allen vordefinierten Symbolen der
                unterstuetzten AVR-Typen (ersetzt alle
                bekannten *def.inc-Dateien)
  gavrif.pas:   Unit zur Implementierung geschachtelter
                IF/ELSE/ELIF/ENDIF-Konstruktionen
  gavrinst.pas: Unit mit Instruktionsset der AVR-Prozessoren
  gavriset.pas: Unit mit prozessorspezifischer Befehlsstruktur
  gavrlang.pas: Unit zur Sprachauswahl (deutsch und englisch
                verfuegbar: gavrlang_de.pas, gavrlang_en.pas)
  gavrline.pas: Unit zum Splitten der asm-Zeilen in ihre
                Bestandteile
  gavrmacr.pas: Unit fuer die Makro-Verwaltung
  gavrout.pas:  Unit fuer die Hexausgabe
  gavrsymb.pas: Unit fuer die Symbole-Verwaltung
  gavrtype.pas: Unit fuer untersttzte AVR-Typen und ihre Eigen-
                schaften
* Vor dem Kompilieren die gewuenschte Sprachdatei (gavrlang_de.pas)
  kopieren und als gavrlang.pas umbenennen!
* Testdatei zur Ueberpruefung des Assemblers:
  instr.asm:    Testdatei mit allen AVR-Instruktionen
  testdir.asm:  Testdatei mit allen Direktiven des Assemblers

c) Direktiven:
* DEVICE-Direktive bindet automatisch alle Symbole des
  betreffenden AVR-Typs ein, das Include von *def.inc-Dateien
  ist damit jetzt ueberfluessig.
* Die EXIT-Direktive ohne Bedingung bricht die weitere
  Verarbeitung der Quelldatei ab und ist kompatibel mit
  anderen AVR-Assemblern. Zusaetzlich kann aber auch eine
  Bedingung als Parameter angegeben werden. Ist die Bedin-
  gung erfuellt (TRUE, 1), dann bricht gavrasm den gesamten
  Assembliervorgang hier ab. Dies funktioniert auch in
  INCLUDE-Dateien.
  Dieses Feature kann verwendet werden, um z.B. Bereichs-
  pruefungen waehrend der Assemblierung durchzufuehren und
  bei�Ueber- oder Unterschreitung bestimmter Grenzen mit einer
  entsprechenden Fehlermeldung abzubrechen.
  Diese Direktive kann teilweise durch die .ERROR-Direktive er-
  setzt werden.
* Zusaetzliche .IF, .ELSE, ELIF und .ENDIF Direktiven: Code
  nach .IF (Bedingung) wird nur assembliert, wenn die Bedingung
  wahr (1) ist, sonst wird zum Code nach der .ELSE-, .ELIF
  oder .ENDIF-Direktive verzweigt. Mit .ELIF kann im Unterschied
  zu .ELSE eine zusaetzliche Bedingung abgefragt werden.
  Beliebig tief verschachtelte .IF, .ELSE, ELIF und .ENDIF
  Direktiven sind zulaessig.
* .IFDEVICE ermoeglicht Verzweigungen abhaengig vom AVR-Typ,
  andernfalls wird nach .ELSE, .ELIF oder .ENDIF weiter
  assembliert.
* .IFDEF und .IFNDEF Direktive zur Abfrage, ob ein Symbol
  definiert ist oder nicht. Die Definition des Symbols MUSS
  vor der ersten Abfrage erfolgen, andernfalls resultieren
  Uebersetzungsfehler!
* .MESSAGE gibt eine erzwungene Meldung (in "..." als Parameter)
  aus und kann zur Benachrichtigung waehrend des Uebersetzens
  verwendet werden.
* .ERROR erzwingt einen Fehler mit einem definierbaren Fehler-
  text (in "..." als Parameter).
* Zusaetzliche Direktive .SETGLOBAL p1,p2,[...] zum Export lo-
  kaler Symbole aus Makros. Normalerweise sind Symbole (Labels)
  in Makros lokal, d.h. auszerhalb des Makros nicht verwendbar.
  SETGLOBAL stellt die gelisteten Symbole auch auszerhalb zur
  Verfuegung. Vorsicht bei der Anwendung dieses Features, es
  kann zu Fehlern fuehren.
* Rekursive .INCLUDE-Direktive mit beliebig tiefer Schachtelung,
  In der Linux-Version Dateiname auf jeden Fall in Gaensefuesze
  einschlieszen!
* Die Liste der unterstuetzten Direktiven wird durch Aufruf mit
  gavrasm -d ausgegeben.

d) Makros:
* Erweiterte Makro-Aufrufe:
  - verschachtelte Aufrufe ohne Begrenzung zulaessig
  - erweiterte Parameterueberpruefung bereits innerhalb der
    Definition, nicht erst beim Aufruf
  - alle Labels in Makros sind lokal definiert und von auszerhalb
    des Makros zwecks verbesserter Fehlererkennung unzugaenglich
  - Export lokaler Symbole mit der .SETGLOBAL-Direktive
  - Labels in Makros sind auch vorwaerts und bei verschachtelten
    Makrodefinitionen gueltig
  - Optionale Verwendung von .ENDM oder .ENDMACRO zum Abschluss
    des Makros
  - Liste aller definierten und verwendeten Makros im Listing,
    wenn die Ausgabe der Symbolliste eingeschaltet ist (Aufruf
    mit Option -s und ohne Option -l bzw. mit .LIST im Quellcode

d) Fehlererkennung und Syntaxpruefung:
* Erweiterte Symbolpruefung auf Zulaessigkeit:
  - exakte Unterscheidung nach Symboltypen (Typen: R fuer Register,
    C fuer Konstanten, V fuer Variablen, T fuer AVR-Typ-
    Definitionen, M fuer lokale Makro-Sprungmarken, L fuer
    Sprungmarken, G fuer globalisierte Lokalvariablen in Makros)
  - erweitert kompatibel mit den meisten gaengigen ATMEL-Header-
    Dateien (akzeptiert OR und BRTS als Symbolname, weil diese in
    aelteren *def.inc-Dateien von ATMEL(R) verwendet werden)
  - erweiterte Erkennung undefinierter Symbole, keine Default-
    Setzung auf Null
* Erweiterte Fehlerkommentierung und Warnungen ( mehr als 100
  Fehlertypen, 8 Warnungstypen)
* Ausfuehrliche Syntaxdarstellung im Anfaengermodus (Option -eb)
  zu fehlerhaften Instruktionen und Direktiven in der Listdatei
* Erweiterte Rechenpruefung (Ueber-, Unterlauf von Rechenschritten
  bei internen 32-Bit-Integerwerten)
* Erweiterte zulaessige Zeichen in Literalkonstanten: ';', '''',
  '\n', '\\', "abc\n\j", "abc;def"
* Zulaessiges Trennzeichen (Punkt, '.') in Binaer- und Hexadezimal-
  zahlen fuer verbesserte Lesbarkeit des Quellcodes (z.B.
  0b0001.0010, $124A.035F, 0x82.FABC)
* BYTE1-Funktion (analog zu BYTE2 etc.)
* Ermoeglicht bei relativen Spruengen die Angabe des
  Displacements, z.B. rjmp +10 oder brcc -3 (Displacement MUSS
  in diesem Fall mit einem Vorzeichen beginnen)

e) Unterstuetzte AVR-Typen:
* 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
* Liste der unterstuetzten AVR-Typen durch Aufruf mit gavrasm -t

f) Sprachversionen:
* Deutsche und englische Sprachversion verfgbar

g) Offene Punkte und bekannte Fehler:
* Keine.

Versionen und Aenderungen
-------------------------
Neueste Versionen unter
http://www.avr-asm-tutorial.net/gavrasm/index_de.html

April 2005: Version 1.3
- Korrigiert: falsche EEPROM-Groesse bei ATmega104 und 128
- Hinzugefuegt: Unterstuetzung fuer die Typen ATmega 1280, 1281,
  2560, 2561 und 640

Maerz 2005: Version 1.2
- Korrigiert: Fehler beim Registerbit WGM02 im Port TCCR0B des
  ATtiny13 war falsch
- Korrigiert: Fehlende Parameter bei einer Reihe von Instruktionen
  wurden faelschlicherweise ohne Kommentar akzeptiert.
- Hinzugefuegt: Unterstuetzung fuer die Typen ATtiny25, 45
  und 85

Januar 2005: Version 1.1
- Korrigiert: Fehler bei der Anzahl Warnungen
- Korrigiert: Fehler bei der Verwendung von SETGLOBAL
- Korrigiert: Fehler bei der Verwendung von underscore bei
  Macronamen
- Hinzugefuegt: Unterstuetzung fuer die optionale Angabe von
  PC bei relativen Sprungdistanzen.

Oktober 2004: Version 1.0
- Hinzugefuegt: Unterstuetzung fuer neue Typen ATmega325/3250/
  645/6450
- Geaendert: Gesamte Auswertung von Direktiven ueberarbeitet
- Hinzugefuegt: Neue Direktiven .ERROR, .MESSAGE, .ELIF, .IFDEF,
  IFNDEF fuer verbesserte Kompatibilitaet mit neueren ATMEL(R)-
  Assemblern
- Hinzugefuegt: Ausgabe aller Fehlermeldungen in eine separate
  Fehlerdatei source.err.

Maerz 2004: Version 0.9
- Hinzugefuegt: Unterstuetzung fuer neue Typen ATmega48/88/168

Februar 2004: Version 0.8
- Korrigiert: Fehler beim Setzen des RAMEND-Symbols beseitigt
- Korrigiert: Falsche SRam-Angaben bei drei aelteren ATmega-Typen
- Korrigiert: Assembler startete nicht mit kurzen Fehlermeldungen
  als Voreinstellung, wenn keine Parameter angegeben wurden

Oktober 2003: Version 0.7
- Hinzugefuegt: Unterstuetzung fuer neuen Typ ATtiny2313
- Hinzugefuegt: Direktive .IFDEVICE fuer Verzweigungen abhaengig
  vom AVR-Typ
- Geaendert: Einstufung von ATtiny22 als zuverlaessig, da
  jetzt Datenblatt verfuegbar

September 2003: Version 0.6
- Korrigiert: Fehler bei der Verarbeitung negativer Zahlen in
  Funktionen behoben
- Korrigiert: Fehler bei der Verarbeitung von .DEVICE behoben
- Geaendert: Der Aufruf von def.inc-Dateien mit .INCLUDE bewirkt
  jetzt, dass die entsprechenden internen Symbol-Definitionen
  geladen werden und eine Warnung ausgegeben wird, die
  def.inc-Datei wird nicht verarbeitet
- Geaendert: Gesamten Instruktionsset ueberarbeitet
- Hinzugefuegt: Support fuer einige aeltere Typen, Warnung bei
  undokumentierten Typen
- Hinzugefuegt: Verschachtelte IF-Konstruktionen

August 2003: Version 0.5
- Korrigiert: LD/ST-Instruktion fuer AT90S1200 zulaessig, ergab
  Fehlermeldung!

Juli 2003: Version 0.4
- Korrigiert: Missverstaendliche Fehlermeldung bei der Verwendung
  undefinierter Registersymbole
- Hinzugefuegt: DEVICE-Direktive bindet alle Symbole des betref-
  fenden AVR-Typs ein und ersetzt die *def.inc-Dateien. Ausgabe
  einer Fehlermeldung beim INCLUDE von *def.inc-Dateien!
- Unterstuetzung fuer den neuen Typ ATtiny13.

Juni 2003: Version 0.3
- Korrigiert: Erkennung doppelter Marken korrigiert (ergab
  faelschlich internen Compiler-Fehler)
- Korrigiert: Konstantenausdruecke, die mit einer Klammer beginnen
  und enden, wurden nicht richtig erkannt. Daher Unterstuetzung
  fuer Makro-Aufrufe mit geklammerten Parametern entfernt!

Mai 2003: Version 0.2
- Hinzugefuegt: Export lokaler Makrosymbole nach global
  implementiert
- Wrap-Around bei relativen Verzweigungen/Spruengen implementiert,
  funktioniert bei allen Verzweigungsinstruktionen (RJMP, RCALL)
  und bei allen bedingten Branch-Instruktionen (Unterschied zu
  aelteren ATMEL-Assemblern!)
- Korrigiert: Mit Studio/Wavrasm kompatible Adressierung in der
  Hex-Datei (byte-orientiert, nicht wort-orientiert), funktioniert
  auch bei mehreren .ORG-Direktiven korrekt
- Korrigiert: Instruktionen LSL und LSR fuer Typ AT90S1200 gueltig,
  ergab Fehlermeldung in Version 0.1
- Korrigiert: Marken/Variable/Konstanten mit Unterstrich als erstem
  Zeichen werden jetzt akzeptiert
- Korrigiert: Doppelte Division x/y/z rechnete falsch!
- Korrigiert: Instruktionen in Spalte 1 werden nicht akzeptiert,
  missverstaendliche Fehlermeldung verbessert
- Korrigiert: Direktiven nach einer Marke in der gleichen Zeile
  werden ueberlesen und nicht ausgefuehrt, Fehlermeldung
  hinzugefuegt
- Hinzugefuegt: Kommandozeilenoption E fuer kurze (Default-Ein-
  stellung) oder laengere Fehlermeldungen

Dezember 2002: Version 0.1 Beta (Erstveroeffentlichung)


Nutzungsbedingungen
-------------------

- Copyright fuer alle Versionen:
  (C)2002/2003/2004/2005 by Gerhard Schmidt
- Nutzung des Quellcodes und der kompilierten Versionen fuer
  nichtkommerzielle Zwecke frei. Weiterverbreitung nur unter
  Beibehaltung der enthaltenen Copyright-Angaben zulaessig.
- Keine Garantie fuer korrekte Funktion der Software.
- Fehlermeldungen (mit Quellcode, allen Include-Dateien und
  Listfile) sowie Featurewuensche mit Betreff
  "gavrasm 1.2" bitte an gavrasm@avr-asm-tutorial.net.
