\input texinfo @c -*-Texinfo-*-
-@c Copyright (C) 1991-2020 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2021 Free Software Foundation, Inc.
@c UPDATE!! On future updates--
@c (1) check for new machine-dep cmdline options in
@c md_parse_option definitions in config/tc-*.c
This file documents the GNU Assembler "@value{AS}".
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2020 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2021 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991-2020 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2021 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
[@b{--listing-cont-lines}=@var{NUM}] [@b{--keep-locals}]
[@b{--no-pad-sections}]
[@b{-o} @var{objfile}] [@b{-R}]
- [@b{--hash-size}=@var{NUM}] [@b{--reduce-memory-overheads}]
[@b{--statistics}]
[@b{-v}] [@b{-version}] [@b{--version}]
[@b{-W}] [@b{--warn}] [@b{--fatal-warnings}] [@b{-w}] [@b{-x}]
[@b{--sectname-subst}] [@b{--size-check=[error|warning]}]
[@b{--elf-stt-common=[no|yes]}]
[@b{--generate-missing-build-notes=[no|yes]}]
+ [@b{--multibyte-handling=[allow|warn|warn-sym-only]}]
[@b{--target-help}] [@var{target-options}]
[@b{--}|@var{files} @dots{}]
@c
@emph{Target IP2K options:}
[@b{-mip2022}|@b{-mip2022ext}]
@end ifset
+@ifset LOONGARCH
+
+@emph{Target LOONGARCH options:}
+ [@b{-fpic}|@b{-fPIC}|@b{-fno-pic}]
+@end ifset
@ifset M32C
@emph{Target M32C options:}
[@b{-fpic}|@b{-fPIC}|@b{-fno-pic}]
[@b{-march}=@var{ISA}]
[@b{-mabi}=@var{ABI}]
+ [@b{-mlittle-endian}|@b{-mbig-endian}]
@end ifset
@ifset RL78
@itemx --gen-debug
Generate debugging information for each assembler source line using whichever
debug format is preferred by the target. This currently means either STABS,
-ECOFF or DWARF2.
+ECOFF or DWARF2. When the debug format is DWARF then a @code{.debug_info} and
+@code{.debug_line} section is only emitted when the assembly file doesn't
+generate one itself.
@item --gstabs
Generate stabs debugging information for each assembler line. This
This option is the same as the @option{--gdwarf-2} option, except that it
allows for the possibility of the generation of extra debug information as per
version 3 of the DWARF specification. Note - enabling this option does not
-guarantee the generation of any extra infortmation, the choice to do so is on a
+guarantee the generation of any extra information, the choice to do so is on a
per target basis.
@item --gdwarf-4
This option is the same as the @option{--gdwarf-2} option, except that it
allows for the possibility of the generation of extra debug information as per
version 4 of the DWARF specification. Note - enabling this option does not
-guarantee the generation of any extra infortmation, the choice to do so is on a
+guarantee the generation of any extra information, the choice to do so is on a
per target basis.
@item --gdwarf-5
This option is the same as the @option{--gdwarf-2} option, except that it
allows for the possibility of the generation of extra debug information as per
version 5 of the DWARF specification. Note - enabling this option does not
-guarantee the generation of any extra infortmation, the choice to do so is on a
+guarantee the generation of any extra information, the choice to do so is on a
per target basis.
@item --gdwarf-sections
Set the maximum number of lines printed in a listing for a single line of input
to @var{number} + 1.
+@item --multibyte-handling=allow
+@itemx --multibyte-handling=warn
+@itemx --multibyte-handling=warn-sym-only
+Controls how the assembler handles multibyte characters in the input. The
+default (which can be restored by using the @option{allow} argument) is to
+allow such characters without complaint. Using the @option{warn} argument will
+make the assembler generate a warning message whenever any multibyte character
+is encountered. Using the @option{warn-sym-only} argument will only cause a
+warning to be generated when a symbol is defined with a name that contains
+multibyte characters. (References to undefined symbols will not generate a
+warning).
+
@item --no-pad-sections
Stop the assembler for padding the ends of output sections to the alignment
of that section. The default is to pad the sections, but this can waste space
@item -R
Fold the data section into the text section.
-@item --hash-size=@var{number}
-Set the default size of GAS's hash tables to a prime number close to
-@var{number}. Increasing this value can reduce the length of time it takes the
-assembler to perform its tasks, at the expense of increasing the assembler's
-memory requirements. Similarly reducing this value can reduce the memory
-requirements at the expense of speed.
-
-@item --reduce-memory-overheads
-This option reduces GAS's memory requirements, at the expense of making the
-assembly processes slower. Currently this switch is a synonym for
-@samp{--hash-size=4051}, but in the future it may have other effects as well.
-
@ifset ELF
@item --sectname-subst
Honor substitution sequences in section names.
@item -EB | -EL
Select either big-endian (-EB) or little-endian (-EL) output.
@item -mcode-density
-Enable Code Density extenssion instructions.
+Enable Code Density extension instructions.
@end table
@end ifset
@end ifset
@c man end
+@ifset LOONGARCH
+
+@ifclear man
+@xref{LoongArch-Options}, for the options available when @value{AS} is configured
+for a LoongArch processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+LoongArch processor.
+@c man end
+@c man begin INCLUDE
+@include c-loongarch.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
@ifset METAG
@ifclear man
@end ifset
No symbol may begin with a digit. Case is significant.
There is no length limit; all characters are significant. Multibyte characters
-are supported. Symbols are delimited by characters not in that set, or by the
-beginning of a file (since the source program must end with a newline, the end
-of a file is not a possible symbol delimiter). @xref{Symbols}.
+are supported, but note that the setting of the
+@option{--multibyte-handling} option might prevent their use. Symbols
+are delimited by characters not in that set, or by the beginning of a file
+(since the source program must end with a newline, the end of a file is not a
+possible symbol delimiter). @xref{Symbols}.
Symbol names may also be enclosed in double quote @code{"} characters. In such
cases any characters are allowed, except for the NUL character. If a double
-quote character is to be included in the symbol name it must be preceeded by a
+quote character is to be included in the symbol name it must be preceded by a
backslash @code{\} character.
@cindex length of symbols
Symbol names do not start with a digit. An exception to this rule is made for
Local Labels. See below.
-Multibyte characters are supported. To generate a symbol name containing
+Multibyte characters are supported, but note that the setting of the
+@option{multibyte-handling} option might prevent their use.
+To generate a symbol name containing
multibyte characters enclose it within double quotes and use escape codes. cf
@xref{Strings}. Generating a multibyte symbol name from a label is not
currently supported.
+Since multibyte symbol names are unusual, and could possibly be used
+maliciously, @command{@value{AS}} provides a command line option
+(@option{--multibyte-handling=warn-sym-only}) which can be used to generate a
+warning message whenever a symbol name containing multibyte characters is defined.
+
Each symbol has exactly one name. Each name in an assembly language program
refers to exactly one symbol. You may use that symbol name any number of times
in a program.
* Altmacro:: @code{.altmacro}
* Ascii:: @code{.ascii "@var{string}"}@dots{}
* Asciz:: @code{.asciz "@var{string}"}@dots{}
+* Attach_to_group:: @code{.attach_to_group @var{name}}
* Balign:: @code{.balign [@var{abs-expr}[, @var{abs-expr}]]}
+* Bss:: @code{.bss @var{subsection}}
* Bundle directives:: @code{.bundle_align_mode @var{abs-expr}}, etc
* Byte:: @code{.byte @var{expressions}}
* CFI directives:: @code{.cfi_startproc [simple]}, @code{.cfi_endproc}, etc.
* MRI:: @code{.mri @var{val}}
* Noaltmacro:: @code{.noaltmacro}
* Nolist:: @code{.nolist}
+* Nop:: @code{.nop}
* Nops:: @code{.nops @var{size}[, @var{control}]}
* Octa:: @code{.octa @var{bignums}}
* Offset:: @code{.offset @var{loc}}
* Text:: @code{.text @var{subsection}}
* Title:: @code{.title "@var{heading}"}
+@ifset ELF
+* Tls_common:: @code{.tls_common @var{symbol}, @var{length}[, @var{alignment}]}
+@end ifset
@ifset COFF-ELF
* Type:: @code{.type <@var{int} | @var{name} , @var{type description}>}
@end ifset
@ifclear no-space-dir
* Zero:: @code{.zero @var{size}}
@end ifclear
-@ifset ELF
* 2byte:: @code{.2byte @var{expressions}}
* 4byte:: @code{.4byte @var{expressions}}
* 8byte:: @code{.8byte @var{bignums}}
-@end ifset
* Deprecated:: Deprecated Directives
@end menu
@cindex zero-terminated strings
@cindex null-terminated strings
@code{.asciz} is just like @code{.ascii}, but each string is followed by
-a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
+a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. Note that
+multiple string arguments not separated by commas will be concatenated
+together and only one final zero byte will be stored.
+
+@node Attach_to_group
+@section @code{.attach_to_group @var{name}}
+Attaches the current section to the named group. This is like declaring
+the section with the @code{G} attribute, but can be done after the section
+has been created. Note if the group section does not exist at the point that
+this directive is used then it will be created.
@node Balign
@section @code{.balign[wl] [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]}
the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
undefined.
+@node Bss
+@section @code{.bss @var{subsection}}
+@cindex @code{bss} directive
+
+@code{.bss} tells @command{@value{AS}} to assemble the following statements
+onto the end of the bss section.
+@ifset ELF
+For ELF based targets an optional @var{subsection} expression (which must
+evaluate to a positive integer) can be provided. In this case the statements
+are appended to the end of the indicated bss subsection.
+@end ifset
+
@node Bundle directives
@section Bundle directives
@subsection @code{.bundle_align_mode @var{abs-expr}}
@item @samp{.l}
Emits 4-byte values.
@item @samp{.p}
-Emits 12-byte values.
+Emits values with size matching packed-decimal floating-point ones.
@item @samp{.s}
Emits 4-byte values.
@item @samp{.w}
Emits 2-byte values.
@item @samp{.x}
-Emits 12-byte values.
+Emits values with size matching long double precision floating-point ones.
@end table
Note - unlike the @code{.dcb} directive the @samp{.d}, @samp{.s} and @samp{.x}
information, and thus the user must know the exact indices that table
entries will have.
-If DWARF-5 support has been enabled via the @option{-gdwarf-5} option then
-an extended version of the @code{file} is also allowed:
+If DWARF5 support has been enabled via the @option{-gdwarf-5} option then
+an extended version of @code{.file} is also allowed:
@smallexample
.file @var{fileno} [@var{dirname}] @var{filename} [md5 @var{value}]
@end smallexample
With this version a separate directory name is allowed, although if this is
-used then @var{filename} should not contain any directory components. In
-addtion an md5 hash value of the contents of @var{filename} can be provided.
-This will be stored in the the file table as well, and can be used by tools
-reading the debug information to verify that the contents of the source file
-match the contents of the compiled file.
+used then @var{filename} should not contain any directory component, except
+for @var{fileno} equal to 0: in this case, @var{dirname} is expected to be
+the current directory and @var{filename} the currently processed file, and
+the latter need not be located in the former. In addtion an MD5 hash value
+of the contents of @var{filename} can be provided. This will be stored in
+the the file table as well, and can be used by tools reading the debug
+information to verify that the contents of the source file match the
+contents of the compiled file.
@node Fill
@section @code{.fill @var{repeat} , @var{size} , @var{value}}
number matrix corresponding to the immediately following assembly
instruction. The @var{fileno}, @var{lineno}, and optional @var{column}
arguments will be applied to the @code{.debug_line} state machine before
-the row is added.
+the row is added. It is an error for the input assembly file to generate
+a non-empty @code{.debug_line} and also use @code{loc} directives.
The @var{options} are a sequence of the following tokens in any order:
counter, and @code{.nolist} decrements it. Assembly listings are
generated whenever the counter is greater than zero.
+@node Nop
+@section @code{.nop [@var{size}]}
+
+@cindex @code{nop} directive
+@cindex filling memory with no-op instructions
+This directive emits no-op instructions. It is provided on all architectures,
+allowing the creation of architecture neutral tests involving actual code. The
+size of the generated instruction is target specific, but if the optional
+@var{size} argument is given and resolves to an absolute positive value at that
+point in assembly (no forward expressions allowed) then the fewest no-op
+instructions are emitted that equal or exceed a total @var{size} in bytes.
+@code{.nop} does affect the generation of DWARF debug line information.
+Some targets do not support using @code{.nop} with @var{size}.
+
@node Nops
@section @code{.nops @var{size}[, @var{control}]}
@cindex @code{nops} directive
@cindex filling memory with no-op instructions
-This directive emits @var{size} bytes filled with no-op instructions.
-@var{size} is absolute expression, which must be a positve value.
-@var{control} controls how no-op instructions should be generated. If
-the comma and @var{control} are omitted, @var{control} is assumed to be
-zero.
-
-Note: For Intel 80386 and AMD x86-64 targets, @var{control} specifies
-the size limit of a no-op instruction. The valid values of @var{control}
-are between 0 and 4 in 16-bit mode, between 0 and 7 when tuning for
-older processors in 32-bit mode, between 0 and 11 in 64-bit mode or when
-tuning for newer processors in 32-bit mode. When 0 is used, the no-op
+This directive emits no-op instructions. It is specific to the Intel 80386 and
+AMD x86-64 targets. It takes a @var{size} argument and generates @var{size}
+bytes of no-op instructions. @var{size} must be absolute and positive. These
+bytes do not affect the generation of DWARF debug line information.
+
+The optional @var{control} argument specifies a size limit for a single no-op
+instruction. If not provided then a value of 0 is assumed. The valid values
+of @var{control} are between 0 and 4 in 16-bit mode, between 0 and 7 when
+tuning for older processors in 32-bit mode, between 0 and 11 in 64-bit mode or
+when tuning for newer processors in 32-bit mode. When 0 is used, the no-op
instruction size limit is set to the maximum supported size.
@node Octa
section is used for thread-local-storage
@item ?
section is a member of the previously-current section's group, if any
+@item R
+retained section (apply SHF_GNU_RETAIN to prevent linker garbage
+collection, GNU ELF extension)
@item @code{<number>}
a numeric value indicating the bits to be set in the ELF section header's flags
field. Note - if one or more of the alphabetic characters described above is
flags can be added to an already defined section. The @code{.interp},
@code{.strtab} and @code{.symtab} sections can have the allocate flag
(@code{a}) set after they are initially defined, and the @code{.note-GNU-stack}
-section may have the executable (@code{x}) flag added.
+section may have the executable (@code{x}) flag added. Also note that the
+@code{.attach_to_group} directive can be used to add a section to a group even
+if the section was not originally declared to be part of that group.
The optional @var{type} argument may contain one of the following constants:
must be present along with an additional field like this:
@smallexample
-.section @var{name},"@var{flags}"o,@@@var{type},@var{SymbolName}
+.section @var{name},"@var{flags}"o,@@@var{type},@var{SymbolName}|@var{SectionIndex}
@end smallexample
The @var{SymbolName} field specifies the symbol name which the section
-references.
+references. Alternatively a numeric @var{SectionIndex} can be provided. This
+is not generally a good idea as section indicies are rarely known at assembly
+time, but the facility is provided for testing purposes. An index of zero is
+allowed. It indicates that the linked-to section has already been discarded.
Note: If both the @var{M} and @var{o} flags are present, then the fields
for the Merge flag should come first, like this:
This directive affects subsequent pages, as well as the current page if
it appears within ten lines of the top of a page.
+@ifset ELF
+@node Tls_common
+@section @code{.tls_common @var{symbol}, @var{length}[, @var{alignment}]}
+
+@cindex @code{tls_common} directive
+This directive behaves in the same way as the @code{.comm} directive
+(@pxref{Comm}) except that @var{symbol} has type of STT_TLS instead of
+STT_OBJECT.
+@end ifset
+
@ifset COFF-ELF
@node Type
@section @code{.type}
instead of zero. Using @samp{.zero} in this way would be confusing however.
@end ifclear
-@ifset ELF
@node 2byte
@section @code{.2byte @var{expression} [, @var{expression}]*}
@cindex @code{2byte} directive
values. As a result of this, if relocations are generated, they may be
different from those used for inserting values with a guaranteed alignment.
-This directive is only available for ELF targets,
-
@node 4byte
@section @code{.4byte @var{expression} [, @var{expression}]*}
@cindex @code{4byte} directive
Like the @option{.2byte} directive, except that it inserts unaligned, eight
byte long bignum values into the output.
-@end ifset
-
@node Deprecated
@section Deprecated Directives
@ifset IP2K
* IP2K-Dependent:: IP2K Dependent Features
@end ifset
+@ifset LOONGARCH
+* LoongArch-Dependent:: LoongArch Dependent Features
+@end ifset
@ifset LM32
* LM32-Dependent:: LM32 Dependent Features
@end ifset
@include c-lm32.texi
@end ifset
+@ifset LOONGARCH
+@include c-loongarch.texi
+@end ifset
+
@ifset M32C
@include c-m32c.texi
@end ifset
projects / binutils-gdb.git / blobdiff