\input texinfo @c -*-Texinfo-*-
-@c Copyright (C) 1991-2020 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-2020 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-2020 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-<N>}] [@b{--gdwarf-sections}]
+ [@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{--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{--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
@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
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
can modify this default. Other possible values for @var{version} are 3 or 4.
@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 --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}), @samp{z14} (or @samp{arch12}), or @samp{z15}
-(or @samp{arch13}).
+@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.
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
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
* 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
+* 8byte:: @code{.8byte @var{expressions}}
* 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}}
@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}}
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}}
@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
@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 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:
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
@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}}
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
@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
@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