[Main]
Title=Assembler Instructions with C Expression Operands

[Top]
In an assembler instruction using <CODE>asm</CODE>, you can specify the
operands of the instruction using C expressions.  This means you need not
guess which registers or memory locations will contain the data you want
to use.
<BR><BR>
You must specify an assembler instruction template much like what
appears in a machine description, plus an operand constraint string for
each operand.
<BR><BR>
For the beginning, you will be given here a very illustrative example on how to use the 68881's
<CODE>fsinx</CODE> instruction (note that this example is not applicable to TI calculators,
because the MC68000 processor which is built into the TI-89 and TI-92+ does not have this
instruction, but the example is illustrative anyway):
<PRE>asm (&quot;fsinx %1,%0&quot; : &quot;=f&quot; (result) : &quot;f&quot; (angle));
</PRE>
Here <I>angle</I> is the C expression for the input operand while
<I>result</I> is that of the output operand.  Each has <CODE>&quot;f&quot;</CODE> as its
operand constraint, saying that a floating point register is required.
The <CODE>=</CODE> in <CODE>=f</CODE> indicates that the operand is an output; all
output operands' constraints must use <CODE>=</CODE>.  The constraints use the
same language used in the machine description (see the section <A HREF="$$LINK(SEC95)">Operand Constraints</A>).
In this example,
the compiler will convert this instruction into a sequence of assembly instructions
which will ensure that the evaluated expression <I>angle</I> is really stored in
one of the 68881's floating point registers, and which will store the result of the <CODE>fsinx</CODE>
(which is in some other floating point register) into the expression <I>result</I>
(note that <I>result</I> need not be a variable; it can be any lvalue expression, for
example a dereferenced pointer).
<BR><BR>
Each operand is described by an operand-constraint string followed by
the C expression in parentheses.  A colon separates the assembler
template from the first output operand and another separates the last
output operand from the first input, if any.  Commas separate the
operands within each group.  The total number of operands is currently
limited to 30; this limitation may be lifted in some future version of
GCC.
<BR><BR>
If there are no output operands but there are input operands, you must
place two consecutive colons surrounding the place where the output
operands would go.
<BR><BR>
As of GCC version 3.1, it is also possible to specify input and output
operands using symbolic names which can be referenced within the
assembler code.  These names are specified inside square brackets
preceding the constraint string, and can be referenced inside the
assembler code using <CODE>%[<I>name</I>]</CODE> instead of a percentage sign
followed by the operand number.  Using named operands the above example
could look like:
<PRE>asm (&quot;fsinx %[angle],%[output]&quot;
     : [output] &quot;=f&quot; (result)
     : [angle] &quot;f&quot; (angle));
</PRE>
Note that the symbolic operand names have no relation whatsoever to
other C identifiers.  You may use any name you like, even those of
existing C symbols, but must ensure that no two operands within the same
assembler construct use the same symbolic name.
<BR><BR>
Output operand expressions must be lvalues; the compiler can check this.
The input operands need not be lvalues.  The compiler cannot check
whether the operands have data types that are reasonable for the
instruction being executed.  It does not parse the assembler instruction
template and does not know what it means or even whether it is valid
assembler input.  The extended <CODE>asm</CODE> feature is most often used for
machine instructions the compiler itself does not know exist.  If
the output expression cannot be directly addressed (for example, it is a
bit-field), your constraint must allow a register.  In that case, GCC
will use the register as the output of the <CODE>asm</CODE>, and then store
that register into the output.
<BR><BR>
Here is an another example, which is applicable to TIGCC. Suppose that we
want to rotate the value of the expression <I>input</I> one bit to the left, and
to store the result into the expression <I>output</I> (which is an lvalue).
We can write the following code:
<PRE>asm ("move.l %1,%%d0; rol #1,%%d0; move.l %%d0,%0" : "=g" (output) : "g" (input));
</PRE>
Note that when extended asm constructions are used, the percent sign before the
register names must be doubled. It is important to say that in the above example
<I>input</I> and <I>output</I> may be any valid expressions; in the simple case
when both of them are just global variables, a simple asm construction like
<PRE>asm ("move.l input,%d0; rol #1,%d0; move.l %d0,output");
</PRE>
would be quite enough. Extended asm constructions allow encapsulating them in macros
which look like functions, like in the following example, which defines a macro <CODE>'rotate'</CODE>
which acts like a void function:
<PRE>#define rotate(input, output) \
({ asm ("move.l %1,%%d0; rol #1,%%d0; move.l %%d0,%0" \
: "=g" (output) : "g" (input)); })
</PRE>
The ordinary output operands must be write-only; GCC will assume that
the values in these operands before the instruction are dead and need
not be generated. That's why the following version of <CODE>'rotate'</CODE>
macro which accepts just one argument (and which rotates it one bit to the left)
is quite unreliable:
<PRE>#define rotate(inout) ({ asm ("rol #1,%0" : "=d" (inout)); })
</PRE>
To solve such difficulties, extended asm supports input-output or read-write
operands.  Use the constraint character <CODE>+</CODE> to indicate such an
operand and list it with the output operands.
<BR><BR>
When the constraints for the read-write operand (or the operand in which
only some of the bits are to be changed) allows a register, you may, as
an alternative, logically split its function into two separate operands,
one input operand and one write-only output operand.  The connection
between them is expressed by constraints which say they need to be in
the same location when the instruction executes.  You can use the same C
expression for both operands, or different expressions.  For example,
here we write the (fictitious) <CODE>combine</CODE> instruction with
<CODE>bar</CODE> as its read-only source operand and <CODE>foo</CODE> as its
read-write destination:
<PRE>asm (&quot;combine %2,%0&quot; : &quot;=r&quot; (foo) : &quot;0&quot; (foo), &quot;g&quot; (bar));
</PRE>
The constraint <CODE>&quot;0&quot;</CODE> for operand 1 says that it must occupy the
same location as operand 0.  A number in constraint is allowed only in
an input operand and it must refer to an output operand.
<BR><BR>
Only a number in the constraint can guarantee that one operand will be in
the same place as another.  The mere fact that <CODE>foo</CODE> is the value
of both operands is not enough to guarantee that they will be in the
same place in the generated assembler code.  The following would not
work reliably:
<PRE>asm (&quot;combine %2,%0&quot; : &quot;=r&quot; (foo) : &quot;r&quot; (foo), &quot;g&quot; (bar));
</PRE>
Various optimizations or reloading could cause operands 0 and 1 to be in
different registers; GCC knows no reason not to do so.  For example, the
compiler might find a copy of the value of <CODE>foo</CODE> in one register and
use it for operand 1, but generate the output operand 0 in a different
register (copying it afterward to <CODE>foo</CODE>'s own address).  Of course,
since the register for operand 1 is not even mentioned in the assembler
code, the result will not work, but GCC can't tell that.
<BR><BR>
As of GCC version 3.1, one may write <CODE>[<I>name</I>]</CODE> instead of
the operand number for a matching constraint.  For example:
<PRE>asm (&quot;cmoveq %1,%2,%[result]&quot;
     : [result] &quot;=r&quot;(result)
     : &quot;r&quot; (test), &quot;r&quot;(new), &quot;[result]&quot;(old));
</PRE>
All the examples given above have a serious drawback: they clobber the register <CODE>'d0'</CODE>.
If the compiler keeps something important in it (which is very likely), this may cause lots
of trouble. Of course,
you can save it on the stack at the beginning and restore it at the end, but there is a much better
solution which will save clobbered registers only when necessary. To describe clobbered registers,
write a third colon after the input operands, followed by the names of
the clobbered registers (given as strings), separated by commas:
<PRE>#define rotate(input, output) \
({ asm ("move.l %1,%%d0; rol #1,%%d0; move.l %%d0,%0" \
: "=g" (output) : "g" (input) : "d0"); })
</PRE>
You may not write a clobber description in a way that overlaps with an
input or output operand.  For example, you may not have an operand
describing a register class with one member if you mention that register
in the clobber list.  Variables declared to live in specific registers
(see <A HREF="$$LINK(SEC97)">Explicit Reg Vars</A>), and used as asm input or output operands must
have no part mentioned in the clobber description.
There is no way for you to specify that an input
operand is modified without also specifying it as an output
operand.  Note that if all the output operands you specify are for this
purpose (and hence unused), you will then also need to specify
<CODE>volatile</CODE> for the <CODE>asm</CODE> construct, as described below, to
prevent GCC from deleting the <CODE>asm</CODE> statement as unused.
<BR><BR>
Whenever you refer to a particular hardware register from the assembler code,
you will probably have to list the register after the third colon to
tell the compiler the register's value is modified.
Alternatively, you can force the compiler to use any data register instead of
<CODE>'d0'</CODE>, using the following trick:
<PRE>#define rotate(input, output) \
({ register long __temp; \
asm ("move.l %1,%2; rol #1,%2; move.l %2,%0" \
: "=g" (output) : "g" (input), "d" (__temp)); })
</PRE>
Here, the <CODE>"d"</CODE> constraint ensures that <CODE>'__temp'</CODE> will be stored in
the data register (note that <CODE>rol</CODE> is applicable only to data registers).
In fact, there is no need for a temporary register if we forced the output to be in
a data register, which can be implemented as in the following example:
<PRE>#define rotate(input, output) \
({ asm ("move.l %1,%0; rol #1,%0" : "=d" (output) : "g" (input)); })
</PRE>
If your assembler instruction can alter the condition code register, add
<CODE>cc</CODE> to the list of clobbered registers.  GCC on some machines
represents the condition codes as a specific hardware register;
<CODE>cc</CODE> serves to name this register.  On other machines, the
condition code is handled differently, and specifying <CODE>cc</CODE> has no
effect.  But it is valid no matter what the machine.
<BR><BR>
If your assembler instruction modifies memory in an unpredictable
fashion, add <CODE>memory</CODE> to the list of clobbered registers.  This
will cause GCC to not keep memory values cached in registers across
the assembler instruction.  You will also want to add the
<CODE>volatile</CODE> keyword if the memory affected is not listed in the
inputs or outputs of the <CODE>asm</CODE>, as the <CODE>memory</CODE> clobber does
not count as a side-effect of the <CODE>asm</CODE>.
<BR><BR>
As already mentioned above, you can put multiple assembler instructions together in a single
<CODE>asm</CODE> template, separated either with newlines or with semicolons
(the GNU assembler allows semicolons as a line-breaking character).
The input operands are guaranteed not to use any of the clobbered
registers, and neither will the output operands' addresses, so you can
read and write the clobbered registers as many times as you like.  Here
is an example of multiple instructions in a template; it assumes the
subroutine <CODE>_foo</CODE> accepts arguments in registers a0 and a1:
<PRE>asm ("move.l %0,%%a0; move.l %1,%%a1; jsr _foo"
: /* no outputs */
: "g" (from), "g" (to)
: "a0", "a1");
</PRE>
Unless an output operand has the <CODE>'&amp;'</CODE> constraint modifier, GCC
may allocate it in the same register as an unrelated input operand, on
the assumption the inputs are consumed before the outputs are produced.
This assumption may be false if the assembler code actually consists of
more than one instruction.  In such a case, use <CODE>'&amp;'</CODE> for each output
operand that may not overlap an input.  See the section <A HREF="$$LINK(SEC95_cmc)">Constraint Modifier Characters</A>.
<BR><BR>
If you want to test the condition code produced by an assembler
instruction, you must include a branch and a label in the <CODE>asm</CODE>
construct, as follows:
<PRE>asm ("clr.l %0; test.l %1; beq 0f; moveq #1,%0; 0:"
: "g" (result) : "g" (input));
</PRE>
This assumes your assembler supports local labels, which is true for the
<A HREF="$$INFOLINK(gnuasm)">GNU Assembler</A> (it uses the suffix <CODE>'f'</CODE> for forward and <CODE>'b'</CODE> for
backward local labels; see the section about <A HREF="$$INFOLINK(gnuasm/SEC48L)">Local Symbol Names</A>).<BR><BR>
Speaking of labels, jumps from one <CODE>asm</CODE> to another are not
supported.  The compiler's optimizers do not know about these jumps, and
therefore they cannot take account of them when deciding how to
optimize.
<BR><BR>
As already mentioned, usually the most convenient way to use these
<CODE>asm</CODE> instructions is to encapsulate them in macros that look like
functions. Here is an example of how to define a function-looking macro with
a non-void return type:
<PRE>#define rotate(x) \
({ unsigned long __result, __arg=(x);   \
asm ("move.l %1,%0; rol #1,%0": "=d" (__result): "g" (__arg));  \
__result; })
</PRE>
This macro acts nearly exactly like a function which takes one <CODE>unsigned long</CODE>
argument, and which returns an <CODE>unsigned long</CODE> result.
Here the variable <CODE>__arg</CODE> is used to make sure that the instruction
operates on a proper <CODE>unsigned long</CODE> value, and to accept only those
arguments <CODE>x</CODE> which can convert automatically to an <CODE>unsigned long</CODE>.
<BR><BR>
Another way to make sure the instruction operates on the correct data
type is to use a cast in the <CODE>asm</CODE>.  This is different from using a
variable <CODE>__arg</CODE> in that it converts more different types.  For
example, if the desired type were <CODE>int</CODE>, casting the argument to
<CODE>int</CODE> would accept a pointer with no complaint, while assigning the
argument to an <CODE>int</CODE> variable named <CODE>__arg</CODE> would warn about
using a pointer unless the caller explicitly casts it.
<BR><BR>
If an <CODE>asm</CODE> has output operands, GCC assumes for optimization
purposes the instruction has no side effects except to change the output
operands.  This does not mean instructions with a side effect cannot be
used, but you must be careful, because the compiler may eliminate them
if the output operands aren't used, or move them out of loops, or
replace two with one if they constitute a common subexpression.  Also,
if your instruction does have a side effect on a variable that otherwise
appears not to change, the old value of the variable may be reused later
if it happens to be found in a register.
<BR><BR>
If you are not happy with this behavior,
you can prevent an <CODE>asm</CODE> instruction from being deleted, moved
significantly, or combined, by writing the keyword <CODE>volatile</CODE> after
the <CODE>asm</CODE>.  For example:
<PRE>#define get_and_set_priority(new)              \
({ int __old;                                  \
   asm volatile (&quot;get_and_set_priority %0, %1&quot; \
                 : &quot;=g&quot; (__old) : &quot;g&quot; (new));  \
   __old; })
</PRE>
If you write an <CODE>asm</CODE> instruction with no outputs, GCC will know
the instruction has side-effects and will not delete the instruction or
move it outside of loops.
<BR><BR>
The <CODE>volatile</CODE> keyword indicates that the instruction has
important side-effects.  GCC will not delete a volatile <CODE>asm</CODE> if
it is reachable.  (The instruction can still be deleted if GCC can
prove that control-flow will never reach the location of the
instruction.)  In addition, GCC will not reschedule instructions
across a volatile <CODE>asm</CODE> instruction.  For example:
<PRE>#define inline_rowread(x) \
  ({*(short*)0x600018=(short)(x); \
  asm volatile("nop;nop;nop;nop;nop;nop;nop;nop;nop;nop;nop;nop":::"memory"); \
  ~(*(unsigned char*)0x60001b);})</PRE>
Here, we can read the keyboard port at 0x60001b only 12 nops after setting
the keyboard mask at 0x600018. Therefore, we need to make sure that the
nops get scheduled between the write to 0x600018 and the read to 0x60001b.
The <CODE>volatile</CODE> keyword makes sure that the instructions get ordered
in the correct way.
<BR><BR>
Note that even a volatile <CODE>asm</CODE> instruction can be moved in ways
that appear insignificant to the compiler, such as across jump
instructions.  You can't expect a sequence of volatile <CODE>asm</CODE>
instructions to remain perfectly consecutive.  If you want consecutive
output, use a single <CODE>asm</CODE>.  Also, GCC will perform some
optimizations across a volatile <CODE>asm</CODE> instruction; GCC does not
&quot;forget everything&quot; when it encounters a volatile <CODE>asm</CODE>
instruction the way some other compilers do.
<BR><BR>
An <CODE>asm</CODE> instruction without any operands or clobbers (an &quot;old
style&quot; <CODE>asm</CODE>) will be treated identically to a volatile
<CODE>asm</CODE> instruction.
<BR><BR>
It is a natural idea to look for a way to give access to the condition
code left by the assembler instruction.  However, when we attempted to
implement this, we found no way to make it work reliably.  The problem
is that output operands might need reloading, which would result in
additional following &quot;store&quot; instructions.  On most machines, these
instructions would alter the condition code before there was time to
test it.  This problem doesn't arise for ordinary &quot;test&quot; and
&quot;compare&quot; instructions because they don't have any output operands.
<BR><BR>
For reasons similar to those described above, it is not possible to give
an assembler instruction access to the condition code left by previous
instructions.
<BR><BR>
You can write write <CODE>__asm__</CODE> instead of <CODE>asm</CODE>.
See section <A HREF="$$LINK(SEC100)">Alternate Keywords</A>.
