\input texinfo @c -*-Texinfo-*-
-@c Copyright (C) 1991-2022 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-2022 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-2022 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{--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{--multibyte-handling=[allow|warn|warn-sym-only]}]
- [@b{--target-help}] [@var{target-options}]
+ [@var{target-options}]
[@b{--}|@var{files} @dots{}]
@c
@c man end
@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 denugging 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).
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.
@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
@item -R
Fold the data section into the text section.
+@item --reduce-memory-overheads
+Ignored. Supported for compatibility with tools that apss the same option to
+both the assembler and the linker.
+
@ifset ELF
@item --sectname-subst
Honor substitution sequences in section names.
@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
@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
@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
@dfn{Is Less Than Or Equal To}
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
+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
@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}.
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.
projects / binutils-gdb.git / blobdiff