X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=gas%2Fdoc%2Fc-alpha.texi;h=b0172328f3bed410674698c4d0cdefdb48884708;hb=4ab19f4c9b3c838cd904a501b77148a459420b4c;hp=f3c18884e4a3974edd1c9c26ed08869f8d7fed6d;hpb=625e1353056d4f665a283c64d434a6fa05573d13;p=binutils-gdb.git

diff --git a/gas/doc/c-alpha.texi b/gas/doc/c-alpha.texi
index f3c18884e4a..b0172328f3b 100644
--- a/gas/doc/c-alpha.texi
+++ b/gas/doc/c-alpha.texi
@@ -1,7 +1,7 @@
-@c Copyright 2002
-@c Free Software Foundation, Inc.
+@c Copyright (C) 2002-2022 Free Software Foundation, Inc.
 @c This is part of the GAS manual.
 @c For copying conditions, see the file as.texinfo.
+@c man end
 
 @ifset GENERIC
 @page
@@ -38,15 +38,16 @@ features specific to these formats are not yet documented.
 @cindex Alpha options
 @cindex options for Alpha
 
-@table @option
-@cindex @code{-m@var{cpu}} command line option, Alpha
+@c man begin OPTIONS
+@table @gcctabopt
+@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: 
+The following processor names are recognized:
 @code{21064},
 @code{21064a},
 @code{21066},
@@ -55,13 +56,17 @@ The following processor names are recognized:
 @code{21164a},
 @code{21164pc},
 @code{21264},
+@code{21264a},
+@code{21264b},
 @code{ev4},
 @code{ev5},
 @code{lca45},
 @code{ev5},
 @code{ev56},
 @code{pca56},
-@code{ev6}.
+@code{ev6},
+@code{ev67},
+@code{ev68}.
 The special name @code{all} may be used to allow the assembler to accept
 instructions valid for any Alpha processor.
 
@@ -70,15 +75,15 @@ 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
+@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
+@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
@@ -86,24 +91,34 @@ 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
+@cindex @code{-replace} command-line option, Alpha
+@cindex @code{-noreplace} command-line option, Alpha
+@item -replace
+@itemx -noreplace
+Enables or disables the optimization of procedure calls, both at assemblage
+and at link time.  These options are only available for VMS targets and
+@code{-replace} is the default.  See section 1.4.1 of the OpenVMS Linker
+Utility Manual.
+
+@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
+@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
+@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
+@c man end
 
 @cindex Alpha Syntax
 @node Alpha Syntax
@@ -123,7 +138,10 @@ OpenVMS syntax, with a few differences for ELF.
 
 @cindex line comment character, Alpha
 @cindex Alpha line comment character
-@samp{#} is the line comment character.
+@samp{#} is the line comment character.  Note that if @samp{#} is the
+first character on a line then it can also be a logical line number
+directive (@pxref{Comments}) or a preprocessor control
+command (@pxref{Preprocessing}).
 
 @cindex line separator, Alpha
 @cindex statement separator, Alpha
@@ -135,12 +153,12 @@ OpenVMS syntax, with a few differences for ELF.
 @cindex Alpha registers
 @cindex register names, Alpha
 
-The 32 integer registers are refered to as @samp{$@var{n}} or
+The 32 integer registers are referred 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},
+be referred 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}}.
+The 32 floating-point registers are referred to as @samp{$f@var{n}}.
 
 @node Alpha-Relocs
 @subsection Relocations
@@ -148,8 +166,8 @@ The 32 floating-point registers are refered to as @samp{$f@var{n}}.
 @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.
+only for ELF.  They are modeled after the relocation format
+introduced in Digital 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
@@ -199,6 +217,12 @@ 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_jsrdirect!@var{N}
+Similar to @code{lituse_jsr}, but also that this call cannot be vectored
+through a PLT entry.  This is useful for functions with special calling
+conventions which do not allow the normal call-clobbered registers to be
+clobbered.
+
 @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,
@@ -216,12 +240,25 @@ beq  $27,is_undef   !lituse_addr!1
 jsr  $26,($27),foo  !lituse_jsr!1
 @end example
 
+@item !lituse_tlsgd!@var{N}
+Used with a register branch format instruction to indicate that the
+literal is the call to @code{__tls_get_addr} used to compute the
+address of the thread-local storage variable whose descriptor was
+loaded with @code{!tlsgd!@var{N}}.
+
+@item !lituse_tlsldm!@var{N}
+Used with a register branch format instruction to indicate that the
+literal is the call to @code{__tls_get_addr} used to compute the
+address of the base of the thread-local storage block for the current
+module.  The descriptor for the module must have been loaded with
+@code{!tlsldm!@var{N}}.
+
 @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 
+with the @code{ldah} instruction, though it may appear anywhere in
 the instruction stream.  The immediate operands must be zero.
 
 @example
@@ -248,6 +285,47 @@ 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.
+
+@item !tlsgd
+@itemx !tlsgd!@var{N}
+Used with an @code{lda} instruction to load the address of a TLS
+descriptor for a symbol in the GOT.
+
+The sequence number @var{N} is optional, and if present it used to
+pair the descriptor load with both the @code{literal} loading the
+address of the @code{__tls_get_addr} function and the @code{lituse_tlsgd}
+marking the call to that function.
+
+For proper relaxation, both the @code{tlsgd}, @code{literal} and
+@code{lituse} relocations must be in the same extended basic block.
+That is, the relocation with the lowest address must be executed
+first at runtime.
+
+@item !tlsldm
+@itemx !tlsldm!@var{N}
+Used with an @code{lda} instruction to load the address of a TLS
+descriptor for the current module in the GOT.
+
+Similar in other respects to @code{tlsgd}.
+
+@item !gotdtprel
+Used with an @code{ldq} instruction to load the offset of the TLS
+symbol within its module's thread-local storage block.  Also known
+as the dynamic thread pointer offset or dtp-relative offset.
+
+@item !dtprelhi
+@itemx !dtprello
+@itemx !dtprel
+Like @code{gprel} relocations except they compute dtp-relative offsets.
+
+@item !gottprel
+Used with an @code{ldq} instruction to load the offset of the TLS
+symbol from the thread pointer.  Also known as the tp-relative offset.
+
+@item !tprelhi
+@itemx !tprello
+@itemx !tprel
+Like @code{gprel} relocations except they compute tp-relative offsets.
 @end table
 
 @node Alpha Floating Point
@@ -321,6 +399,18 @@ 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 .usepv @var{function}, @var{which}
+Used to indicate the use of the @code{$27} register, similar to
+@code{.prologue}, but without the other semantics of needing to
+be inside an open @code{.ent}/@code{.end} block.
+
+The @var{which} argument should be either @code{no}, indicating that
+@code{$27} is not used, or @code{std}, indicating that the first two
+instructions of the function perform a GP load.
+
+One might use this directive instead of @code{.prologue} if you are
+also using dwarf2 CFI directives.
+
 @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
@@ -355,7 +445,7 @@ 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
+Enables the expansion 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.