\input texinfo @c -*-Texinfo-*-
-@c Copyright (C) 1991-2019 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2023 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-2019 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2023 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-2019 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2023 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
@c to be limited to one line for the header.
@smallexample
@c man begin SYNOPSIS
-@value{AS} [@b{-a}[@b{cdghlns}][=@var{file}]] [@b{--alternate}] [@b{-D}]
- [@b{--compress-debug-sections}] [@b{--nocompress-debug-sections}]
+@value{AS} [@b{-a}[@b{cdghlns}][=@var{file}]]
+ [@b{--alternate}]
+ [@b{--compress-debug-sections}] [@b{--nocompress-debug-sections}]
+ [@b{-D}]
+ [@b{--dump-config}]
[@b{--debug-prefix-map} @var{old}=@var{new}]
- [@b{--defsym} @var{sym}=@var{val}] [@b{-f}] [@b{-g}] [@b{--gstabs}]
- [@b{--gstabs+}] [@b{--gdwarf-2}] [@b{--gdwarf-sections}]
- [@b{--help}] [@b{-I} @var{dir}] [@b{-J}]
- [@b{-K}] [@b{-L}] [@b{--listing-lhs-width}=@var{NUM}]
- [@b{--listing-lhs-width2}=@var{NUM}] [@b{--listing-rhs-width}=@var{NUM}]
- [@b{--listing-cont-lines}=@var{NUM}] [@b{--keep-locals}]
+ [@b{--defsym} @var{sym}=@var{val}]
+ [@b{--elf-stt-common=[no|yes]}]
+ [@b{--emulation}=@var{name}]
+ [@b{-f}]
+ [@b{-g}] [@b{--gstabs}] [@b{--gstabs+}]
+ [@b{--gdwarf-<N>}] [@b{--gdwarf-sections}]
+ [@b{--gdwarf-cie-version}=@var{VERSION}]
+ [@b{--generate-missing-build-notes=[no|yes]}]
+ [@b{--gsframe}]
+ [@b{--hash-size}=@var{N}]
+ [@b{--help}] [@b{--target-help}]
+ [@b{-I} @var{dir}]
+ [@b{-J}]
+ [@b{-K}]
+ [@b{--keep-locals}]
+ [@b{-L}]
+ [@b{--listing-lhs-width}=@var{NUM}]
+ [@b{--listing-lhs-width2}=@var{NUM}]
+ [@b{--listing-rhs-width}=@var{NUM}]
+ [@b{--listing-cont-lines}=@var{NUM}]
+ [@b{--multibyte-handling=[allow|warn|warn-sym-only]}]
[@b{--no-pad-sections}]
[@b{-o} @var{objfile}] [@b{-R}]
- [@b{--hash-size}=@var{NUM}] [@b{--reduce-memory-overheads}]
+ [@b{--sectname-subst}]
+ [@b{--size-check=[error|warning]}]
[@b{--statistics}]
[@b{-v}] [@b{-version}] [@b{--version}]
[@b{-W}] [@b{--warn}] [@b{--fatal-warnings}] [@b{-w}] [@b{-x}]
[@b{-Z}] [@b{@@@var{FILE}}]
- [@b{--sectname-subst}] [@b{--size-check=[error|warning]}]
- [@b{--elf-stt-common=[no|yes]}]
- [@b{--generate-missing-build-notes=[no|yes]}]
- [@b{--target-help}] [@var{target-options}]
+ [@var{target-options}]
[@b{--}|@var{files} @dots{}]
@c
@c man end
@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
[@b{--[no-]transform}]
[@b{--rename-section} @var{oldname}=@var{newname}]
[@b{--[no-]trampolines}]
+ [@b{--abi-windowed}|@b{--abi-call0}]
@end ifset
@ifset Z80
@emph{Target Z80 options:}
- [@b{-z80}] [@b{-r800}]
- [@b{ -ignore-undocumented-instructions}] [@b{-Wnud}]
- [@b{ -ignore-unportable-instructions}] [@b{-Wnup}]
- [@b{ -warn-undocumented-instructions}] [@b{-Wud}]
- [@b{ -warn-unportable-instructions}] [@b{-Wup}]
- [@b{ -forbid-undocumented-instructions}] [@b{-Fud}]
- [@b{ -forbid-unportable-instructions}] [@b{-Fup}]
+ [@b{-march=@var{CPU}@var{[-EXT]}@var{[+EXT]}}]
+ [@b{-local-prefix=}@var{PREFIX}]
+ [@b{-colonless}]
+ [@b{-sdcc}]
+ [@b{-fp-s=}@var{FORMAT}]
+ [@b{-fp-d=}@var{FORMAT}]
@end ifset
@ifset Z8000
@itemx --compress-debug-sections=zlib
@itemx --compress-debug-sections=zlib-gnu
@itemx --compress-debug-sections=zlib-gabi
+@itemx --compress-debug-sections=zstd
These options control how DWARF debug sections are compressed.
@option{--compress-debug-sections=none} is equivalent to
@option{--nocompress-debug-sections}.
@option{--compress-debug-sections=zlib} and
@option{--compress-debug-sections=zlib-gabi} are equivalent to
@option{--compress-debug-sections}.
-@option{--compress-debug-sections=zlib-gnu} compresses DWARF debug
-sections using zlib. The debug sections are renamed to begin with
-@samp{.zdebug}. Note if compression would make a given section
-@emph{larger} then it is not compressed nor renamed.
+@option{--compress-debug-sections=zlib-gnu} compresses DWARF debug sections
+using the obsoleted zlib-gnu format. The debug sections are renamed to begin
+with @samp{.zdebug}.
+@option{--compress-debug-sections=zstd} compresses DWARF debug
+sections using zstd. Note - if compression would actually make a section
+@emph{larger}, then it is not compressed nor renamed.
@end ifset
override this.
@item -D
-Ignored. This option is accepted for script compatibility with calls to
+Enable debugging in target specific backends, if supported. Otherwise ignored.
+Even if ignored, this option is accepted for script compatibility with calls to
other assemblers.
@item --debug-prefix-map @var{old}=@var{new}
value. The value of the symbol can be overridden inside a source file via the
use of a @code{.set} pseudo-op.
+@item --dump-config
+Displays how the assembler is configured and then exits.
+
+@ifset ELF
+@item --elf-stt-common=no
+@itemx --elf-stt-common=yes
+These options control whether the ELF assembler should generate common
+symbols with the @code{STT_COMMON} type. The default can be controlled
+by a configure option @option{--enable-elf-stt-common}.
+@end ifset
+
+@item --emulation=@var{name}
+If the assembler is configured to support multiple different target
+configurations then this option can be used to select the desired form.
+
@item -f
``fast''---skip whitespace and comment preprocessing (assume source is
compiler output).
@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
may help debugging assembler code, if the debugger can handle it. Note---this
option is only supported by some targets, not all of them.
+@item --gdwarf-3
+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 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 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 information, the choice to do so is on a
+per target basis.
+
@item --gdwarf-sections
Instead of creating a .debug_line section, create a series of
.debug_line.@var{foo} sections where @var{foo} is the name of the
then debug line section will still be called just @var{.debug_line} without any
suffix.
-@ifset ELF
-@item --size-check=error
-@itemx --size-check=warning
-Issue an error or warning for invalid ELF .size directive.
-
-@item --elf-stt-common=no
-@itemx --elf-stt-common=yes
-These options control whether the ELF assembler should generate common
-symbols with the @code{STT_COMMON} type. The default can be controlled
-by a configure option @option{--enable-elf-stt-common}.
+@item --gdwarf-cie-version=@var{version}
+Control which version of DWARF Common Information Entries (CIEs) are produced.
+When this flag is not specificed the default is version 1, though some targets
+can modify this default. Other possible values for @var{version} are 3 or 4.
+@ifset ELF
@item --generate-missing-build-notes=yes
@itemx --generate-missing-build-notes=no
These options control whether the ELF assembler should generate GNU Build
The default can be controlled by the @option{--enable-generate-build-notes}
configure option.
+@item --gsframe
+@itemx --gsframe
+Create @var{.sframe} section from CFI directives.
+
@end ifset
+@item --hash-size @var{N}
+Ignored. Supported for command line compatibility with other assemblers.
+
@item --help
Print a summary of the command-line options and exit.
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
+@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.
+Ignored. Supported for compatibility with tools that apss the same option to
+both the assembler and the linker.
@ifset ELF
@item --sectname-subst
@ifclear man
@xref{Section Name Substitutions,,@code{.section @var{name}}}.
@end ifclear
+
+@item --size-check=error
+@itemx --size-check=warning
+Issue an error or warning for invalid ELF .size directive.
@end ifset
@item --statistics
@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
@samp{arch3}), @samp{g6}, @samp{z900} (or @samp{arch5}), @samp{z990} (or
@samp{arch6}), @samp{z9-109}, @samp{z9-ec} (or @samp{arch7}), @samp{z10} (or
@samp{arch8}), @samp{z196} (or @samp{arch9}), @samp{zEC12} (or @samp{arch10}),
-@samp{z13} (or @samp{arch11}), or @samp{z14} (or @samp{arch12}).
+@samp{z13} (or @samp{arch11}), @samp{z14} (or @samp{arch12}), @samp{z15}
+(or @samp{arch13}), or @samp{z16} (or @samp{arch14}).
@item -mregnames
@itemx -mno-regnames
Allow or disallow symbolic names for registers.
@end ifset
-@c man begin OPTIONS
-
@ifset Z80
-The following options are available when @value{AS} is configured for
-a Z80 family processor.
-@table @gcctabopt
-@item -z80
-Assemble for Z80 processor.
-@item -r800
-Assemble for R800 processor.
-@item -ignore-undocumented-instructions
-@itemx -Wnud
-Assemble undocumented Z80 instructions that also work on R800 without warning.
-@item -ignore-unportable-instructions
-@itemx -Wnup
-Assemble all undocumented Z80 instructions without warning.
-@item -warn-undocumented-instructions
-@itemx -Wud
-Issue a warning for undocumented Z80 instructions that also work on R800.
-@item -warn-unportable-instructions
-@itemx -Wup
-Issue a warning for undocumented Z80 instructions that do not work on R800.
-@item -forbid-undocumented-instructions
-@itemx -Fud
-Treat all undocumented instructions as errors.
-@item -forbid-unportable-instructions
-@itemx -Fup
-Treat undocumented Z80 instructions that do not work on R800 as errors.
-@end table
-@end ifset
+@ifclear man
+@xref{Z80 Options}, for the options available when @value{AS} is configured
+for an Z80 processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for an
+Z80 processor.
@c man end
+@c man begin INCLUDE
+@include c-z80.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
@menu
* Manual:: Structure of this Manual
should find a fairly similar environment when you use it on another
architecture. Each version has much in common with the others,
including object file formats, most assembler directives (often called
-@dfn{pseudo-ops}) and assembler syntax.@refill
+@dfn{pseudo-ops}) and assembler syntax.
@cindex purpose of @sc{gnu} assembler
@command{@value{AS}} is primarily intended to assemble the output of the
@menu
* a:: -a[cdghlns] enable listings
* alternate:: --alternate enable alternate macro syntax
-* D:: -D for compatibility
+* D:: -D for compatibility and debugging
* f:: -f to work faster
* I:: -I for .include search path
@ifclear DIFF-TBL-KLUGE
@section @option{-D}
@kindex -D
-This option has no effect whatsoever, but it is accepted to make it more
-likely that scripts written for other assemblers also work with
+This option enables debugging, if it is supported by the assembler's
+configuration. Otherwise it does nothing as is ignored. This allows scripts
+designed to work with other assemblers to also work with GAS.
@command{@value{AS}}.
@node f
do include file processing with the @code{.include} directive
(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver
to get other ``CPP'' style preprocessing by giving the input file a
-@samp{.S} suffix. @xref{Overall Options, ,Options Controlling the Kind of
-Output, gcc info, Using GNU CC}.
+@samp{.S} suffix. @url{https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#Overall-Options,
+See the 'Options Controlling the Kind of Output' section of the GCC manual for
+more details}
Excess whitespace, comments, and character constants
cannot be used in the portions of the input text that are not
If the first line of an input file is @code{#NO_APP} or if you use the
@samp{-f} option, whitespace and comments are not removed from the input file.
Within an input file, you can ask for whitespace and comment removal in
-specific portions of the by putting a line that says @code{#APP} before the
+specific portions of the file by putting a line that says @code{#APP} before the
text that may contain whitespace or comments, and putting a line that says
-@code{#NO_APP} after this text. This feature is mainly intend to support
+@code{#NO_APP} after this text. This feature is mainly intended to support
@code{asm} statements in compilers whose output is otherwise free of comments
and whitespace.
@cindex line comment character
Anything from a @dfn{line comment} character up to the next newline is
considered a comment and is ignored. The line comment character is target
-specific, and some targets multiple comment characters. Some targets also have
-line comment characters that only work if they are the first character on a
-line. Some targets use a sequence of two characters to introduce a line
-comment. Some targets can also change their line comment characters depending
-upon command-line options that have been used. For more details see the
-@emph{Syntax} section in the documentation for individual targets.
+specific, and some targets support multiple comment characters. Some targets
+also have line comment characters that only work if they are the first
+character on a line. Some targets use a sequence of two characters to
+introduce a line comment. Some targets can also change their line comment
+characters depending upon command-line options that have been used. For more
+details see the @emph{Syntax} section in the documentation for individual
+targets.
If the line comment character is the hash sign (@samp{#}) then it still has the
special ability to enable and disable preprocessing (@pxref{Preprocessing}) and
@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
@cindex newline, required at file end
@cindex EOF, newline must precede
It is an error to end any statement with end-of-file: the last
-character of any input file should be a newline.@refill
+character of any input file should be a newline.
An empty statement is allowed, and may include whitespace. It is ignored.
Different versions of @command{@value{AS}} for different computers
recognize different instructions. In fact, the same symbol may
represent a different instruction in a different computer's assembly
-language.@refill
+language.
@end ifset
@cindex @code{:} (label)
and does not count as the end of a statement. The value of a character
constant in a numeric expression is the machine's byte-wide code for
that character. @command{@value{AS}} assumes your character code is ASCII:
-@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
+@kbd{'A} means 65, @kbd{'B} means 66, and so on.
@node Numbers
@subsection Number Constants
@cindex expr (internal section)
@item expr section
-The assembler stores complex expression internally as combinations of
+The assembler stores complex expressions internally as combinations of
symbols. When it needs to represent an expression as a symbol, it puts
it in the expr section.
@c FIXME item debug
machines, you can also use @code{$} in symbol names; exceptions are
noted in @ref{Machine Dependencies}. That character may be followed by any
string of digits, letters, dollar signs (unless otherwise noted for a
-particular target machine), and underscores.
+particular target machine), and underscores. These restrictions do not
+apply when quoting symbol names by @samp{"}, which is permitted for most
+targets. Escaping characters in quoted symbol names with @samp{\} generally
+extends only to @samp{\} itself and @samp{"}, at the time of writing.
@end ifclear
@ifset SPECIAL-SYMS
@ifset H8
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.
@item <=
@dfn{Is Less Than Or Equal To}
-The comparison operators can be used as infix operators. A true results has a
-value of -1 whereas a false result has a value of 0. Note, these operators
+The comparison operators can be used as infix operators. A true result has a
+value of -1 whereas a false result has a value of 0. Note, these operators
perform signed comparisons.
@end table
These two logical operations can be used to combine the results of sub
expressions. Note, unlike the comparison operators a true result returns a
-value of 1 but a false results does still return 0. Also note that the logical
+value of 1 but a false result does still return 0. Also note that the logical
or operator has a slightly lower precedence than logical and.
@end table
* ABORT (COFF):: @code{.ABORT}
@end ifset
-* Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
+* Align:: @code{.align [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]}
* Altmacro:: @code{.altmacro}
* Ascii:: @code{.ascii "@var{string}"}@dots{}
* Asciz:: @code{.asciz "@var{string}"}@dots{}
-* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
+* 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}}
* Org:: @code{.org @var{new-lc}, @var{fill}}
-* P2align:: @code{.p2align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
+* P2align:: @code{.p2align [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]}
@ifset ELF
* PopSection:: @code{.popsection}
* Previous:: @code{.previous}
* Struct:: @code{.struct @var{expression}}
@ifset ELF
* SubSection:: @code{.subsection}
-* Symver:: @code{.symver @var{name},@var{name2@@nodename}}
+* Symver:: @code{.symver @var{name},@var{name2@@nodename}[,@var{visibility}]}
@end ifset
@ifset COFF
* 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
+* 8byte:: @code{.8byte @var{expressions}}
* Deprecated:: Deprecated Directives
@end menu
@end ifset
@node Align
-@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
+@section @code{.align [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]}
@cindex padding the location counter
@cindex @code{align} directive
Pad the location counter (in the current subsection) to a particular storage
boundary. The first expression (which must be absolute) is the alignment
-required, as described below.
+required, as described below. If this expression is omitted then a default
+value of 0 is used, effectively disabling alignment requirements.
The second expression (also absolute) gives the fill value to be stored in the
padding bytes. It (and the comma) may be omitted. If it is omitted, the
The way the required alignment is specified varies from system to system.
For the arc, hppa, i386 using ELF, iq2000, m68k, or1k,
-s390, sparc, tic4x, tic80 and xtensa, the first expression is the
+s390, sparc, tic4x and xtensa, the first expression is the
alignment request in bytes. For example @samp{.align 8} advances
the location counter until it is a multiple of 8. If the location counter
is already a multiple of 8, no change is needed. For the tic54x, the
strongarm, it is the
number of low-order zero bits the location counter must have after
advancement. For example @samp{.align 3} advances the location
-counter until it a multiple of 8. If the location counter is already a
+counter until it is a multiple of 8. If the location counter is already a
multiple of 8, no change is needed.
This inconsistency is due to the different behaviors of the various
@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}}
+@section @code{.balign[wl] [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]}
@cindex padding the location counter given number of bytes
@cindex @code{balign} directive
storage boundary. The first expression (which must be absolute) is the
alignment request in bytes. For example @samp{.balign 8} advances
the location counter until it is a multiple of 8. If the location counter
-is already a multiple of 8, no change is needed.
+is already a multiple of 8, no change is needed. If the expression is omitted
+then a default value of 0 is used, effectively disabling alignment requirements.
The second expression (also absolute) gives the fill value to be stored in the
padding bytes. It (and the comma) may be omitted. If it is omitted, the
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}}
@code{.byte} expects zero or more expressions, separated by commas.
Each expression is assembled into the next byte.
+Note - this directive is not intended for encoding instructions, and it will
+not trigger effects like DWARF line number generation. Instead some targets
+support special directives for encoding arbitrary binary sequences as
+instructions such as @code{.insn} or @code{.inst}.
+
@node CFI directives
@section CFI directives
@subsection @code{.cfi_sections @var{section_list}}
@cindex @code{cfi_sections} directive
@code{.cfi_sections} may be used to specify whether CFI directives
-should emit @code{.eh_frame} section and/or @code{.debug_frame} section.
-If @var{section_list} is @code{.eh_frame}, @code{.eh_frame} is emitted,
-if @var{section_list} is @code{.debug_frame}, @code{.debug_frame} is emitted.
-To emit both use @code{.eh_frame, .debug_frame}. The default if this
-directive is not used is @code{.cfi_sections .eh_frame}.
+should emit @code{.eh_frame} section, @code{.debug_frame} section and/or
+@code{.sframe} section. If @var{section_list} contains @code{.eh_frame},
+@code{.eh_frame} is emitted, if @var{section_list} contains
+@code{.debug_frame}, @code{.debug_frame} is emitted, and finally, if
+@var{section_list} contains @code{.sframe}, @code{.sframe} is emitted.
+To emit multiple sections, specify them together in a list. For example, to
+emit both @code{.eh_frame} and @code{.debug_frame}, use
+@code{.eh_frame, .debug_frame}. The default if this directive is not used
+is @code{.cfi_sections .eh_frame}.
On targets that support compact unwinding tables these can be generated
by specifying @code{.eh_frame_entry} instead of @code{.eh_frame}.
The byte ordering is target dependent, as is the size and format of floating
point values.
+Note - these directives are not intended for encoding instructions, and they
+will not trigger effects like DWARF line number generation. Instead some
+targets support special directives for encoding arbitrary binary sequences as
+instructions such as @code{.insn} or @code{.inst}.
+
@node Dcb
@section @code{.dcb[@var{size}] @var{number} [,@var{fill}]}
@cindex @code{dcb} directive
@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}
The byte ordering is target dependent.
-
@ifset COFF
@node Def
@section @code{.def @var{name}}
The @var{fileno} operand should be a unique positive integer to use as the
index of the entry in the table. The @var{filename} operand is a C string
-literal.
+literal enclosed in double quotes. The @var{filename} can include directory
+elements. If it does, then the directory will be added to the directory table
+and the basename will be added to the file table.
The detail of filename indices is exposed to the user because the filename
table is shared with the @code{.debug_info} section of the DWARF2 debugging
information, and thus the user must know the exact indices that table
entries will have.
+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 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}}
@end ifset
@end ifclear
+Note - this directive is not intended for encoding instructions, and it will
+not trigger effects like DWARF line number generation. Instead some targets
+support special directives for encoding arbitrary binary sequences as
+instructions such as eg @code{.insn} or @code{.inst}.
+
@ifset ELF
@node Internal
@section @code{.internal @var{names}}
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:
also applies to the identifiers used in @code{.irp} (@pxref{Irp})
and @code{.irpc} (@pxref{Irpc}) as well.
+Another issue can occur with the actual arguments passed during macro
+invocation: Multiple arguments can be separated by blanks or commas. To have
+arguments actually contain blanks or commas (or potentially other non-alpha-
+numeric characters), individual arguments will need to be enclosed in either
+parentheses @code{()}, square brackets @code{[]}, or double quote @code{"}
+characters. The latter may be the only viable option in certain situations,
+as only double quotes are actually stripped while establishing arguments. It
+may be important to be aware of two escaping models used when processing such
+quoted argument strings: For one two adjacent double quotes represent a single
+double quote in the resulting argument, going along the lines of the stripping
+of the enclosing quotes. But then double quotes can also be escaped by a
+backslash @code{\}, but this backslash will not be retained in the resulting
+actual argument as then seen / used while expanding the macro.
+
+As a consequence to the first of these escaping mechanisms two string literals
+intended to be representing separate macro arguments need to be separated by
+white space (or, better yet, by a comma). To state it differently, such
+adjacent string literals - even if separated only by a blank - will not be
+concatenated when determining macro arguments, even if they're only separated
+by white space. This is unlike certain other pseudo ops, e.g. @code{.ascii}.
+
@item .endm
@cindex @code{endm} directive
Mark the end of a macro definition.
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
@var{fill} defaults to zero.
@node P2align
-@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
+@section @code{.p2align[wl] [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]}
@cindex padding the location counter given a power of two
@cindex @code{p2align} directive
storage boundary. The first expression (which must be absolute) is the
number of low-order zero bits the location counter must have after
advancement. For example @samp{.p2align 3} advances the location
-counter until it a multiple of 8. If the location counter is already a
-multiple of 8, no change is needed.
+counter until it is a multiple of 8. If the location counter is already a
+multiple of 8, no change is needed. If the expression is omitted then a
+default value of 0 is used, effectively disabling alignment requirements.
The second expression (also absolute) gives the fill value to be stored in the
padding bytes. It (and the comma) may be omitted. If it is omitted, the
@end ifset
@node Quad
-@section @code{.quad @var{bignums}}
+@section @code{.quad @var{expressions}}
@cindex @code{quad} directive
-@code{.quad} expects zero or more bignums, separated by commas. For
-each bignum, it emits
@ifclear bignum-16
-an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
-warning message; and just takes the lowest order 8 bytes of the bignum.
+For 64-bit architectures, or more generally with any GAS configured to support
+64-bit target virtual addresses, this is like @samp{.int}, but emitting 64-bit
+quantities. Otherwise @code{.quad} expects zero or more bignums, separated by
+commas. For each item, it emits an 8-byte integer. If a bignum won't fit in
+8 bytes, a warning message is printed and just the lowest order 8 bytes of the
+bignum are taken.
@cindex eight-byte integer
@cindex integer, 8-byte
hence @emph{quad}-word for 8 bytes.
@end ifclear
@ifset bignum-16
-a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
-warning message; and just takes the lowest order 16 bytes of the bignum.
+@code{.quad} expects zero or more bignums, separated by commas. For
+each bignum, it emits a 16-byte integer. If the bignum won't fit in 16
+bytes, it prints a warning message; and just takes the lowest order 16
+bytes of the bignum.
+@xref{Octa,,@code{.octa @var{bignums}}}.
@cindex sixteen-byte integer
@cindex integer, 16-byte
@end ifset
+Note - this directive is not intended for encoding instructions, and it will
+not trigger effects like DWARF line number generation. Instead some targets
+support special directives for encoding arbitrary binary sequences as
+instructions such as @code{.insn} or @code{.inst}.
+
@node Reloc
@section @code{.reloc @var{offset}, @var{reloc_name}[, @var{expression}]}
section is a GNU_MBIND section
@item e
section is excluded from executable and shared library.
+@item o
+section references a symbol defined in another section (the linked-to
+section) in the same file.
@item w
section is writable
@item x
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:
@code{"def"} will be merged with @code{"abcdef"}; A reference to the first
@code{"def"} will be changed to a reference to @code{"abcdef"+3}.
+If @var{flags} contains the @code{o} flag, then the @var{type} argument
+must be present along with an additional field like this:
+
+@smallexample
+.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. 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:
+
+@smallexample
+.section @var{name},"@var{flags}"Mo,@@@var{type},@var{entsize},@var{SymbolName}
+@end smallexample
+
If @var{flags} contains the @code{G} symbol then the @var{type} argument must
be present along with an additional field like this:
.section @var{name} , "@var{flags}"MG, @@@var{type}, @var{entsize}, @var{GroupName}[, @var{linkage}]
@end smallexample
+If both @code{o} flag and @code{G} flag are present, then the
+@var{SymbolName} field for @code{o} comes first, like this:
+
+@smallexample
+.section @var{name},"@var{flags}"oG,@@@var{type},@var{SymbolName},@var{GroupName}[,@var{linkage}]
+@end smallexample
+
If @var{flags} contains the @code{?} symbol then it may not also contain the
@code{G} symbol and the @var{GroupName} or @var{linkage} fields should not be
present. Instead, @code{?} says to consider the section that's current before
@code{G} with those same @var{GroupName} and @var{linkage} fields implicitly.
If not, then the @code{?} symbol has no effect.
+The optional @var{unique,@code{<number>}} argument must come last. It
+assigns @var{@code{<number>}} as a unique section ID to distinguish
+different sections with the same section name like these:
+
+@smallexample
+.section @var{name},"@var{flags}",@@@var{type},@var{unique,@code{<number>}}
+.section @var{name},"@var{flags}"G,@@@var{type},@var{GroupName},[@var{linkage}],@var{unique,@code{<number>}}
+.section @var{name},"@var{flags}"MG,@@@var{type},@var{entsize},@var{GroupName}[,@var{linkage}],@var{unique,@code{<number>}}
+@end smallexample
+
+The valid values of @var{@code{<number>}} are between 0 and 4294967295.
+
If no flags are specified, the default flags depend upon the section name. If
the section name is not recognized, the default will be for the section to have
none of the above flags: it will not be allocated in memory, nor writable, nor
executable. The section will contain data.
-For ELF targets, the assembler supports another type of @code{.section}
+For SPARC ELF targets, the assembler supports another type of @code{.section}
directive for compatibility with the Solaris assembler:
@smallexample
file is the last value stored into it.
@ifset Z80
-On Z80 @code{set} is a real instruction, use
+On Z80 @code{set} is a real instruction, use @code{.set} or
@samp{@var{symbol} defl @var{expression}} instead.
@end ifset
@end ifset
@end ifclear
+Note - this directive is not intended for encoding instructions, and it will
+not trigger effects like DWARF line number generation. Instead some targets
+support special directives for encoding arbitrary binary sequences as
+instructions such as @code{.insn} or @code{.inst}.
+
@node Single
@section @code{.single @var{flonums}}
For ELF targets, the @code{.symver} directive can be used like this:
@smallexample
-.symver @var{name}, @var{name2@@nodename}
+.symver @var{name}, @var{name2@@nodename}[ ,@var{visibility}]
@end smallexample
-If the symbol @var{name} is defined within the file
+If the original symbol @var{name} is defined within the file
being assembled, the @code{.symver} directive effectively creates a symbol
alias with the name @var{name2@@nodename}, and in fact the main reason that we
just don't try and create a regular alias is that the @var{@@} character isn't
the name of a node specified in the version script supplied to the linker when
building a shared library. If you are attempting to override a versioned
symbol from a shared library, then @var{nodename} should correspond to the
-nodename of the symbol you are trying to override.
+nodename of the symbol you are trying to override. The optional argument
+@var{visibility} updates the visibility of the original symbol. The valid
+visibilities are @code{local}, @code{hidden}, and @code{remove}. The
+@code{local} visibility makes the original symbol a local symbol
+(@pxref{Local}). The @code{hidden} visibility sets the visibility of the
+original symbol to @code{hidden} (@pxref{Hidden}). The @code{remove}
+visibility removes the original symbol from the symbol table. If visibility
+isn't specified, the original symbol is unchanged.
If the symbol @var{name} is not defined within the file being assembled, all
references to @var{name} will be changed to @var{name2@@nodename}. If no
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}
@end table
+Changing between incompatible types other than from/to STT_NOTYPE will
+result in a diagnostic. An intermediate change to STT_NOTYPE will silence
+this.
+
Note: Some targets support extra types in addition to those listed above.
@end ifset
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
@cindex eight-byte integer
@cindex integer, 8-byte
-Like the @option{.2byte} directive, except that it inserts unaligned, eight
-byte long bignum values into the output.
-
-@end ifset
+For 64-bit architectures, or more generally with any GAS configured to support
+64-bit target virtual addresses, this is like the @option{.2byte} directive,
+except that it inserts unaligned, eight byte long values into the output.
+Otherwise, like @ref{Quad,,@code{.quad @var{expressions}}}, it expects zero or
+more bignums, separated by commas.
@node Deprecated
@section Deprecated Directives
arrangement indicated by the flag value and the vendor name.
@end table
+@subsection M680x0 Attributes
+
+@table @r
+@item Tag_GNU_M68K_ABI_FP (4)
+The floating-point ABI used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the floating-point ABI.
+@item
+1 for files using double-precision hardware floating-point ABI.
+@item
+2 for files using the software floating-point ABI.
+@end itemize
+@end table
+
@subsection MIPS Attributes
@table @r
registers, 32-bit general-purpose registers and a rule that forbids the
direct use of odd-numbered single-precision floating-point registers.
@end itemize
+
+@item Tag_GNU_MIPS_ABI_MSA (8)
+The MIPS SIMD Architecture (MSA) ABI used by this object file. The value
+will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the MSA ABI.
+@item
+1 for files using the 128-bit MSA ABI.
+@end itemize
+
@end table
@subsection PowerPC Attributes
@end itemize
@end table
+@subsection MSP430 Attributes
+
+@table @r
+@item Tag_GNU_MSP430_Data_Region (4)
+The data region used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not using the large memory model.
+@item
+1 for files which have been compiled with the condition that all
+data is in the lower memory region, i.e. below address 0x10000.
+@item
+2 for files which allow data to be placed in the full 20-bit memory range.
+@end itemize
+@end table
+
@node Defining New Object Attributes
@section Defining New Object Attributes
@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
+@ifset KVX
+* KVX-Dependent:: KVX Dependent Features
+@end ifset
@ifset M32C
* M32C-Dependent:: M32C Dependent Features
@end ifset
@include c-lm32.texi
@end ifset
+@ifset LOONGARCH
+@include c-loongarch.texi
+@end ifset
+
+@ifset KVX
+@include c-kvx.texi
+@end ifset
+
@ifset M32C
@include c-m32c.texi
@end ifset
projects / binutils-gdb.git / blobdiff