Inline-Assembler in avr-gcc

2011-07-20T09:45:19Z

Rdiez: Beispiel "Multiplikation 16x16 auf 32 von .S ins Inline-Assembler übersetzt" eingefügt.

In C versteht man unter '''Inline Assembler''' die Möglichkeit, direkt Assembler-Befehle in den Code einzufügen bzw. die eingefügten Assembler-Befehle selbst.

Neben den einzufügenden Befehlen muss beschrieben werden, welche Nebeneffekte die Befehle auf die Maschine haben und wo/wie Parameter übergeben werden, bzw. wie die Zuordnung von Variablen zu den Registern ist. Diese Beschreibung ist notwendig weil der [[Compiler]] keine Vorstellung davon hat, welche Effekte und Nebenwirkungen die Assembler-Kommandos auf Register, Variablen und Speicher haben, denn der Assembler-Schnippsel ist für den Compiler lediglich eine "Black Box".

Obgleich das dazu verwendete Schlüsselwort <tt>__asm</tt> zum ANSI-C-Standard gehört, ist dies in jedem C-Compiler anders implementiert. Das gilt insbesondere für die Schnittstellenbeschreibung Variablen/Register. Dieser Artikel bezieht sich auf den Inline Assembler von [[avr-gcc]].
Viele Erklärungen aus diesem Artikel sind auch gültig für Inline-Assembler anderer C-Compiler der [[gcc]]-Familie. Instruktionen und Registerklassen werden sich aber unterscheiden, weil diese natürlich abhängig sind vom verwendeten Controller bzw. der Controller-Familie.

=Assembler oder Inline-Assembler?=
;Assembler: Längere und komplexere Code-Stücke sind komfortabler direkt in Assembler auszudrücken. Dazu schreibt man Assembler-Funktionen und ruft diese von C aus auf. Natürlich können auch C-Funktionen von Assembler aus aufgerufen werden. Zudem kann man im Assembler den C-Präprozessor nutzen, was bei Inline-Assembler nur auf C-Ebene geht. Der Build-Prozess wird allerdings komplizierter, da extra asm-Dateien übersetzt werden müssen. Ein typischer Fall ist es, eine komplette ISR in Assembler zu schreiben.
;Inline-Assembler: Mit Inline-Assembler kann man kleine Assembler-Stückchen direkt in den C-Code einbetten. Es muss dann keine Assembler-Funktion aufgerufen werden. Dies kann von der Registerverwendung her deutlich günstiger sein, da [[gcc]] genau weiß, welche Register gebraucht werden und welche nicht.
:Eine (Assembler-)Funktion ist hingegen eine Black Box, bei der von der Standard-[[avr-gcc/Interna#Registerverwendung|Registerverwendung]] ausgegangen werden muss, auch wenn weniger Register in der Funktion verwendet werden. Ein Funktionsaufruf bedeutet also meistens einen Laufzeit-Overhead im Vergleich zu einem Inline-Code.
:Bei mehrfacher Verwendung einer längeren Codesequenz ist eine Funktion jedoch sparsamer im [[Flash]]-Verbrauch. Legt man eine Funktion als C-Funktion an und ihren Body als Inline-Assembler (eine s.g. Stub-Funktion, von engl. ''Stub'' = Stumpf), dann übernimmt gcc das Verwalten von Funktions-Argumenten, return-Wert, etc. und man brauch sich nicht selber um die Aufruf-Konvention zu kümmern. Auch innerhalb einer Funktion kann C mit Assembler gemischt werden.
:Ein Vorteil von Inline-Assembler ist, daß eine C-Funktion, die Inline-Assembler enthält, vom C-Compiler [[C-Tutorial#Inlining|geinlinet]] werden kann. Dies ist mit einer reinen Assembler-Funktion nicht möglich.

=Begriffe=
;Assembler-Template: Das Template (''Schablone'') ist ein statischer, konstanter String im Sinne von C. Es enthält die Assembler-Befehle sowie Platzhalter, in deren Stelle später die Operanden treten
;Constraint: Die Constraints (''Nebenbedingungen'') beschreiben Einschränkungen an die zu verwendeten Register. Dies ist notwendig, da nicht alle Maschinenbefehle auf alle Register anwendbar sind
;Clobber-List: Das ist eine Liste von Registern, deren Inhalt durch den Inline-Assembler zerstört wird

=Syntax und Semantik=
Das Schlüsselwort, um eine Inline-Assembler Sequenz einzuleiten, ist <tt>__asm</tt> (ANSI). Oft ist auch <tt>asm</tt> oder <tt>__asm__</tt> verwendbar. Um zu kennzeichnen, daß die Sequenz keinesfalls wegoptimiert werden darf – etwa dann, wenn der Assembler keine Wirkung auf C-Variablen hat – wird dem <tt>asm</tt> ein <tt>volatile</tt> bzw. <tt>__volatile</tt> nachgestellt. Danach folgen in runden Klammern die durch <tt>''':'''</tt> getrennten Abschnitte des Inline-Assemblers:
asm volatile ([[#Assembler-Template|asm-template]] : [[#Operanden und Constraints|output-operand-list]] : [[#Operanden und Constraints|input-operand-list]] : [[#Clobbers|clobber-list]]);

Abschnitte, die leer sind, können auch weggelassen werden, wenn dahinter kein weiterer Abschnitt folgt:
asm volatile (asm-template);

Oder, wenn weder Input- noch Output-Operanden gebraucht werden, aber Register oder Speicher verändert werden:
asm volatile (asm-template ::: clobber-list);

{{FarbigerRahmen |
Aus Compiler-Sicht werden die Assembler-Befehle im Template parallel, also ''gleichzeitig'' ausgeführt! Dies ist zu bedenken, wenn Register sowohl als Input als auch als Output verwendet werden.
}}

==Assembler-Template==

Im Template stehen die durch Zeilenumbrüche getrennten Assembler-Befehle. Das Template kann zudem <tt>%</tt>-Ausdrücke als Platzhalter enthalten, welche durch die Operanden ersetzt werden. Dabei bezieht sich <tt>%0</tt> auf den ersten Operanden, <tt>%1</tt> auf den zweiten Operanden, etc. Die Operanden selbst werden im zweiten und dritten Abschnitt des Templates als Komma-getrennte Liste angegeben.

Ein Platzhalter kann zusätzlich einen einbuchstabigen Modifier enthalten, um ein Register in einem speziellen Format darzustellen. Wird z.B. ein Wert ab Register <tt>r28</tt> (dem Y-Register) gehalten, dann wären folgende Ersetzungen denkbar (als erstes Argument):

:<tt>%0     →  r28</tt>

:<tt>%A0    →  r28</tt>

:<tt>%B0    →  r29</tt>

:<tt>%C0    →  r30</tt>

:<tt>%D0    →  r31</tt>

:<tt>%a0    →  y  </tt>

Im einfachsten Falle enthält das Templater nur einen Befehl:
"nop"
oder sogar garkeinen Befehl und lediglich einen Kommentar:
"; ein Kommentar"

:{| {{Blauetabelle}}
|+ '''Tabelle: asm-Platzhalter und ihre Modifier, Sonderzeichen'''
|- {{Hintergrund1}}
! Platzhalter || wird ersetzt durch
|-
|<tt>%''n''</tt> || Wird ersezt durch Argument <tt>''n''</tt> mit <tt>''n''</tt> = 0...9
|-
|<tt>%A''n''</tt> || das erste (untere) Register des Arguments <tt>''n''</tt> (Bits 0...7)
|-
|<tt>%B''n''</tt> || das zweite Register des Arguments <tt>''n''</tt> (Bits 8...15)
|-
|<tt>%C''n''</tt> || das dritte Register des Arguments <tt>''n''</tt> (Bits 16...23)
|-
|<tt>%D''n''</tt> || das vierte Register des Arguments <tt>''n''</tt> (Bits 24...31)
|-
|<tt>%a''n''</tt> || Ausgabe des Arguments als Adress-Register, also als <tt>x</tt>, <tt>y</tt> bzw. <tt>z</tt>. Erlaubt zusammen mit Constraint <tt>b</tt>, <tt>e</tt>, <tt>x</tt>, <tt>y</tt>, <tt>z</tt>
|-
|<tt>%~</tt> || wird auf AVR mit Flash bis max. 8kByte durch ein <tt>r</tt> ersetzt, ansonsten bleibt es leer. Zum Aufbau von Sprungbefehlen, etwa "<tt>%~call foo</tt>"
|-
|<tt>%=</tt> || eine für dieses asm-Template und die Übersetzungseinheit eindeutige Zahl. Zum Aufbau lokaler Sprungmarken.
|- {{Hintergrund1}}
! Sequenz || wird ersetzt durch Sonderzeichen
|-
|<tt>%%</tt> || das <tt>%</tt>-Zeichen selbst
|-
|<tt>\n</tt> || ein Zeilenumbruch zum Trennen mehrerer asm-Befehle/Zeilen
|-
|<tt>\t</tt> || ein TAB, zur Übersichtlichkeit im erzeugten asm
|-
|<tt>\"</tt> || ein <tt>"</tt> wird eingefügt
|-
|<tt>\\</tt> || das <tt>\</tt>-Zeichen selbst
|- {{Hintergrund1}}
! Kommentar || Beschreibung
|-
|<tt>; ''Text''</tt> || einzeiliger Kommentar bis zum Ende des Templates bzw. nächsten Zeilenumbruch
|-
|<tt>/* ''Text'' */</tt> || mehrzeiliger Kommentar wie in C
|}

==Operanden und Constraints==

Ein Operand besteht aus der Angabe des Constraint-Strings (also der Registerklasse und Kennzeichnung, ob es sich um einen Output-Operanden handelt) und dahinter in runden Klammern der C-Ausdruck, der in Register der angegebenen Klasse geladen werden soll. Die Operanden werden mit 0 beginnend von links nach rechts durchnumeriert und über diese Nummer angesprochen, um sie ins Assembler-Schnippsel einzufügen.

Mehrere Input- bzw. Output-Operanden werden durch Komma getrennt.

:{| {{Blauetabelle}}
|+ '''Tabelle: Constraints und ihre Bedeutung'''
|- {{Hintergrund1}}
! Constraint || Register || Wertebereich
|rowspan="14"| 
! Constraint || Konstante || Wertebereich
|-
|<tt>a</tt>||einfache obere Register||<tt>r16</tt>...<tt>r23</tt>
|<tt>G</tt>||Floatingpoint-Konstante ||<tt>0.0</tt>
|-
|<tt>b</tt>||Pointer-Register ||<tt>y</tt>, <tt>z</tt>
|<tt>i</tt>||Konstante || 
|-
|<tt>d</tt>||obere Register ||<tt>r16</tt>...<tt>r31</tt>
|<tt>I</tt>||positive 6-Bit-Konstante ||0...63
|-
|<tt>e</tt>||Pointer-Register ||<tt>x</tt>, <tt>y</tt>, <tt>z</tt>
|<tt>J</tt>||negative 6-Bit Konstante ||<tt>-</tt>63...0
|-
|<tt>l</tt>||untere Register ||<tt>r0</tt>...<tt>r15</tt>
|<tt>M</tt>||8-Bit Konstante ||0...255
|-
|<tt>q</tt>||Stack-Pointer ||<tt>SPH:SPL</tt>
|colspan="3" | 
|-
|<tt>r</tt>||ein Register ||<tt>r0</tt>...<tt>r31</tt>
!{{Hintergrund1}}| Constraint ||{{Hintergrund1}}| Memory ||{{Hintergrund1}}| Wertebereich
|-
|<tt>t</tt>||Scratch-Register ||<tt>r0</tt>
|<tt>m</tt>|| Memory ||  
|-
|<tt>w</tt>||obere Register-Paare ||<tt>r24</tt>, <tt>r26</tt>, <tt>r28</tt>, <tt>r30</tt>
|colspan="3" rowspan="5"| 
|-
|<tt>x</tt>||Pointer-Register X ||<tt>x</tt> (<tt>r27:r26</tt>)
|-
|<tt>y</tt>||Pointer-Register Y ||<tt>y</tt> (<tt>r29:r28</tt>)
|-
|<tt>z</tt>||Pointer-Register Z ||<tt>z</tt> (<tt>r31:r30</tt>)
|-
|<tt>0</tt>...<tt>9</tt>||colspan="2"|Identisch mit dem angegebenen Operanden Wird verwendet, wenn ein Operand sowohl als Input als auch als Output dient, um sich auf diesen Operanden zu beziehen
|}

:{| {{Blauetabelle}}
|+ '''Tabelle: Constraint Modifier'''
|- {{Hintergrund1}}
!Modifier || Bedeutung
|-
|<tt>=</tt> || der Operand ist Output-Operand
|-
|<tt>&</tt> || diesen Operanden ''nicht'' als Input-Operanden verwenden, sondern nur als Output-Operand
|-
|<tt>+</tt> || dieser Operanden ist Input- und Output-Operand
|}

Ein Input-Operand könnte also so aussehen, wobei <tt>foo</tt> eine C-Variable ist. Als Register dient ein (je nach Typ von <tt>foo</tt> auch mehrere) obere Register, irgendwo von <tt>r16</tt> bis <tt>r31</tt> (Constraint <tt>"d"</tt>):
"d" (foo)

In den Klammern kann ein beliebiger, gültiger C-Ausdruck stehen, der beim folgenden Beispiel in irgendeinem Register landet (Constraint <tt>"r"</tt>), ohne weitere Einschränkung an das Register:
"r" ((foo >= 0) ? foo : -foo)

Um einen Operanden als Output-Operanden zu kennzeichnen, wird dem Constraint ein <tt>"="</tt> vorangestellt.
Soll <tt>foo</tt> ein Output-Operand sein, der in den Registern <tt>r0</tt>...<tt>r15</tt> landen soll (Constraint <tt>"l"</tt>, sieht es so aus. Dabei muss <tt>foo</tt> ein sogenannter Lvalue sein, also ein Wert, dem etwas zugewiesen werden kann:
"=l" (foo)

Ist <tt>foo</tt> sowohl Input als auch Output, schreibt man <tt>foo</tt> als Output- und als Input-Operand hin. In der Input-Constraint bezieht man sich dann auf die Operanden-Nummer von <tt>foo</tt>. Hier ein komplettes Beispiel, das die Nibbles von <tt>foo</tt> tauscht. Weil <tt>swap</tt> auf alle Register anwendbar ist, kann als Registerklasse <tt>"r"</tt> genommen werden:
<pre>
unsigned char foo;
...
asm volatile ("swap %0" : "=r" (foo) : "0" (foo));
</pre>
<tt>foo</tt> als Input-Operand soll im gleichen Register liegen wie <tt>foo</tt> als Output-Operand. Daher wird als Constraint <tt>"0"</tt> angegeben, d.h. es wird ins gleiche Register geladen wie der Operand Numero 0 <tt>"r" (foo)</tt>.

=== Benannte Constraints ===

Um das Assembler-Schnippsel besser lesbar zu halten, kann man Constraints einen Namen geben:
asm volatile ("swap %[bar]" : [bar] "+r" (foo));
Damit ist der Assembler auch unabhängig von der Reihenfolge der Operanden. Das macht die Anpassung, wenn ein neuer Operand hinzukommt, wesentlich einfacher und den Schnippsel zudem besser lesbar.

Hier wird <tt>bar</tt> als Alias für die C-Variable <tt>foo</tt> benutzt; es könnte aber auch jeder andere gültige C-Bezeichner sein, also insbesondere auch <tt>foo</tt>.

===Instruktionen und Constraints===
Die folgende Tabelle enhält eine Auflistung von AVR-Instruktionen und dazu passende Argumente bzw. Constraints. Nicht alle Shorthands sind in der Tabelle enthalten, so ist "<tt>clr Rn</tt>" nur eine Abkürzung für "<tt>eor Rn, Rn</tt>", ähnliches gilt für den Zoo von Instruktionen rund um das SREG wie branch, bit set, bit clear, etc., die im Endeffekt auf nur vier Instruktionen abbilden. Instruktionen wie <tt>nop</tt>, die keine Argumente brauchen, sind ebenfalls nicht in der Tabelle enthalten.

<tt>"load"</tt> ist ein <tt>"load from SRAM"</tt> 
<tt>"store"</tt> ist <tt>"store to SRAM"</tt> 

:{| {{Blauetabelle}}
|+'''Tabelle: Übersicht AVR-Instruktionen und passende Constraints'''
|- {{Hintergrund1}}
!Mnemonic || Constraint ||Bedeutung ||rowspan="32"| 
!Mnemonic || Constraint ||Bedeutung
|-
| <tt>adc</tt>||<tt>r,r</tt> || add with carry
| <tt>add</tt>||<tt>r,r</tt> || add
|-
| <tt>adiw</tt>||<tt>w,I</tt> || add immediate to word
| <tt>and</tt>||<tt>r,r</tt> || and
|-
| <tt>andi</tt>||<tt>d,M</tt> || and with immediate
| <tt>asr</tt>||<tt>r</tt> || arithmetic shift right
|-
| <tt>bclr</tt>||<tt>I</tt> || bit clear in SREG
| <tt>bld</tt>||<tt>r,I</tt> || bit load from T
|-
| <tt>brbc</tt>||<tt>I,label</tt> || branch if bit in SREG clear
| <tt>brbs</tt>||<tt>I,label</tt> || branch if bit in SREG set
|-
| <tt>bset</tt>||<tt>I</tt> || bit set in SREG
| <tt>bst</tt>||<tt>r,I</tt> || bit store from T
|-
| <tt>cbi</tt>||<tt>I,I</tt> || clear bit in I/O
| <tt>com</tt>||<tt>r</tt> || complement
|-
| <tt>cp</tt>||<tt>r,r</tt> || compare
| <tt>cpc</tt>||<tt>r,r</tt> || compare with carry
|-
| <tt>cpi</tt>||<tt>d,M</tt> || compare against immediate
| <tt>cpse</tt>||<tt>r,r</tt>|| compare, skip if equal
|-
| <tt>dec</tt>||<tt>r</tt> || decrement
| <tt>elpm</tt>||<tt>t,z</tt>|| extern: load from prog mem
|-
| <tt>eor</tt>||<tt>r,r</tt> || exclusive-or
| <tt>fmul*</tt>||<tt>a,a</tt> || fractional multiply
|-
| <tt>in</tt>||<tt>r,I</tt> || input from I/O
| <tt>inc</tt>||<tt>r</tt> || increment
|-
| <tt>ld</tt>||<tt>r,e</tt> || load indirect
| <tt>ld</tt>||<tt>r,e+</tt> || load indirect, post-increment
|-
| <tt>ld</tt>||<tt>r,-e</tt> || load indirect, pre-decrement
| <tt>ldd</tt>||<tt>r,b+I</tt> || load indirect with displacement
|-
| <tt>ldi</tt>||<tt>d,M</tt> || load immediate
| <tt>lds</tt>||<tt>r,label</tt> || load direct from SRAM
|-
| <tt>lpm</tt>||<tt>t,z</tt> || load from prog mem
| <tt>lsr</tt>||<tt>r</tt> || logical shift right
|-
| <tt>mov</tt>||<tt>r,r</tt> || move
| <tt>movw</tt>||<tt>r,r</tt> || move word
|-
| <tt>mul</tt>||<tt>r,r</tt> || multiply unsigned
| <tt>muls</tt>||<tt>d,d</tt> || multiply signed
|-
| <tt>mulsu</tt>||<tt>a,a</tt> || multiply signed/unsigned
|colspan="3"|  
|-
| <tt>neg</tt>||<tt>r</tt> || negate
| <tt>or</tt>||<tt>r,r</tt> || or
|-
| <tt>ori</tt>||<tt>d,M</tt> || or with immediate
| <tt>out</tt>||<tt>I,r</tt> || output to I/O
|-
| <tt>pop</tt>||<tt>r</tt> || pop from Stack
| <tt>push</tt>||<tt>r</tt> || push to Stack
|-
| <tt>ror</tt>||<tt>r</tt> || rotate right
|colspan="3"|  
|-
| <tt>sbc</tt>||<tt>r,r</tt> || subtract with carry
| <tt>sbci</tt>||<tt>d,M</tt> || subtract with carry immediate
|-
| <tt>sbic</tt>||<tt>I,I</tt> || skip if bit in I/O clear
| <tt>sbis</tt>||<tt>I,I</tt> || skip if bit in I/O set
|-
| <tt>sbi</tt>||<tt>I,I</tt> || set Bit in I/O
| <tt>sbiw</tt>||<tt>w,I</tt> || subtract immediate from word
|-
| <tt>sbrc</tt>||<tt>r,I</tt> || skip if bit in register clear
| <tt>sbrs</tt>||<tt>r,I</tt> || skip if bit in register set
|-
| <tt>st</tt>||<tt>e,r</tt> || store indirect
| <tt>st</tt>||<tt>e+,r</tt> || store indirect, post-increment
|-
| <tt>st</tt>||<tt>-e,r</tt> || store indirect, pre-decrement
| <tt>std</tt>||<tt>b,r</tt> || store indirect with displacement
|-
| <tt>sts</tt>||<tt>label,r</tt> || store direct
| <tt>sub</tt>||<tt>r,r</tt> || subtract
|-
| <tt>subi</tt>||<tt>d,M</tt> || subtract immediate
| <tt>swap</tt>||<tt>r</tt> || swap nibbles

|}

Hier noch ein paar der gebräuchlichsten Shorthands und deren Abbildung auf "Basis"-Instruktionen:

:{| {{Blauetabelle}}
|+'''Tabelle: Shorthands'''
|- {{Hintergrund1}}
!Shorthand || gleichbedeutend mit || Bedeutung ||rowspan="5"| 
!Shorthand || gleichbedeutend mit || Bedeutung
|-
| <tt>asl r</tt> || <tt>addc r,r</tt> || arithmetic shift left
| <tt>cbr r,M</tt> || <tt>andi r, ~M</tt> || clear bits in reg
|-
| <tt>clr r</tt> || <tt>eor r,r</tt> || clear reg to zero
| <tt>lsl r</tt> || <tt>add r,r</tt> || logical shift left
|-
| <tt>sbr d,M</tt> || <tt>ori d, M</tt> || set bits in reg
| <tt>ser d</tt> || <tt>ldi d, 0xff</tt> || set all bits in reg
|-
| <tt>tst r</tt> || <tt>and r,r</tt> || test against zero
|colspan="3"| 
|}

==Clobbers==

In der Komma-getrennten Clobber-Liste kann man angeben, welche Register durch den Inline-Assembler ihren Wert ändern. Ändern z.B. <tt>r2</tt> und <tt>r3</tt> ihre Werte, dann ist die Clobber-Liste
"r2", "r3"

Wird schreibend auf das RAM zugegriffen, dann muss man das auch mitteilen, damit RAM-Inhalte, die sich evtl. in Registern befinden, nach dem Inline-Assembler neu gelesen werden. Der Clobber dafür ist:
"memory"

'''Beispiel:'''

Es soll ein Inline-Assembler geschrieben werden, das den Inhalt zweier aufeinanderfolgender Speicherstellen austauscht. Die Adresse soll in <tt>addr</tt> stehen. Sie ist Input-Operand und muss in Register X, Y oder Z stehen, um den <tt>ld</tt> bzw. <tt>st</tt>-Befehl anwenden zu können. Die passende Constraint ist also <tt>"e"</tt>. Nach der Sequenz liegt <tt>addr</tt> unverändert vor.
<pre>
asm volatile (
"ld r2, %a0+" "\n\t"
"ld r3, %a0" "\n\t"
"st %a0, r2" "\n\t"
"st -%a0, r3"
: /* keine Output-Operanden */
: "e" (addr)
: "r2", "r3", "memory"
);
</pre>
avr-gcc entscheidet sich dazu, das Z-Register für <tt>addr</tt> zu verwenden:
<pre>
ld r2, Z+
ld r3, Z
st Z, r2
st -Z, r3
</pre>

Günstiger ist es jedoch, dem Compiler auch die Entscheidung zu überlassen, welche(s) Register als Hilfsregister verwendet werden sollen. Ein Register kann <tt>__tmp_reg__</tt> sein, für das zweite legen wir eine lokale 8-Bit-Variable <tt>hilf</tt> an:
<pre>
{
char hilf;

asm volatile (
"ld __tmp_reg__, %a1+" "\n\t"
"ld %0, %a1" "\n\t"
"st %a1, __tmp_reg__" "\n\t"
"st -%a1, %0"
: "=&r" (hilf)
: "e" (addr)
: "memory"
);
}
</pre>
<tt>__tmp_reg__</tt> (also <tt>r0</tt>) brauch nicht in die Clobber-Liste aufgenommen zu werden. Um das zweite benötigte Register (hier <tt>r24</tt>, in dem <tt>hilf</tt> lebt) kümmert sich avr-gcc und sichert es, falls nötig
<pre>
ld r0, Z+
ld r24, Z
st Z, r0
st -Z, r24
</pre>

{{FarbigerRahmen |
Falls das Register <tt>r1</tt> verändert wird – was z.B. geschieht, wenn man Multiplikationsbefehle verwendet – dann muss am Ende des Templates das Register wieder auf 0 gesetzt werden, denn bei avr-gcc enthält dieses Register immer den Wert 0.
Das Register in die Clobber-Liste aufzunehen bleibt wirkungslos. Hat man es zerstört,
dann schreibt man ans Ende des Templates ein
clr __zero_reg__
und stellt es dadurch wieder her.
}}

=Vordefinierte Bezeichner und Makros=
Je nach Assembler, für den avr-gcc Code erzeugt, gibt es unterschiedliche vordefinierte Funktionen/Makros, die von Inline-Assembler aus verwendbar sind.

== GNU-Assembler ==

:{| {{Blauetabelle}}
|+ '''Tabelle: vordefinierte Bezeichner/Makros
|- {{Hintergrund1}}
! Bezeichner || Bedeutung
|-
|<tt>__SP_L__</tt> || unteres Byte des Stack-Pointers, für <tt>in</tt> bzw. <tt>out</tt>
|-
|<tt>__SP_H__</tt> || oberes Byte des Stack-Pointers, für <tt>in</tt> bzw. <tt>out</tt>
|-
|<tt>__SREG__</tt> || Status-Register, für <tt>in</tt> bzw. <tt>out</tt>
|-
|<tt>__tmp_reg__</tt> || ein Register zur temporären Verwendung (<tt>r0</tt>)
|-
|<tt>__zero_reg__</tt> || ein Register, das 0 enthält (<tt>r1</tt>)
|-
|<tt>lo8(''const'')</tt> || die unteren 8 Bit der Konstanten <tt>''const''</tt>
|-
|<tt>hi8(''const'')</tt> || Bits 8...15 der Konstanten <tt>''const''</tt>
|-
|<tt>hlo8(''const'')</tt> || Bits 16...23 der Konstanten <tt>''const''</tt>
|-
|<tt>hhi8(''const'')</tt> || Bits 24...31 der Konstanten <tt>''const''</tt>
|-
|<tt>pm(''const'')</tt> || Konstante <tt>''const''</tt> durch 2 geteilt, zur Berechnung von Flash-Adressen für <tt>icall</tt>, <tt>lpm</tt> etc.
|}

=Beispiele=

==nop==
Mit den bisherigen Vorkenntnissen ist zu <tt>nop</tt> nicht viel zu sagen:
asm volatile ("nop");
Oder als C-Makro:
#define nop() \
asm volatile ("nop")

<tt>nop</tt> hat weder Input- noch Output-Operanden, und Register/RAM ändern sich natürlich nicht. Bei der Makro-Definition ist lediglich darauf zu achten, daß das Makro nicht mit einem <tt>;</tt> endet, damit man den C-Code wie gewohnt mit <tt>;</tt> schreiben kann:
<pre>
if (x)
nop();
else
...
</pre>

==swap Nibbles==
Ein einfaches Beispiel für <tt>swap</tt> haben wir bereits oben kennen gelernt. Der Inline-Assembler dreht die Nibbles von <tt>foo</tt> um:
<pre>
unsigned char foo;
...
asm volatile ("swap %0" : "=r" (foo) : "0" (foo));
</pre>

Wünschenswert wäre eher, <tt>swap</tt> wie eine normale C-Funktion verwenden zu können und hinzuschreiben:
a = swap(b);
ohne daß <tt>b</tt> seinen Wert ändert. Soll <tt>b</tt> geswappt werden, dann via
b = swap(b);
zudem soll das Argument ein Ausdruck sein können:
if (b == swap (b+1))
...

Dazu verwenden wir eine lokale Variable <tt>__x__</tt>, in die der ursprüngliche Wert <tt>x</tt> gesichert wird:
<pre>
#define swap(x) \
({ \
unsigned char __x__ = (unsigned char) x; \
asm volatile ("swap %0" : "=r" (__x__) : "0" (__x__)); \
__x__; \
})
</pre>
alternativ könnten wir eine inline-Funktion definieren:
<pre>
static inline unsigned char swap (unsigned char x)
{
asm volatile ("swap %0" : "=r" (x) : "0" (x));
return x;
}
</pre>

==swap Bytes==
Werden Zahlen zwischen verschiedenen Plattformen übertragen, kann es sein, daß diese unterschiedlich dargestellt werden: Das low-Byte kann in sich im unteren Byte befinden (AVR), es kann aber auch im oberen Byte sein. Ist das so, dann müssen die Werte beim Senden/Empfang umgewandelt werden, indem die Bytes getauscht werden. Liegt der 16-Bit-Wert in <tt>x_in</tt> und soll der konvertierte Wert nach <tt>x_out</tt> gespeichert werden, dann könnte man auf die Idee kommen, so etwas zu schreiben:
<pre>
asm volatile (
"mov %A0, %B1" "\n\t"
"mov %B0, %A1"
: "=r" (x_out)
: "r" (x_in)
);
</pre>
Daraus könnte folgender Code entstehen:
<pre>
mov r24, r25
mov r25, r24
</pre>
Das ist offenbar Käse! Was ist passiert?

avr-gcc hat sich dazu entschieden, <tt>x_in</tt> in <tt>r25:r24</tt> anzulegen. Auch <tt>x_out</tt> wird in diesen Registern angelegt. Das ist erst mal in Ordnung, wenn <tt>x_in</tt> nach dem Inline nicht mehr gebraucht wird.

Allerdings wird das Inline nicht en bloc — also nicht zeitparallel — ausgeführt, sondern sequenziell. Bei ''gleichzeitiger'' Ausführung der beiden <tt>mov</tt>-Instruktionen wäre auch nichts dagegen zu sagen! Ein <tt>swap</tt>-Kommando z.B. tauscht die Nibbles ''gleichzeitig'', und der Input-Operand kann im gleichen Register leben wie der Output-Operand, wenn der Input nicht weiter verwendet wird.

Mit den beiden Bytes geht es aber nicht. Wir müssen daher kennzeichnen, daß sich <tt>x_out</tt> in einem Register befindet, das ''nur'' als Output dient, was durch das <tt>&</tt> in der Output-Constraint erreicht wird:
<pre>
asm volatile (
"mov %A0, %B1" "\n\t"
"mov %B0, %A1"
: "=&r" (x_out)
: "r" (x_in)
);
</pre>
Damit erfolgt eine korrekte Registerzuordnung. <tt>x_out</tt> steht jetzt in <tt>r19:r18</tt> und überschneidet nich nicht mehr mit <tt>x_in</tt>:
<pre>
mov r18, r25
mov r19, r24
</pre>

Alternativ können wir wie bei [[#swap Nibbles|swap Nibbles]] eine lokale Variable verwenden, und alles als (inline-)Funktion machen. In dem folgenden Beispiel wird ein etwas anderer Code zum Tauschen verwendet:
<pre>
static inline unsigned short swap_16 (unsigned short x_in)
{
asm volatile (
"eor %A0, %B0" "\n\t"
"eor %B0, %A0" "\n\t"
"eor %A0, %B0"
: "=r" (x_in)
: "0" (x_in)
);

return x_in;
}
</pre>
Die <tt>eor</tt>-Sequenz tauscht die Inhalte von <tt>r24</tt> und <tt>r25</tt>. Sie ist genauso schnell und knapp wie ein "Dreiecks-Tausch", kommt aber ohne Hilfsregister aus. Nachrechnen, es stimmt!
<pre>
eor r24, r25
eor r25, r24
eor r24, r25
</pre>

== Multiplikation 16x16 auf 32 von .S ins Inline-Assembler übersetzt ==

Das ist die ursprüngliche Routine mul16x16_32 from Atmel's avr201.asm file, see also Atmel's document "AVR201: Using the AVR Hardware Multiplier":

<pre>
;******************************************************************************
;*
;* FUNCTION
;* mul16x16_32
;* DECRIPTION
;* Unsigned multiply of two 16bits numbers with 32bits result.
;* USAGE
;* r19:r18:r17:r16 = r23:r22 * r21:r20
;* STATISTICS
;* Cycles : 17 + ret
;* Words : 13 + ret
;* Register usage: r0 to r2 and r16 to r23 (11 registers)
;* NOTE
;* Full orthogonality i.e. any register pair can be used as long as
;* the 32bit result and the two operands does not share register pairs.
;* The routine is non-destructive to the operands.
;*
;******************************************************************************

mul16x16_32:
clr r2
mul r23, r21 ; ah * bh
movw r19:r18, r1:r0
mul r22, r20 ; al * bl
movw r17:r16, r1:r0
mul r23, r20 ; ah * bl
add r17, r0
adc r18, r1
adc r19, r2
mul r21, r22 ; bh * al
add r17, r0
adc r18, r1
adc r19, r2
ret
</pre>

Das ist hier eine Übersetzung für den avr-gcc. Der größte Vorteil besteht darin, dass der avr-gcc die Benutzung von den Registern an den umliegenden C Code anpassen kann. Daher müssen gegebenenfalls keine Register umkopiert werden, um diese Routine aufzurufen:

<pre>
static __inline__ uint32_t mul_unsigned_16x16_32 ( const uint16_t operand_1, const uint16_t operand_2 )
{
uint32_t return_value;

asm // No "asm volatile", so that the compiler can optimize the whole lot away
( // if the result is not used.

// The code here is based on routine mul16x16_32 from Atmel's avr201.asm file,
// see also Atmel's document "AVR201: Using the AVR Hardware Multiplier".

"clr r2 ; r1/__zero_reg__ gets clobbered by mul, and we need \n\t" \
" ; some register to hold a zero value later, see below. \n\t" \
" \n\t" \
"mul %B[operand_1], %B[operand_2] ; high(operand_1) * high(operand_2) \n\t" \
"movw %C[return_value], r0 ; 16-bit move: r1:r0 -> rD+1:rD \n\t" \
" \n\t" \
"mul %A[operand_1], %A[operand_2] ; low(operand_1) * low(operand_2) \n\t" \
"movw %A[return_value], r0 ; 16-bit move: r1:r0 -> rD+1:rD \n\t" \
" \n\t" \
"mul %B[operand_1], %A[operand_2] ; high(operand_1) * low(operand_2) \n\t" \
"add %B[return_value], r0 \n\t" \
"adc %C[return_value], r1 \n\t" \
"adc %D[return_value], r2 \n\t" \
" \n\t" \
"mul %B[operand_2], %A[operand_1] ; high(operand_2) * low(operand_1) \n\t" \
"add %B[return_value], r0 \n\t" \
"adc %C[return_value], r1 \n\t" \
"adc %D[return_value], r2 \n\t" \
" \n\t" \
"clr __zero_reg__ ; r1/__zero_reg__ gets clobbered by mul \n\t"

: [return_value] "=&r" (return_value) // output operands
: [operand_1] "r" (operand_1), [operand_2] "r" (operand_2) // input operands
: "r2" // clobbered registers ("r1/__zero_reg__" here would have no effect)
);

return return_value;
}
</pre>

== Zugriff auf SFRs ==
Um auf SFRs zuzugreifen, können im asm-Template keine Defines aus <tt>avr/io.h</tt> verwendet werden, weil der Präprozessor nicht mehr über den erzeugten Assembler-Code läuft (er läuft vor dem Compilieren). Um nicht die hex-Codes des SFRs angeben zu müssen, kann man dem Inline die Adressen als Konstanten übergeben. Weil die Adressen RAM-Adressen sind, müssen sie in das <tt>_SFR_IO_ADDR</tt> Makro verpackt werden, um den Offset für den I/O-Bereich abzuziehen. <tt>tcnt1</tt> wird auf den Inhalt von <tt>TCNT1</tt> gesetzt:
<pre>
#include <avr/io.h>
...
uint16_t tcnt1;

asm volatile (
"in %A0, %1" "\n\t"
"in %B0, %1+1"
: "=r" (tcnt1)
: "M" (_SFR_IO_ADDR (TCNT1))
);
</pre>
wird umgesetzt zu
<pre>
in r24, 44
in r25, 44+1
</pre>
Das nur als Beispiel. Von C aus geht das natürlich auch mit
uint16_t tcnt1 = TCNT1;

== Zugriff aufs SRAM ==
Auf bekannte globale Symbole kann man direkt von Assembler aus zugreifen:
<pre>
extern int einInt;

asm volatile (
"lds %A0, einInt" "\n\t"
"lds %B0, einInt+1"
: "=r" (...)
);
</pre>
ergibt
<pre>
lds r24, einInt
lds r25, einInt+1
</pre>
alternativ ginge
<pre>
asm volatile (
"lds %A0, %A1" "\n\t"
"lds %B0, %B1"
: "=r" (...)
: "m" (einInt)
);
</pre>

Falls die Adresse eines Objekts zur Compilezeit bekannt ist, kann man auch die Adresse von C aus übergeben:
<pre>
struct foo_t {
int a[2], b[2];
} foo;

...
{
asm volatile (
"lds %A0, %1" "\n\t"
"lds %B0, %1+1"
: "=r" (...)
: "i" (& foo.b[1])
);
}
</pre>
ergibt
<pre>
lds r24, einStruct+6
lds r25, einStruct+6+1
</pre>

Falls die Adresse zur Compilezeit nicht bekannt ist, muss sie natürlich in einem Adress- oder Basisregister übergeben werden:
<pre>
void blah (struct foo_t * pfoo)
{
asm volatile (
"ld %A0, %a1" "\n\t"
"ldd %B0, %a1+1"
: "=&r" (...)
: "b" (& pfoo->b[1])
);
}
</pre>
ergibt
<pre>
ld r24, Z
ldd r25, Z+1
</pre>
Auch hier muss der Output-Operand mit einem <tt>&</tt> gekennzeichnet werden, damit er nicht ins gleiche Register geladen wird wie die Adresse.

= Labels und Schleifen =
Für Labels in Sprüngen und Schleifen können keine festen Bezeichner verwendet werden, weil ein Label, der via Makro oder inline-Funktion in den Code eingefügt wird, nicht mehrfach vorkommen darf. Dazu kann man sich durch Einfügen von <tt>"%="</tt> Labels zusammenbauen, etwa <tt>L_a%=</tt>, <tt>L_b%=</tt>, etc. Das <tt>"%="</tt> wird durch eine für die Übersetzungseinheit und den Code-Schnippsel eindeutige Zahl ersetzt. Die obigen Sequenzen könnten also z.B. umgesetzt werden als <tt>L_a14</tt> und <tt>L_b14</tt>, wenn sie im gleichen Schnippsel stehen.

Etwas bequemer ist die Verwendung einer Ziffer als Label. Beim Sprung gibt man direkt hinter der Ziffer an, in welche Richtung das Label gesucht wird. Ist das Label <tt>''n''</tt>, dann sucht und springt
*<tt>''n''b</tt> zurück (backward)
*<tt>''n''f</tt> nach vorne (forward)

Es wird zum nächsten auffindbaren Label in der angegebenen Richtung gesprungen.

==Bits zählen==

Dieses Assembler-Schnippsel zählt die Anzahl der gesetzten Bits in einem Byte <tt>eingabe</tt>. Die Eingabe wird nach rechts ins Carry geschoben, und das Carry zum Ergebnis dazu addiert.
<pre>
static inline unsigned char count_bits (unsigned char eingabe)
{
unsigned char count;

asm volatile (
"clr %0" "\n"
"0:" "\n\t"
"lsr %1" "\n\t"
"adc %0, __zero_reg__" "\n\t"
"tst %1" "\n\t"
"brne 0b"
: "=&r" (count), "+r" (eingabe)
);

return count;
}
</pre>
Damit kann man sich ein Parity bauen:
#define parity(x) (count_bits(x) & 1)
und hätte eine schlankere (aber etwas langsamere) Parity-Implementierung als in <tt>avr/parity.h</tt>. Ein
if (parity(foo))
...
wird in Assembler dann zu (<tt>r24 = eingabe</tt>, <tt>r25 = count</tt>):
<pre>
lds r24,foo
/* #APP */
clr r25
0:
lsr r24
adc r25, __zero_reg__
tst r24
brne 0b
/* #NOAPP */
sbrs r25,0
rjmp .L1
...
</pre>

=Bugs=
* Um die Sonderzeichen <tt>"%~"</tt> und <tt>"%="</tt> benutzen zu können, muss bei parameterlosen Inline Assembler dem Template ein Doppelpunkt folgen:
:<pre>asm volatile ("%~call some_function" :);</pre>

=Quellen=
* Doku zur avr-libc
* Doku zu avr-gcc
* Quellen von gcc

=Siehe auch=
* [[AVR Assembler Einführung]]
* [[:Kategorie:Quellcode Assembler_AVR|Quellcode Assembler]]
* [[Sourcevergleich#GCC (Assembler einfügen)]]
* [[avr-gcc]]

[[Kategorie:Microcontroller]]
[[Kategorie:Software]]
[[Kategorie:Grundlagen]]
[[Kategorie:Quellcode_Assembler_AVR]]
[[Kategorie:Quellcode C]]

RN-Wissen.de - Benutzerbeiträge [de]

Inline-Assembler in avr-gcc