From 625e1353056d4f665a283c64d434a6fa05573d13 Mon Sep 17 00:00:00 2001 From: Richard Henderson Date: Sun, 10 Feb 2002 23:25:17 +0000 Subject: [PATCH] * doc/c-alpha.texi: New file. * doc/Makefile.am (CPU_DOCS): Add it. * doc/all.texi, doc/as.texinfo: Add hooks for Alpha. --- gas/ChangeLog | 6 + gas/doc/Makefile.am | 1 + gas/doc/Makefile.in | 1 + gas/doc/all.texi | 3 +- gas/doc/as.texinfo | 24 ++- gas/doc/c-alpha.texi | 396 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 426 insertions(+), 5 deletions(-) create mode 100644 gas/doc/c-alpha.texi diff --git a/gas/ChangeLog b/gas/ChangeLog index 5d56137d27c..a9f7ecb7cb3 100644 --- a/gas/ChangeLog +++ b/gas/ChangeLog @@ -1,3 +1,9 @@ +2002-02-10 Richard Henderson + + * doc/c-alpha.texi: New file. + * doc/Makefile.am (CPU_DOCS): Add it. + * doc/all.texi, doc/as.texinfo: Add hooks for Alpha. + 2002-02-09 Richard Henderson * config/tc-alpha.c (O_samegp): New. diff --git a/gas/doc/Makefile.am b/gas/doc/Makefile.am index a47dbe5882e..a526dded139 100644 --- a/gas/doc/Makefile.am +++ b/gas/doc/Makefile.am @@ -25,6 +25,7 @@ asconfig.texi: $(CONFIG).texi CPU_DOCS = \ c-a29k.texi \ + c-alpha.texi \ c-arc.texi \ c-arm.texi \ c-d10v.texi \ diff --git a/gas/doc/Makefile.in b/gas/doc/Makefile.in index 1a03cd6d3fe..58e08e61122 100644 --- a/gas/doc/Makefile.in +++ b/gas/doc/Makefile.in @@ -136,6 +136,7 @@ info_TEXINFOS = as.texinfo gasp.texi CPU_DOCS = \ c-a29k.texi \ + c-alpha.texi \ c-arc.texi \ c-arm.texi \ c-d10v.texi \ diff --git a/gas/doc/all.texi b/gas/doc/all.texi index 2a8bbe18c21..0642dfdeede 100644 --- a/gas/doc/all.texi +++ b/gas/doc/all.texi @@ -1,4 +1,4 @@ -@c Copyright 1992, 1993, 1994, 1996, 1997, 1999, 2000, 2001 +@c Copyright 1992, 1993, 1994, 1996, 1997, 1999, 2000, 2001, 2002 @c Free Software Foundation, Inc. @c This file is part of the documentation for the GAS manual @@ -27,6 +27,7 @@ @c CPUs of interest @c ================ @set A29K +@set ALPHA @set ARC @set ARM @set CRIS diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo index 705fa464efb..26eab02976a 100644 --- a/gas/doc/as.texinfo +++ b/gas/doc/as.texinfo @@ -29,6 +29,7 @@ @set TARGET TARGET @set GENERIC @set A29K +@set ALPHA @set ARC @set ARM @set CRIS @@ -266,6 +267,14 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. @ifset A29K @c am29k has no machine-dependent assembler options @end ifset +@ifset ALPHA + +@emph{Target Alpha options:} + [@b{-m@var{cpu}}] + [@b{-mdebug} | @b{-no-mdebug}] + [@b{-relax}] [@b{-g}] [@b{-G@var{size}}] + [@b{-F}] [@b{-32addr}] +@end ifset @ifset ARC @emph{Target ARC options:} @@ -5586,6 +5595,9 @@ subject, see the hardware manufacturer's manual. @ifset A29K * AMD29K-Dependent:: AMD 29K Dependent Features @end ifset +@ifset ALPHA +* Alpha-Dependent:: Alpha Dependent Features +@end ifset @ifset ARC * ARC-Dependent:: ARC Dependent Features @end ifset @@ -5681,14 +5693,18 @@ subject, see the hardware manufacturer's manual. @c node and sectioning commands; hence the repetition of @chapter BLAH @c in both conditional blocks. -@ifset ARC -@include c-arc.texi -@end ifset - @ifset A29K @include c-a29k.texi @end ifset +@ifset ALPHA +@include c-alpha.texi +@end ifset + +@ifset ARC +@include c-arc.texi +@end ifset + @ifset ARM @include c-arm.texi @end ifset diff --git a/gas/doc/c-alpha.texi b/gas/doc/c-alpha.texi new file mode 100644 index 00000000000..f3c18884e4a --- /dev/null +++ b/gas/doc/c-alpha.texi @@ -0,0 +1,396 @@ +@c Copyright 2002 +@c Free Software Foundation, Inc. +@c This is part of the GAS manual. +@c For copying conditions, see the file as.texinfo. + +@ifset GENERIC +@page +@node Alpha-Dependent +@chapter Alpha Dependent Features +@end ifset + +@ifclear GENERIC +@node Machine Dependencies +@chapter Alpha Dependent Features +@end ifclear + +@cindex Alpha support +@menu +* Alpha Notes:: Notes +* Alpha Options:: Options +* Alpha Syntax:: Syntax +* Alpha Floating Point:: Floating Point +* Alpha Directives:: Alpha Machine Directives +* Alpha Opcodes:: Opcodes +@end menu + +@node Alpha Notes +@section Notes +@cindex Alpha notes +@cindex notes for Alpha + +The documentation here is primarily for the ELF object format. +@code{@value{AS}} also supports the ECOFF and EVAX formats, but +features specific to these formats are not yet documented. + +@node Alpha Options +@section Options +@cindex Alpha options +@cindex options for Alpha + +@table @option +@cindex @code{-m@var{cpu}} command line option, Alpha +@item -m@var{cpu} +This option specifies the target processor. If an attempt is made to +assemble an instruction which will not execute on the target processor, +the assembler may either expand the instruction as a macro or issue an +error message. This option is equivalent to the @code{.arch} directive. + +The following processor names are recognized: +@code{21064}, +@code{21064a}, +@code{21066}, +@code{21068}, +@code{21164}, +@code{21164a}, +@code{21164pc}, +@code{21264}, +@code{ev4}, +@code{ev5}, +@code{lca45}, +@code{ev5}, +@code{ev56}, +@code{pca56}, +@code{ev6}. +The special name @code{all} may be used to allow the assembler to accept +instructions valid for any Alpha processor. + +In order to support existing practice in OSF/1 with respect to @code{.arch}, +and existing practice within @command{MILO} (the Linux ARC bootloader), the +numbered processor names (e.g.@: 21064) enable the processor-specific PALcode +instructions, while the ``electro-vlasic'' names (e.g.@: @code{ev4}) do not. + +@cindex @code{-mdebug} command line option, Alpha +@cindex @code{-no-mdebug} command line option, Alpha +@item -mdebug +@itemx -no-mdebug +Enables or disables the generation of @code{.mdebug} encapsulation for +stabs directives and procedure descriptors. The default is to automatically +enable @code{.mdebug} when the first stabs directive is seen. + +@cindex @code{-relax} command line option, Alpha +@item -relax +This option forces all relocations to be put into the object file, instead +of saving space and resolving some relocations at assembly time. Note that +this option does not propagate all symbol arithmetic into the object file, +because not all symbol arithmetic can be represented. However, the option +can still be useful in specific applications. + +@cindex @code{-g} command line option, Alpha +@item -g +This option is used when the compiler generates debug information. When +@command{gcc} is using @command{mips-tfile} to generate debug +information for ECOFF, local labels must be passed through to the object +file. Otherwise this option has no effect. + +@cindex @code{-G} command line option, Alpha +@item -G@var{size} +A local common symbol larger than @var{size} is placed in @code{.bss}, +while smaller symbols are placed in @code{.sbss}. + +@cindex @code{-F} command line option, Alpha +@cindex @code{-32addr} command line option, Alpha +@item -F +@itemx -32addr +These options are ignored for backward compatibility. +@end table + +@cindex Alpha Syntax +@node Alpha Syntax +@section Syntax +The assembler syntax closely follow the Alpha Reference Manual; +assembler directives and general syntax closely follow the OSF/1 and +OpenVMS syntax, with a few differences for ELF. + +@menu +* Alpha-Chars:: Special Characters +* Alpha-Regs:: Register Names +* Alpha-Relocs:: Relocations +@end menu + +@node Alpha-Chars +@subsection Special Characters + +@cindex line comment character, Alpha +@cindex Alpha line comment character +@samp{#} is the line comment character. + +@cindex line separator, Alpha +@cindex statement separator, Alpha +@cindex Alpha line separator +@samp{;} can be used instead of a newline to separate statements. + +@node Alpha-Regs +@subsection Register Names +@cindex Alpha registers +@cindex register names, Alpha + +The 32 integer registers are refered to as @samp{$@var{n}} or +@samp{$r@var{n}}. In addition, registers 15, 28, 29, and 30 may +be refered to by the symbols @samp{$fp}, @samp{$at}, @samp{$gp}, +and @samp{$sp} respectively. + +The 32 floating-point registers are refered to as @samp{$f@var{n}}. + +@node Alpha-Relocs +@subsection Relocations +@cindex Alpha relocations +@cindex relocations, Alpha + +Some of these relocations are available for ECOFF, but mostly +only for ELF. They are modeled after the relocation format +introduced in Digial Unix 4.0, but there are additions. + +The format is @samp{!@var{tag}} or @samp{!@var{tag}!@var{number}} +where @var{tag} is the name of the relocation. In some cases +@var{number} is used to relate specific instructions. + +The relocation is placed at the end of the instruction like so: + +@example +ldah $0,a($29) !gprelhigh +lda $0,a($0) !gprellow +ldq $1,b($29) !literal!100 +ldl $2,0($1) !lituse_base!100 +@end example + +@table @code +@item !literal +@itemx !literal!@var{N} +Used with an @code{ldq} instruction to load the address of a symbol +from the GOT. + +A sequence number @var{N} is optional, and if present is used to pair +@code{lituse} relocations with this @code{literal} relocation. The +@code{lituse} relocations are used by the linker to optimize the code +based on the final location of the symbol. + +Note that these optimizations are dependent on the data flow of the +program. Therefore, if @emph{any} @code{lituse} is paired with a +@code{literal} relocation, then @emph{all} uses of the register set by +the @code{literal} instruction must also be marked with @code{lituse} +relocations. This is because the original @code{literal} instruction +may be deleted or transformed into another instruction. + +Also note that there may be a one-to-many relationship between +@code{literal} and @code{lituse}, but not a many-to-one. That is, if +there are two code paths that load up the same address and feed the +value to a single use, then the use may not use a @code{lituse} +relocation. + +@item !lituse_base!@var{N} +Used with any memory format instruction (e.g.@: @code{ldl}) to indicate +that the literal is used for an address load. The offset field of the +instruction must be zero. During relaxation, the code may be altered +to use a gp-relative load. + +@item !lituse_jsr!@var{N} +Used with a register branch format instruction (e.g.@: @code{jsr}) to +indicate that the literal is used for a call. During relaxation, the +code may be altered to use a direct branch (e.g.@: @code{bsr}). + +@item !lituse_bytoff!@var{N} +Used with a byte mask instruction (e.g.@: @code{extbl}) to indicate +that only the low 3 bits of the address are relevant. During relaxation, +the code may be altered to use an immediate instead of a register shift. + +@item !lituse_addr!@var{N} +Used with any other instruction to indicate that the original address +is in fact used, and the original @code{ldq} instruction may not be +altered or deleted. This is useful in conjunction with @code{lituse_jsr} +to test whether a weak symbol is defined. + +@example +ldq $27,foo($29) !literal!1 +beq $27,is_undef !lituse_addr!1 +jsr $26,($27),foo !lituse_jsr!1 +@end example + +@item !gpdisp!@var{N} +Used with @code{ldah} and @code{lda} to load the GP from the current +address, a-la the @code{ldgp} macro. The source register for the +@code{ldah} instruction must contain the address of the @code{ldah} +instruction. There must be exactly one @code{lda} instruction paired +with the @code{ldah} instruction, though it may appear anywhere in +the instruction stream. The immediate operands must be zero. + +@example +bsr $26,foo +ldah $29,0($26) !gpdisp!1 +lda $29,0($29) !gpdisp!1 +@end example + +@item !gprelhigh +Used with an @code{ldah} instruction to add the high 16 bits of a +32-bit displacement from the GP. + +@item !gprellow +Used with any memory format instruction to add the low 16 bits of a +32-bit displacement from the GP. + +@item !gprel +Used with any memory format instruction to add a 16-bit displacement +from the GP. + +@item !samegp +Used with any branch format instruction to skip the GP load at the +target address. The referenced symbol must have the same GP as the +source object file, and it must be declared to either not use @code{$27} +or perform a standard GP load in the first two instructions via the +@code{.prologue} directive. +@end table + +@node Alpha Floating Point +@section Floating Point +@cindex floating point, Alpha (@sc{ieee}) +@cindex Alpha floating point (@sc{ieee}) +The Alpha family uses both @sc{ieee} and VAX floating-point numbers. + +@node Alpha Directives +@section Alpha Assembler Directives + +@command{@value{AS}} for the Alpha supports many additional directives for +compatibility with the native assembler. This section describes them only +briefly. + +@cindex Alpha-only directives +These are the additional directives in @code{@value{AS}} for the Alpha: + +@table @code +@item .arch @var{cpu} +Specifies the target processor. This is equivalent to the +@option{-m@var{cpu}} command-line option. @xref{Alpha Options, Options}, +for a list of values for @var{cpu}. + +@item .ent @var{function}[, @var{n}] +Mark the beginning of @var{function}. An optional number may follow for +compatibility with the OSF/1 assembler, but is ignored. When generating +@code{.mdebug} information, this will create a procedure descriptor for +the function. In ELF, it will mark the symbol as a function a-la the +generic @code{.type} directive. + +@item .end @var{function} +Mark the end of @var{function}. In ELF, it will set the size of the symbol +a-la the generic @code{.size} directive. + +@item .mask @var{mask}, @var{offset} +Indicate which of the integer registers are saved in the current +function's stack frame. @var{mask} is interpreted a bit mask in which +bit @var{n} set indicates that register @var{n} is saved. The registers +are saved in a block located @var{offset} bytes from the @dfn{canonical +frame address} (CFA) which is the value of the stack pointer on entry to +the function. The registers are saved sequentially, except that the +return address register (normally @code{$26}) is saved first. + +This and the other directives that describe the stack frame are +currently only used when generating @code{.mdebug} information. They +may in the future be used to generate DWARF2 @code{.debug_frame} unwind +information for hand written assembly. + +@item .fmask @var{mask}, @var{offset} +Indicate which of the floating-point registers are saved in the current +stack frame. The @var{mask} and @var{offset} parameters are interpreted +as with @code{.mask}. + +@item .frame @var{framereg}, @var{frameoffset}, @var{retreg}[, @var{argoffset}] +Describes the shape of the stack frame. The frame pointer in use is +@var{framereg}; normally this is either @code{$fp} or @code{$sp}. The +frame pointer is @var{frameoffset} bytes below the CFA. The return +address is initially located in @var{retreg} until it is saved as +indicated in @code{.mask}. For compatibility with OSF/1 an optional +@var{argoffset} parameter is accepted and ignored. It is believed to +indicate the offset from the CFA to the saved argument registers. + +@item .prologue @var{n} +Indicate that the stack frame is set up and all registers have been +spilled. The argument @var{n} indicates whether and how the function +uses the incoming @dfn{procedure vector} (the address of the called +function) in @code{$27}. 0 indicates that @code{$27} is not used; 1 +indicates that the first two instructions of the function use @code{$27} +to perform a load of the GP register; 2 indicates that @code{$27} is +used in some non-standard way and so the linker cannot elide the load of +the procedure vector during relaxation. + +@item .gprel32 @var{expression} +Computes the difference between the address in @var{expression} and the +GP for the current object file, and stores it in 4 bytes. In addition +to being smaller than a full 8 byte address, this also does not require +a dynamic relocation when used in a shared library. + +@item .t_floating @var{expression} +Stores @var{expression} as an @sc{ieee} double precision value. + +@item .s_floating @var{expression} +Stores @var{expression} as an @sc{ieee} single precision value. + +@item .f_floating @var{expression} +Stores @var{expression} as a VAX F format value. + +@item .g_floating @var{expression} +Stores @var{expression} as a VAX G format value. + +@item .d_floating @var{expression} +Stores @var{expression} as a VAX D format value. + +@item .set @var{feature} +Enables or disables various assembler features. Using the positive +name of the feature enables while using @samp{no@var{feature}} disables. + +@table @code +@item at +Indicates that macro expansions may clobber the @dfn{assembler +temporary} (@code{$at} or @code{$28}) register. Some macros may not be +expanded without this and will generate an error message if @code{noat} +is in effect. When @code{at} is in effect, a warning will be generated +if @code{$at} is used by the programmer. + +@item macro +Enables the expasion of macro instructions. Note that variants of real +instructions, such as @code{br label} vs @code{br $31,label} are +considered alternate forms and not macros. + +@item move +@itemx reorder +@itemx volatile +These control whether and how the assembler may re-order instructions. +Accepted for compatibility with the OSF/1 assembler, but @command{@value{AS}} +does not do instruction scheduling, so these features are ignored. +@end table +@end table + +The following directives are recognized for compatibility with the OSF/1 +assembler but are ignored. + +@example +.proc .aproc +.reguse .livereg +.option .aent +.ugen .eflag +.alias .noalias +@end example + +@node Alpha Opcodes +@section Opcodes +For detailed information on the Alpha machine instruction set, see the +@c Attempt to work around a very overfull hbox. +@iftex +Alpha Architecture Handbook located at +@smallfonts +@example +ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf +@end example +@textfonts +@end iftex +@ifnottex +@uref{ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf,Alpha Architecture Handbook}. +@end ifnottex -- 2.30.2