extend.texi

早期freebsd实现

For example, here is how to use the 68881's @code{fsinx} instruction:

@example
asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
@end example

@noindent
@ifset INTERNALS
Here @code{angle} is the C expression for the input operand while
@code{result} is that of the output operand.  Each has @samp{"f"} as its
operand constraint, saying that a floating point register is required.  The
@samp{=} in @samp{=f} indicates that the operand is an output; all output
operands' constraints must use @samp{=}.  The constraints use the same
language used in the machine description (@pxref{Constraints}).
@end ifset
@ifclear INTERNALS
Here @code{angle} is the C expression for the input operand while
@code{result} is that of the output operand.  Each has @samp{"f"} as its
operand constraint, saying that a floating point register is required.  The
@samp{=} in @samp{=f} indicates that the operand is an output; all output
operands' constraints must use @samp{=}.  The constraints use the same
language used in the machine description (@pxref{Constraints,,Operand
Constraints, gcc.info, Using and Porting GCC}).
@end ifclear

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 output operands and separate
inputs.  The total number of operands is limited to ten or to the maximum
number of operands in any instruction pattern in the machine description,
whichever is greater.

If there are no output operands, and there are input operands, then there
must be two consecutive colons surrounding the place where the output
operands would go.

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 whether it is valid assembler input.  The
extended @code{asm} feature is most often used for machine instructions
that the compiler itself does not know exist.

The output operands must be write-only; GNU CC will assume that the values
in these operands before the instruction are dead and need not be
generated.  Extended asm does not support input-output or read-write
operands.  For this reason, the constraint character @samp{+}, which
indicates such an operand, may not be used.

When the assembler instruction has a read-write operand, or an operand
in which only some of the bits are to be changed, you must 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) @samp{combine} instruction with @code{bar} as its read-only
source operand and @code{foo} as its read-write destination:

@example
asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
@end example

@noindent
The constraint @samp{"0"} for operand 1 says that it must occupy the same
location as operand 0.  A digit in constraint is allowed only in an input
operand, and it must refer to an output operand.

Only a digit in the constraint can guarantee that one operand will be in
the same place as another.  The mere fact that @code{foo} 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:

@example
asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
@end example

Various optimizations or reloading could cause operands 0 and 1 to be in
different registers; GNU CC knows no reason not to do so.  For example, the
compiler might find a copy of the value of @code{foo} 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}'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 GNU CC can't tell that.

Some instructions clobber specific hard registers.  To describe this, write
a third colon after the input operands, followed by the names of the
clobbered hard registers (given as strings).  Here is a realistic example
for the Vax:

@example
asm volatile ("movc3 %0,%1,%2"
              : /* no outputs */
              : "g" (from), "g" (to), "g" (count)
              : "r0", "r1", "r2", "r3", "r4", "r5");
@end example

If you refer to a particular hardware register from the assembler code,
then you will probably have to list the register after the third colon
to tell the compiler that the register's value is modified.  In many
assemblers, the register names begin with @samp{%}; to produce one
@samp{%} in the assembler code, you must write @samp{%%} in the input.

If your assembler instruction can alter the condition code register,
add @samp{cc} to the list of clobbered registers.  GNU CC on some
machines represents the condition codes as a specific hardware
register; @samp{cc} serves to name this register.  On other machines,
the condition code is handled differently, and specifying @samp{cc}
has no effect.  But it is valid no matter what the machine.

If your assembler instruction modifies memory in an unpredicable
fashion, add @samp{memory} to the list of clobbered registers.
This will cause GNU CC to not keep memory values cached in
registers across the assembler instruction.

You can put multiple assembler instructions together in a single @code{asm}
template, separated either with newlines (written as @samp{\n}) or with
semicolons if the assembler allows such semicolons.  The GNU assembler
allows semicolons and all Unix assemblers seem to do so.  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 that the subroutine
@code{_foo} accepts arguments in registers 9 and 10:

@example
asm ("movl %0,r9;movl %1,r10;call _foo"
     : /* no outputs */
     : "g" (from), "g" (to)
     : "r9", "r10");
@end example

@ifset INTERNALS
Unless an output operand has the @samp{&} constraint modifier, GNU CC may
allocate it in the same register as an unrelated input operand, on the
assumption that 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 @samp{&} for each output
operand that may not overlap an input.
@xref{Modifiers}.
@end ifset
@ifclear INTERNALS
Unless an output operand has the @samp{&} constraint modifier, GNU CC may
allocate it in the same register as an unrelated input operand, on the
assumption that 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 @samp{&} for each output
operand that may not overlap an input.
@xref{Modifiers,,Constraint Modifier Characters,gcc.info,Using and
Porting GCC}.
@end ifclear

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} construct, as follows:

@example
asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
     : "g" (result)
     : "g" (input));
@end example

@noindent
This assumes your assembler supports local labels, as the GNU assembler
and most Unix assemblers do.

@cindex macros containing @code{asm}
Usually the most convenient way to use these @code{asm} instructions is to
encapsulate them in macros that look like functions.  For example,

@example
#define sin(x)       \
(@{ double __value, __arg = (x);   \
   asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
   __value; @})
@end example

@noindent
Here the variable @code{__arg} is used to make sure that the instruction
operates on a proper @code{double} value, and to accept only those
arguments @code{x} which can convert automatically to a @code{double}.

Another way to make sure the instruction operates on the correct data type
is to use a cast in the @code{asm}.  This is different from using a
variable @code{__arg} in that it converts more different types.  For
example, if the desired type were @code{int}, casting the argument to
@code{int} would accept a pointer with no complaint, while assigning the
argument to an @code{int} variable named @code{__arg} would warn about
using a pointer unless the caller explicitly casts it.

If an @code{asm} has output operands, GNU CC assumes for optimization
purposes that the instruction has no side effects except to change the
output operands.  This does not mean that 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.

You can prevent an @code{asm} instruction from being deleted, moved
significantly, or combined, by writing the keyword @code{volatile} after
the @code{asm}.  For example:

@example
#define set_priority(x)  \
asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
@end example

@noindent
An instruction without output operands will not be deleted or moved
significantly, regardless, unless it is unreachable.

Note that even a volatile @code{asm} 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}
instructions to remain perfectly consecutive.  If you want consecutive
output, use a single @code{asm}.

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 ``store'' 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 ``test'' and
``compare'' instructions because they don't have any output operands.

If you are writing a header file that should be includable in ANSI C
programs, write @code{__asm__} instead of @code{asm}.  @xref{Alternate
Keywords}.

@node Asm Labels
@section Controlling Names Used in Assembler Code
@cindex assembler names for identifiers
@cindex names used in assembler code
@cindex identifiers, names in assembler code

You can specify the name to be used in the assembler code for a C
function or variable by writing the @code{asm} (or @code{__asm__})
keyword after the declarator as follows:

@example
int foo asm ("myfoo") = 2;
@end example

@noindent
This specifies that the name to be used for the variable @code{foo} in
the assembler code should be @samp{myfoo} rather than the usual
@samp{_foo}.

On systems where an underscore is normally prepended to the name of a C
function or variable, this feature allows you to define names for the
linker that do not start with an underscore.

You cannot use @code{asm} in this way in a function @emph{definition}; but
you can get the same effect by writing a declaration for the function
before its definition and putting @code{asm} there, like this:

@example
extern func () asm ("FUNC");

func (x, y)
     int x, y;
@dots{}
@end example

It is up to you to make sure that the assembler names you choose do not
conflict with any other assembler symbols.  Also, you must not use a
register name; that would produce completely invalid assembler code.  GNU
CC does not as yet have the ability to store static variables in registers.
Perhaps that will be added.

@node Explicit Reg Vars
@section Variables in Specified Registers
@cindex explicit register variables
@cindex variables in specified registers
@cindex specified registers
@cindex registers, global allocation

GNU C allows you to put a few global variables into specified hardware
registers.  You can also specify the register in which an ordinary
register variable should be allocated.

@itemize @bullet
@item
Global register variables reserve registers throughout the program.
This may be useful in programs such as programming language
interpreters which have a couple of global variables that are accessed
very often.

@item
Local register variables in specific registers do not reserve the
registers.  The compiler's data flow analysis is capable of determining
where the specified registers contain live values, and where they are
available for other uses.

These local variables are sometimes convenient for use with the extended
@code{asm} feature (@pxref{Extended Asm}), if you want to write one
output of the assembler instruction directly into a particular register.
(This will work provided the register you specify fits the constraints
specified for that operand in the @code{asm}.)
@end itemize

@menu
* Global Reg Vars::
* Local Reg Vars::
@end menu

@node Global Reg Vars
@subsection Defining Global Register Variables
@cindex global register variables
@cindex registers, global variables in

You can define a global register variable in GNU C like this:

@example
register int *foo asm ("a5");
@end example

@noindent
Here @code{a5} is the name of the register which should be used.  Choose a
register which is normally saved and restored by function calls on your
machine, so that library routines will not clobber it.

Naturally the register name is cpu-dependent, so you would need to
conditionalize your program according to cpu type.  The register
@code{a5} would be a good choice on a 68000 for a variable of pointer
type.  On machines with register windows, be sure to choose a ``global''
register that is not affected magically by the function call mechanism.

In addition, operating systems on one type of cpu may differ in how they
name the registers; then you would need additional conditionals.  For
example, some 68000 operating systems call this register @code{%a5}.

Eventually there may be a way of asking the compiler to choose a register
automatically, but first we need to figure out how it should choose and
how to enable you to guide the choice.  No solution is evident.

Defining a global register variable in a certain register reserves that
register entirely for this use, at least within the current compilation.
The register will not be allocated for any other purpose in the functions
in the current compilation.  The register will not be saved and restored by
these functions.  Stores into this register are never deleted even if they
would appear to be dead, but references may be deleted or moved or
simplified.

It is not safe to access the global register variables from signal
handlers, or from more than one thread of control, because the system
library routines may temporarily use the register for other things (unless
you recompile them specially for the task at hand).

@cindex @code{qsort}, and global register variables
It is not safe for one function that uses a global register variable to
call another such function @code{foo} by way of a third function
@code{lose} that was compiled without knowledge of this variable (i.e. in a
different source file in which the variable wasn't declared).  This is
because @code{lose} might save the register and put some other value there.
For example, you can't expect a global register variable to be available in
the comparison-function that you pass to @code{qsort}, since @code{qsort}
might have put something else in that register.  (If you are prepared to
recompile @code{qsort} with the same global register variable, you can
solve this problem.)

If you want to rec