You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
503 lines
43 KiB
HTML
503 lines
43 KiB
HTML
<!-- HTML header for doxygen 1.8.7-->
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.6.3"/>
|
|
<!--BEGIN PROJECT_NAME--><title>avr-libc: avr-libc: Inline Assembler Cookbook</title><!--END PROJECT_NAME-->
|
|
<!--BEGIN !PROJECT_NAME--><title>avr-libc: Inline Assembler Cookbook</title><!--END !PROJECT_NAME-->
|
|
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="$relpath^jquery.js"></script>
|
|
<script type="text/javascript" src="$relpath^dynsections.js"></script>
|
|
$treeview
|
|
$search
|
|
$mathjax
|
|
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
|
|
$extrastylesheet
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
|
|
<!--BEGIN TITLEAREA-->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<!--BEGIN PROJECT_LOGO-->
|
|
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
|
|
<!--END PROJECT_LOGO-->
|
|
<!--BEGIN PROJECT_NAME-->
|
|
<td style="padding-left: 0.5em;">
|
|
<div id="projectname">avr-libc
|
|
<!--BEGIN PROJECT_NUMBER--> <span id="projectnumber">2.0.0</span><!--END PROJECT_NUMBER-->
|
|
</div>
|
|
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
|
|
</td>
|
|
<!--END PROJECT_NAME-->
|
|
<!--BEGIN !PROJECT_NAME-->
|
|
<!--BEGIN PROJECT_BRIEF-->
|
|
<td style="padding-left: 0.5em;">
|
|
<div id="projectbrief">$projectbrief</div>
|
|
</td>
|
|
<!--END PROJECT_BRIEF-->
|
|
<!--END !PROJECT_NAME-->
|
|
<!--BEGIN DISABLE_INDEX-->
|
|
<!--BEGIN SEARCHENGINE-->
|
|
<td>$searchbox</td>
|
|
<!--END SEARCHENGINE-->
|
|
<!--END DISABLE_INDEX-->
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<table>
|
|
<tr>
|
|
<td align="left"><a href="http://www.nongnu.org/avr-libc/"><h2>AVR Libc Home Page</h2></a></td>
|
|
<td align="center" colspan=4><img src="avrs.png" alt="AVRs" align="middle" border="0"></td>
|
|
<td align="right"><a href="https://savannah.nongnu.org/projects/avr-libc/"><h2>AVR Libc Development Pages</h2></a></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="20%"><a href="index.html"><h2>Main Page</h2></a></td>
|
|
<td align="center" width="20%"><a href="pages.html"><h2>User Manual</h2></a></td>
|
|
<td align="center" width="20%"><a href="modules.html"><h2>Library Reference</h2></a></td>
|
|
<td align="center" width="20%"><a href="FAQ.html"><h2>FAQ</h2></a></td>
|
|
<td align="center" width="20%"><a href="group__demos.html"><h2>Example Projects</h2></a></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<!--END TITLEAREA-->
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.6.3 -->
|
|
<script type="text/javascript"><!--
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
--></script>
|
|
<div class="contents">
|
|
|
|
|
|
<h1><a class="anchor" id="inline_asm">Inline Assembler Cookbook </a></h1><p>AVR-GCC<br/>
|
|
Inline Assembler Cookbook</p>
|
|
<p>About this Document</p>
|
|
<p>The GNU C compiler for Atmel AVR RISC processors offers, to embed assembly language code into C programs. This cool feature may be used for manually optimizing time critical parts of the software or to use specific processor instruction, which are not available in the C language.</p>
|
|
<p>Because of a lack of documentation, especially for the AVR version of the compiler, it may take some time to figure out the implementation details by studying the compiler and assembler source code. There are also a few sample programs available in the net. Hopefully this document will help to increase their number.</p>
|
|
<p>It's assumed, that you are familiar with writing AVR assembler programs, because this is not an AVR assembler programming tutorial. It's not a C language tutorial either.</p>
|
|
<p>Note that this document does not cover file written completely in assembler language, refer to <a class="el" href="assembler.html">avr-libc and assembler programs</a> for this.</p>
|
|
<p>Copyright (C) 2001-2002 by egnite Software GmbH</p>
|
|
<p>Permission is granted to copy and distribute verbatim copies of this manual provided that the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.</p>
|
|
<p>This document describes version 3.3 of the compiler. There may be some parts, which hadn't been completely understood by the author himself and not all samples had been tested so far. Because the author is German and not familiar with the English language, there are definitely some typos and syntax errors in the text. As a programmer the author knows, that a wrong documentation sometimes might be worse than none. Anyway, he decided to offer his little knowledge to the public, in the hope to get enough response to improve this document. Feel free to contact the author via e-mail. For the latest release check <a href="http://www.ethernut.de/.">http://www.ethernut.de/.</a></p>
|
|
<p>Herne, 17th of May 2002 Harald Kipp harald.kipp-at-egnite.de</p>
|
|
<dl class="note"><dt><b>Note:</b></dt><dd>As of 26th of July 2002, this document has been merged into the documentation for avr-libc. The latest version is now available at <a href="http://savannah.nongnu.org/projects/avr-libc/.">http://savannah.nongnu.org/projects/avr-libc/.</a></dd></dl>
|
|
<h2><a class="anchor" id="gcc_asm">
|
|
GCC asm Statement</a></h2>
|
|
<p>Let's start with a simple example of reading a value from port D:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span>(<span class="stringliteral">"in %0, %1"</span> : <span class="stringliteral">"=r"</span> (value) : <span class="stringliteral">"I"</span> (_SFR_IO_ADDR(PORTD)) );
|
|
</pre></div><p>Each <code>asm</code> statement is devided by colons into (up to) four parts:</p>
|
|
<ol type="1">
|
|
<li>The assembler instructions, defined as a single string constant: <div class="fragment"><pre class="fragment"> <span class="stringliteral">"in %0, %1"</span>
|
|
</pre></div></li>
|
|
<li>A list of output operands, separated by commas. Our example uses just one: <div class="fragment"><pre class="fragment"> <span class="stringliteral">"=r"</span> (value)
|
|
</pre></div></li>
|
|
<li>A comma separated list of input operands. Again our example uses one operand only: <div class="fragment"><pre class="fragment"> <span class="stringliteral">"I"</span> (_SFR_IO_ADDR(PORTD))
|
|
</pre></div></li>
|
|
<li>Clobbered registers, left empty in our example.</li>
|
|
</ol>
|
|
<p>You can write assembler instructions in much the same way as you would write assembler programs. However, registers and constants are used in a different way if they refer to expressions of your C program. The connection between registers and C operands is specified in the second and third part of the <code>asm</code> instruction, the list of input and output operands, respectively. The general form is</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span>(code : output operand list : input operand list [: clobber list]);
|
|
</pre></div><p>In the code section, operands are referenced by a percent sign followed by a single digit. <code>0</code> refers to the first <code>1</code> to the second operand and so forth. From the above example:</p>
|
|
<p><code>0</code> refers to <code>"=r" (value)</code> and<br/>
|
|
<code>1</code> refers to <code>"I" (_SFR_IO_ADDR(PORTD))</code>.</p>
|
|
<p>This may still look a little odd now, but the syntax of an operand list will be explained soon. Let us first examine the part of a compiler listing which may have been generated from our example:</p>
|
|
<div class="fragment"><pre class="fragment"> lds r24,value
|
|
<span class="comment">/* #APP */</span>
|
|
in r24, 12
|
|
<span class="comment">/* #NOAPP */</span>
|
|
sts value,r24
|
|
</pre></div><p>The comments have been added by the compiler to inform the assembler that the included code was not generated by the compilation of C statements, but by inline assembler statements. The compiler selected register <code>r24</code> for storage of the value read from <code>PORTD</code>. The compiler could have selected any other register, though. It may not explicitely load or store the value and it may even decide not to include your assembler code at all. All these decisions are part of the compiler's optimization strategy. For example, if you never use the variable value in the remaining part of the C program, the compiler will most likely remove your code unless you switched off optimization. To avoid this, you can add the volatile attribute to the <code>asm</code> statement:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(<span class="stringliteral">"in %0, %1"</span> : <span class="stringliteral">"=r"</span> (value) : <span class="stringliteral">"I"</span> (_SFR_IO_ADDR(PORTD)));
|
|
</pre></div><p>Alternatively, operands can be given names. The name is prepended in brackets to the constraints in the operand list, and references to the named operand use the bracketed name instead of a number after the % sign. Thus, the above example could also be written as</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span>(<span class="stringliteral">"in %[retval], %[port]"</span> :
|
|
[retval] <span class="stringliteral">"=r"</span> (value) :
|
|
[port] <span class="stringliteral">"I"</span> (_SFR_IO_ADDR(PORTD)) );
|
|
</pre></div><p>The last part of the <code>asm</code> instruction, the clobber list, is mainly used to tell the compiler about modifications done by the assembler code. This part may be omitted, all other parts are required, but may be left empty. If your assembler routine won't use any input or output operand, two colons must still follow the assembler code string. A good example is a simple statement to disable interrupts:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(<span class="stringliteral">"cli"</span>::);
|
|
</pre></div><h2><a class="anchor" id="asm_code">
|
|
Assembler Code</a></h2>
|
|
<p>You can use the same assembler instruction mnemonics as you'd use with any other AVR assembler. And you can write as many assembler statements into one code string as you like and your flash memory is able to hold.</p>
|
|
<dl class="note"><dt><b>Note:</b></dt><dd>The available assembler directives vary from one assembler to another.</dd></dl>
|
|
<p>To make it more readable, you should put each statement on a seperate line:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(<span class="stringliteral">"nop\n\t"</span>
|
|
<span class="stringliteral">"nop\n\t"</span>
|
|
<span class="stringliteral">"nop\n\t"</span>
|
|
<span class="stringliteral">"nop\n\t"</span>
|
|
::);
|
|
</pre></div><p>The linefeed and tab characters will make the assembler listing generated by the compiler more readable. It may look a bit odd for the first time, but that's the way the compiler creates it's own assembler code.</p>
|
|
<p>You may also make use of some special registers.</p>
|
|
<table class="doxtable">
|
|
<tr>
|
|
<td><b>Symbol</b> </td><td><b>Register</b> </td></tr>
|
|
<tr>
|
|
<td><code>__SREG__</code> </td><td>Status register at address 0x3F </td></tr>
|
|
<tr>
|
|
<td><code>__SP_H__</code> </td><td>Stack pointer high byte at address 0x3E </td></tr>
|
|
<tr>
|
|
<td><code>__SP_L__</code> </td><td>Stack pointer low byte at address 0x3D </td></tr>
|
|
<tr>
|
|
<td><code>__tmp_reg__</code> </td><td>Register r0, used for temporary storage </td></tr>
|
|
<tr>
|
|
<td><code>__zero_reg__</code> </td><td>Register r1, always zero </td></tr>
|
|
</table>
|
|
<p>Register <code>r0</code> may be freely used by your assembler code and need not be restored at the end of your code. It's a good idea to use <code>__tmp_reg__</code> and <code>__zero_reg__</code> instead of <code>r0</code> or <code>r1</code>, just in case a new compiler version changes the register usage definitions.</p>
|
|
<h2><a class="anchor" id="io_ops">
|
|
Input and Output Operands</a></h2>
|
|
<p>Each input and output operand is described by a constraint string followed by a C expression in parantheses. <code>AVR-GCC</code> 3.3 knows the following constraint characters:</p>
|
|
<dl class="note"><dt><b>Note:</b></dt><dd>The most up-to-date and detailed information on contraints for the avr can be found in the gcc manual.</dd>
|
|
<dd>
|
|
The <code>x</code> register is <code>r27:r26</code>, the <code>y</code> register is <code>r29:r28</code>, and the <code>z</code> register is <code>r31:r30</code></dd></dl>
|
|
<table class="doxtable">
|
|
<tr>
|
|
<td><b>Constraint</b></td><td><b>Used for</b></td><td><b>Range</b> </td></tr>
|
|
<tr>
|
|
<td>a</td><td>Simple upper registers</td><td>r16 to r23 </td></tr>
|
|
<tr>
|
|
<td>b</td><td>Base pointer registers pairs</td><td>y, z </td></tr>
|
|
<tr>
|
|
<td>d</td><td>Upper register</td><td>r16 to r31 </td></tr>
|
|
<tr>
|
|
<td>e</td><td>Pointer register pairs</td><td>x, y, z </td></tr>
|
|
<tr>
|
|
<td>q</td><td>Stack pointer register</td><td>SPH:SPL </td></tr>
|
|
<tr>
|
|
<td>r</td><td>Any register</td><td>r0 to r31 </td></tr>
|
|
<tr>
|
|
<td>t</td><td>Temporary register</td><td>r0 </td></tr>
|
|
<tr>
|
|
<td>w</td><td>Special upper register pairs</td><td>r24, r26, r28, r30 </td></tr>
|
|
<tr>
|
|
<td>x</td><td>Pointer register pair X</td><td>x (r27:r26) </td></tr>
|
|
<tr>
|
|
<td>y</td><td>Pointer register pair Y</td><td>y (r29:r28) </td></tr>
|
|
<tr>
|
|
<td>z</td><td>Pointer register pair Z</td><td>z (r31:r30) </td></tr>
|
|
<tr>
|
|
<td>G</td><td>Floating point constant</td><td>0.0 </td></tr>
|
|
<tr>
|
|
<td>I</td><td>6-bit positive integer constant</td><td>0 to 63 </td></tr>
|
|
<tr>
|
|
<td>J</td><td>6-bit negative integer constant</td><td>-63 to 0 </td></tr>
|
|
<tr>
|
|
<td>K</td><td>Integer constant</td><td>2 </td></tr>
|
|
<tr>
|
|
<td>L</td><td>Integer constant</td><td>0 </td></tr>
|
|
<tr>
|
|
<td>l</td><td>Lower registers</td><td>r0 to r15 </td></tr>
|
|
<tr>
|
|
<td>M</td><td>8-bit integer constant</td><td>0 to 255 </td></tr>
|
|
<tr>
|
|
<td>N</td><td>Integer constant</td><td>-1 </td></tr>
|
|
<tr>
|
|
<td>O</td><td>Integer constant</td><td>8, 16, 24 </td></tr>
|
|
<tr>
|
|
<td>P</td><td>Integer constant</td><td>1 </td></tr>
|
|
<tr>
|
|
<td>Q</td><td>(GCC >= 4.2.x) A memory address based on Y or Z pointer with displacement.</td><td> </td></tr>
|
|
<tr>
|
|
<td>R</td><td>(GCC >= 4.3.x) Integer constant.</td><td>-6 to 5 </td></tr>
|
|
</table>
|
|
<p>The selection of the proper contraint depends on the range of the constants or registers, which must be acceptable to the AVR instruction they are used with. The C compiler doesn't check any line of your assembler code. But it is able to check the constraint against your C expression. However, if you specify the wrong constraints, then the compiler may silently pass wrong code to the assembler. And, of course, the assembler will fail with some cryptic output or internal errors. For example, if you specify the constraint <code>"r"</code> and you are using this register with an <code>"ori"</code> instruction in your assembler code, then the compiler may select any register. This will fail, if the compiler chooses <code>r2</code> to <code>r15</code>. (It will never choose <code>r0</code> or <code>r1</code>, because these are uses for special purposes.) That's why the correct constraint in that case is <code>"d"</code>. On the other hand, if you use the constraint <code>"M"</code>, the compiler will make sure that you don't pass anything else but an 8-bit value. Later on we will see how to pass multibyte expression results to the assembler code.</p>
|
|
<p>The following table shows all AVR assembler mnemonics which require operands, and the related contraints. Because of the improper constraint definitions in version 3.3, they aren't strict enough. There is, for example, no constraint, which restricts integer constants to the range 0 to 7 for bit set and bit clear operations.</p>
|
|
<table class="doxtable">
|
|
<tr>
|
|
<td><b>Mnemonic</b> </td><td><b>Constraints</b> </td><td></td><td><b>Mnemonic</b> </td><td><b>Constraints</b> </td></tr>
|
|
<tr>
|
|
<td>adc </td><td>r,r </td><td></td><td>add </td><td>r,r </td></tr>
|
|
<tr>
|
|
<td>adiw </td><td>w,I </td><td></td><td>and </td><td>r,r </td></tr>
|
|
<tr>
|
|
<td>andi </td><td>d,M </td><td></td><td>asr </td><td>r </td></tr>
|
|
<tr>
|
|
<td>bclr </td><td>I </td><td></td><td>bld </td><td>r,I </td></tr>
|
|
<tr>
|
|
<td>brbc </td><td>I,label </td><td></td><td>brbs </td><td>I,label </td></tr>
|
|
<tr>
|
|
<td>bset </td><td>I </td><td></td><td>bst </td><td>r,I </td></tr>
|
|
<tr>
|
|
<td>cbi </td><td>I,I </td><td></td><td>cbr </td><td>d,I </td></tr>
|
|
<tr>
|
|
<td>com </td><td>r </td><td></td><td>cp </td><td>r,r </td></tr>
|
|
<tr>
|
|
<td>cpc </td><td>r,r </td><td></td><td>cpi </td><td>d,M </td></tr>
|
|
<tr>
|
|
<td>cpse </td><td>r,r </td><td></td><td>dec </td><td>r </td></tr>
|
|
<tr>
|
|
<td>elpm </td><td>t,z </td><td></td><td>eor </td><td>r,r </td></tr>
|
|
<tr>
|
|
<td>in </td><td>r,I </td><td></td><td>inc </td><td>r </td></tr>
|
|
<tr>
|
|
<td>ld </td><td>r,e </td><td></td><td>ldd </td><td>r,b </td></tr>
|
|
<tr>
|
|
<td>ldi </td><td>d,M </td><td></td><td>lds </td><td>r,label </td></tr>
|
|
<tr>
|
|
<td>lpm </td><td>t,z </td><td></td><td>lsl </td><td>r </td></tr>
|
|
<tr>
|
|
<td>lsr </td><td>r </td><td></td><td>mov </td><td>r,r </td></tr>
|
|
<tr>
|
|
<td>movw </td><td>r,r </td><td></td><td>mul </td><td>r,r </td></tr>
|
|
<tr>
|
|
<td>neg </td><td>r </td><td></td><td>or </td><td>r,r </td></tr>
|
|
<tr>
|
|
<td>ori </td><td>d,M </td><td></td><td>out </td><td>I,r </td></tr>
|
|
<tr>
|
|
<td>pop </td><td>r </td><td></td><td>push </td><td>r </td></tr>
|
|
<tr>
|
|
<td>rol </td><td>r </td><td></td><td>ror </td><td>r </td></tr>
|
|
<tr>
|
|
<td>sbc </td><td>r,r </td><td></td><td>sbci </td><td>d,M </td></tr>
|
|
<tr>
|
|
<td>sbi </td><td>I,I </td><td></td><td>sbic </td><td>I,I </td></tr>
|
|
<tr>
|
|
<td>sbiw </td><td>w,I </td><td></td><td>sbr </td><td>d,M </td></tr>
|
|
<tr>
|
|
<td>sbrc </td><td>r,I </td><td></td><td>sbrs </td><td>r,I </td></tr>
|
|
<tr>
|
|
<td>ser </td><td>d </td><td></td><td>st </td><td>e,r </td></tr>
|
|
<tr>
|
|
<td>std </td><td>b,r </td><td></td><td>sts </td><td>label,r </td></tr>
|
|
<tr>
|
|
<td>sub </td><td>r,r </td><td></td><td>subi </td><td>d,M </td></tr>
|
|
<tr>
|
|
<td>swap </td><td>r </td><td></td><td></td><td></td></tr>
|
|
</table>
|
|
<p>Constraint characters may be prepended by a single constraint modifier. Contraints without a modifier specify read-only operands. Modifiers are:</p>
|
|
<table class="doxtable">
|
|
<tr>
|
|
<td><b>Modifier</b> </td><td><b>Specifies</b> </td></tr>
|
|
<tr>
|
|
<td>= </td><td>Write-only operand, usually used for all output operands. </td></tr>
|
|
<tr>
|
|
<td>+ </td><td>Read-write operand </td></tr>
|
|
<tr>
|
|
<td>& </td><td>Register should be used for output only </td></tr>
|
|
</table>
|
|
<p>Output operands must be write-only and the C expression result must be an lvalue, which means that the operands must be valid on the left side of assignments. Note, that the compiler will not check if the operands are of reasonable type for the kind of operation used in the assembler instructions.</p>
|
|
<p>Input operands are, you guessed it, read-only. But what if you need the same operand for input and output? As stated above, read-write operands are not supported in inline assembler code. But there is another solution. For input operators it is possible to use a single digit in the constraint string. Using digit n tells the compiler to use the same register as for the n-th operand, starting with zero. Here is an example:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(<span class="stringliteral">"swap %0"</span> : <span class="stringliteral">"=r"</span> (value) : <span class="stringliteral">"0"</span> (value));
|
|
</pre></div><p>This statement will swap the nibbles of an 8-bit variable named value. Constraint <code>"0"</code> tells the compiler, to use the same input register as for the first operand. Note however, that this doesn't automatically imply the reverse case. The compiler may choose the same registers for input and output, even if not told to do so. This is not a problem in most cases, but may be fatal if the output operator is modified by the assembler code before the input operator is used. In the situation where your code depends on different registers used for input and output operands, you must add the <code>&</code> constraint modifier to your output operand. The following example demonstrates this problem:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(<span class="stringliteral">"in %0,%1"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"out %1, %2"</span> <span class="stringliteral">"\n\t"</span>
|
|
: <span class="stringliteral">"=&r"</span> (input)
|
|
: <span class="stringliteral">"I"</span> (_SFR_IO_ADDR(port)), <span class="stringliteral">"r"</span> (output)
|
|
);
|
|
</pre></div><p>In this example an input value is read from a port and then an output value is written to the same port. If the compiler would have choosen the same register for input and output, then the output value would have been destroyed on the first assembler instruction. Fortunately, this example uses the <code>&</code> constraint modifier to instruct the compiler not to select any register for the output value, which is used for any of the input operands. Back to swapping. Here is the code to swap high and low byte of a 16-bit value:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(<span class="stringliteral">"mov __tmp_reg__, %A0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %A0, %B0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %B0, __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
: <span class="stringliteral">"=r"</span> (value)
|
|
: <span class="stringliteral">"0"</span> (value)
|
|
);
|
|
</pre></div><p>First you will notice the usage of register <code>__tmp_reg__</code>, which we listed among other special registers in the <a class="el" href="inline__asm.html#asm_code">Assembler Code</a> section. You can use this register without saving its contents. Completely new are those letters <code>A</code> and <code>B</code> in <code>%A0</code> and <code>%B0</code>. In fact they refer to two different 8-bit registers, both containing a part of value.</p>
|
|
<p>Another example to swap bytes of a 32-bit value:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(<span class="stringliteral">"mov __tmp_reg__, %A0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %A0, %D0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %D0, __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov __tmp_reg__, %B0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %B0, %C0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %C0, __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
: <span class="stringliteral">"=r"</span> (value)
|
|
: <span class="stringliteral">"0"</span> (value)
|
|
);
|
|
</pre></div><p>Instead of listing the same operand as both, input and output operand, it can also be declared as a read-write operand. This must be applied to an output operand, and the respective input operand list remains empty:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(<span class="stringliteral">"mov __tmp_reg__, %A0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %A0, %D0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %D0, __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov __tmp_reg__, %B0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %B0, %C0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %C0, __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
: <span class="stringliteral">"+r"</span> (value));
|
|
</pre></div><p>If operands do not fit into a single register, the compiler will automatically assign enough registers to hold the entire operand. In the assembler code you use <code>%A0</code> to refer to the lowest byte of the first operand, <code>%A1</code> to the lowest byte of the second operand and so on. The next byte of the first operand will be <code>%B0</code>, the next byte <code>%C0</code> and so on.</p>
|
|
<p>This also implies, that it is often neccessary to cast the type of an input operand to the desired size.</p>
|
|
<p>A final problem may arise while using pointer register pairs. If you define an input operand</p>
|
|
<div class="fragment"><pre class="fragment"><span class="stringliteral">"e"</span> (ptr)
|
|
</pre></div><p>and the compiler selects register <code>Z</code> <code></code>(r30:r31), then</p>
|
|
<p><code>%A0</code> refers to <code>r30</code> and<br/>
|
|
<code>%B0</code> refers to <code>r31</code>.</p>
|
|
<p>But both versions will fail during the assembly stage of the compiler, if you explicitely need <code>Z</code>, like in</p>
|
|
<div class="fragment"><pre class="fragment">ld r24,Z
|
|
</pre></div><p>If you write</p>
|
|
<div class="fragment"><pre class="fragment">ld r24, %a0
|
|
</pre></div><p>with a lower case <code>a</code> following the percent sign, then the compiler will create the proper assembler line.</p>
|
|
<h2><a class="anchor" id="clobbers">
|
|
Clobbers</a></h2>
|
|
<p>As stated previously, the last part of the <code>asm</code> statement, the list of clobbers, may be omitted, including the colon seperator. However, if you are using registers, which had not been passed as operands, you need to inform the compiler about this. The following example will do an atomic increment. It increments an 8-bit value pointed to by a pointer variable in one go, without being interrupted by an interrupt routine or another thread in a multithreaded environment. Note, that we must use a pointer, because the incremented value needs to be stored before interrupts are enabled.</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(
|
|
<span class="stringliteral">"cli"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"ld r24, %a0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"inc r24"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"st %a0, r24"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"sei"</span> <span class="stringliteral">"\n\t"</span>
|
|
:
|
|
: <span class="stringliteral">"e"</span> (ptr)
|
|
: <span class="stringliteral">"r24"</span>
|
|
);
|
|
</pre></div><p>The compiler might produce the following code:</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="group__avr__interrupts.html#ga68c330e94fe121eba993e5a5973c3162">cli</a>
|
|
ld r24, Z
|
|
inc r24
|
|
st Z, r24
|
|
<a class="code" href="group__avr__interrupts.html#gaad5ebd34cb344c26ac87594f79b06b73">sei</a>
|
|
</pre></div><p>One easy solution to avoid clobbering register <code>r24</code> is, to make use of the special temporary register <code>__tmp_reg__</code> defined by the compiler.</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">asm</span> <span class="keyword">volatile</span>(
|
|
<span class="stringliteral">"cli"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"ld __tmp_reg__, %a0"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"inc __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"st %a0, __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"sei"</span> <span class="stringliteral">"\n\t"</span>
|
|
:
|
|
: <span class="stringliteral">"e"</span> (ptr)
|
|
);
|
|
</pre></div><p>The compiler is prepared to reload this register next time it uses it. Another problem with the above code is, that it should not be called in code sections, where interrupts are disabled and should be kept disabled, because it will enable interrupts at the end. We may store the current status, but then we need another register. Again we can solve this without clobbering a fixed, but let the compiler select it. This could be done with the help of a local C variable.</p>
|
|
<div class="fragment"><pre class="fragment">{
|
|
<a class="code" href="group__avr__stdint.html#gaba7bc1797add20fe3efdf37ced1182c5">uint8_t</a> s;
|
|
<span class="keyword">asm</span> <span class="keyword">volatile</span>(
|
|
<span class="stringliteral">"in %0, __SREG__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"cli"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"ld __tmp_reg__, %a1"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"inc __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"st %a1, __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"out __SREG__, %0"</span> <span class="stringliteral">"\n\t"</span>
|
|
: <span class="stringliteral">"=&r"</span> (s)
|
|
: <span class="stringliteral">"e"</span> (ptr)
|
|
);
|
|
}
|
|
</pre></div><p>Now every thing seems correct, but it isn't really. The assembler code modifies the variable, that <code>ptr</code> points to. The compiler will not recognize this and may keep its value in any of the other registers. Not only does the compiler work with the wrong value, but the assembler code does too. The C program may have modified the value too, but the compiler didn't update the memory location for optimization reasons. The worst thing you can do in this case is:</p>
|
|
<div class="fragment"><pre class="fragment">{
|
|
<a class="code" href="group__avr__stdint.html#gaba7bc1797add20fe3efdf37ced1182c5">uint8_t</a> s;
|
|
<span class="keyword">asm</span> <span class="keyword">volatile</span>(
|
|
<span class="stringliteral">"in %0, __SREG__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"cli"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"ld __tmp_reg__, %a1"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"inc __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"st %a1, __tmp_reg__"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"out __SREG__, %0"</span> <span class="stringliteral">"\n\t"</span>
|
|
: <span class="stringliteral">"=&r"</span> (s)
|
|
: <span class="stringliteral">"e"</span> (ptr)
|
|
: <span class="stringliteral">"memory"</span>
|
|
);
|
|
}
|
|
</pre></div><p>The special clobber "memory" informs the compiler that the assembler code may modify any memory location. It forces the compiler to update all variables for which the contents are currently held in a register before executing the assembler code. And of course, everything has to be reloaded again after this code.</p>
|
|
<p>In most situations, a much better solution would be to declare the pointer destination itself volatile:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">volatile</span> <a class="code" href="group__avr__stdint.html#gaba7bc1797add20fe3efdf37ced1182c5">uint8_t</a> *ptr;
|
|
</pre></div><p>This way, the compiler expects the value pointed to by <code>ptr</code> to be changed and will load it whenever used and store it whenever modified.</p>
|
|
<p>Situations in which you need clobbers are very rare. In most cases there will be better ways. Clobbered registers will force the compiler to store their values before and reload them after your assembler code. Avoiding clobbers gives the compiler more freedom while optimizing your code.</p>
|
|
<h2><a class="anchor" id="asm_macros">
|
|
Assembler Macros</a></h2>
|
|
<p>In order to reuse your assembler language parts, it is useful to define them as macros and put them into include files. AVR Libc comes with a bunch of them, which could be found in the directory <code>avr/include</code>. Using such include files may produce compiler warnings, if they are used in modules, which are compiled in strict ANSI mode. To avoid that, you can write <code>__asm__</code> instead of <code>asm</code> and <code>__volatile__</code> instead of <code>volatile</code>. These are equivalent aliases.</p>
|
|
<p>Another problem with reused macros arises if you are using labels. In such cases you may make use of the special pattern <code>=</code>, which is replaced by a unique number on each <code>asm</code> statement. The following code had been taken from <code>avr/include/iomacros.h</code>:</p>
|
|
<div class="fragment"><pre class="fragment">#define loop_until_bit_is_clear(port,bit) \
|
|
__asm__ __volatile__ ( \
|
|
"L_%=: " "sbic %0, %1" "\n\t" \
|
|
"rjmp L_%=" \
|
|
: /* no outputs */
|
|
: "I" (_SFR_IO_ADDR(port)),
|
|
"I" (bit)
|
|
)
|
|
</pre></div><p>When used for the first time, <code>L_=</code> may be translated to <code>L_1404</code>, the next usage might create <code>L_1405</code> or whatever. In any case, the labels became unique too.</p>
|
|
<p>Another option is to use Unix-assembler style numeric labels. They are explained in <a class="el" href="FAQ.html#faq_asmstabs">How do I trace an assembler file in avr-gdb?</a>. The above example would then look like:</p>
|
|
<div class="fragment"><pre class="fragment">#define loop_until_bit_is_clear(port,bit)
|
|
__asm__ __volatile__ (
|
|
"1: " "sbic %0, %1" "\n\t"
|
|
"rjmp 1b"
|
|
: /* no outputs */
|
|
: "I" (_SFR_IO_ADDR(port)),
|
|
"I" (bit)
|
|
)
|
|
</pre></div><h2><a class="anchor" id="asm_c_stubs">
|
|
C Stub Functions</a></h2>
|
|
<p>Macro definitions will include the same assembler code whenever they are referenced. This may not be acceptable for larger routines. In this case you may define a C stub function, containing nothing other than your assembler code.</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> delay(<a class="code" href="group__avr__stdint.html#gaba7bc1797add20fe3efdf37ced1182c5">uint8_t</a> ms)
|
|
{
|
|
<a class="code" href="group__avr__stdint.html#ga1f1825b69244eb3ad2c7165ddc99c956">uint16_t</a> cnt;
|
|
<span class="keyword">asm</span> <span class="keyword">volatile</span> (
|
|
<span class="stringliteral">"\n"</span>
|
|
<span class="stringliteral">"L_dl1%=:"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %A0, %A2"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"mov %B0, %B2"</span> <span class="stringliteral">"\n"</span>
|
|
<span class="stringliteral">"L_dl2%=:"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"sbiw %A0, 1"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"brne L_dl2%="</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"dec %1"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"brne L_dl1%="</span> <span class="stringliteral">"\n\t"</span>
|
|
: <span class="stringliteral">"=&w"</span> (cnt)
|
|
: <span class="stringliteral">"r"</span> (ms), <span class="stringliteral">"r"</span> (delay_count)
|
|
);
|
|
}
|
|
</pre></div><p>The purpose of this function is to delay the program execution by a specified number of milliseconds using a counting loop. The global 16 bit variable delay_count must contain the CPU clock frequency in Hertz divided by 4000 and must have been set before calling this routine for the first time. As described in the <a class="el" href="inline__asm.html#clobbers">clobber</a> section, the routine uses a local variable to hold a temporary value.</p>
|
|
<p>Another use for a local variable is a return value. The following function returns a 16 bit value read from two successive port addresses.</p>
|
|
<div class="fragment"><pre class="fragment"><a class="code" href="group__avr__stdint.html#ga1f1825b69244eb3ad2c7165ddc99c956">uint16_t</a> inw(<a class="code" href="group__avr__stdint.html#gaba7bc1797add20fe3efdf37ced1182c5">uint8_t</a> port)
|
|
{
|
|
<a class="code" href="group__avr__stdint.html#ga1f1825b69244eb3ad2c7165ddc99c956">uint16_t</a> result;
|
|
<span class="keyword">asm</span> <span class="keyword">volatile</span> (
|
|
<span class="stringliteral">"in %A0,%1"</span> <span class="stringliteral">"\n\t"</span>
|
|
<span class="stringliteral">"in %B0,(%1) + 1"</span>
|
|
: <span class="stringliteral">"=r"</span> (result)
|
|
: <span class="stringliteral">"I"</span> (_SFR_IO_ADDR(port))
|
|
);
|
|
<span class="keywordflow">return</span> result;
|
|
}
|
|
</pre></div><dl class="note"><dt><b>Note:</b></dt><dd>inw() is supplied by avr-libc.</dd></dl>
|
|
<h2><a class="anchor" id="c_names_in_asm">
|
|
C Names Used in Assembler Code</a></h2>
|
|
<p>By default <code>AVR-GCC</code> uses the same symbolic names of functions or variables in C and assembler code. You can specify a different name for the assembler code by using a special form of the <code>asm</code> statement:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> value <span class="keyword">asm</span>(<span class="stringliteral">"clock"</span>) = 3686400;
|
|
</pre></div><p>This statement instructs the compiler to use the symbol name clock rather than value. This makes sense only for external or static variables, because local variables do not have symbolic names in the assembler code. However, local variables may be held in registers.</p>
|
|
<p>With <code>AVR-GCC</code> you can specify the use of a specific register:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> Count(<span class="keywordtype">void</span>)
|
|
{
|
|
<span class="keyword">register</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> counter <span class="keyword">asm</span>(<span class="stringliteral">"r3"</span>);
|
|
|
|
... some code...
|
|
<span class="keyword">asm</span> <span class="keyword">volatile</span>(<span class="stringliteral">"clr r3"</span>);
|
|
... more code...
|
|
}
|
|
</pre></div><p>The assembler instruction, <code>"clr r3"</code>, will clear the variable counter. <code>AVR-GCC</code> will not completely reserve the specified register. If the optimizer recognizes that the variable will not be referenced any longer, the register may be re-used. But the compiler is not able to check wether this register usage conflicts with any predefined register. If you reserve too many registers in this way, the compiler may even run out of registers during code generation.</p>
|
|
<p>In order to change the name of a function, you need a prototype declaration, because the compiler will not accept the <code>asm</code> keyword in the function definition:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="keyword">extern</span> <span class="keywordtype">long</span> Calc(<span class="keywordtype">void</span>) asm ("CALCULATE");
|
|
</pre></div><p>Calling the function <code>Calc()</code> will create assembler instructions to call the function <code>CALCULATE</code>.</p>
|
|
<h2><a class="anchor" id="links">
|
|
Links</a></h2>
|
|
<p>For a more thorough discussion of inline assembly usage, see the gcc user manual. The latest version of the gcc manual is always available here: <a href="http://gcc.gnu.org/onlinedocs/">http://gcc.gnu.org/onlinedocs/</a> </p>
|
|
</div>
|
|
<!--- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Defines</a></div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<!-- HTML footer for doxygen 1.8.7-->
|
|
<!-- start footer part -->
|
|
<!--BEGIN GENERATE_TREEVIEW-->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
$navpath
|
|
<li class="footer">$generatedby
|
|
<a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> 1.6.3 </li>
|
|
</ul>
|
|
</div>
|
|
<!--END GENERATE_TREEVIEW-->
|
|
<!--BEGIN !GENERATE_TREEVIEW-->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
$generatedby  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
|
|
</a> 1.6.3
|
|
</small></address>
|
|
<!--END !GENERATE_TREEVIEW-->
|
|
</body>
|
|
</html>
|