\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{--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
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
@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
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.
* 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.
@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
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}}
generated whenever the counter is greater than zero.
@node Nop
-@section @code{.nop}
+@section @code{.nop [@var{size}]}
@cindex @code{nop} directive
@cindex filling memory with no-op instructions
-This directive emits a single no-op instruction. 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. The
-instruction does affect the generation of DWARF debug line information.
+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}]}
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