\input texinfo @c -*-Texinfo-*-
-@c Copyright (C) 1991-2020 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2021 Free Software Foundation, Inc.
@c UPDATE!! On future updates--
@c (1) check for new machine-dep cmdline options in
@c md_parse_option definitions in config/tc-*.c
This file documents the GNU Assembler "@value{AS}".
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2020 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2021 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991-2020 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2021 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
@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
@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
* 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}]]}
* Bundle directives:: @code{.bundle_align_mode @var{abs-expr}}, etc
* Byte:: @code{.byte @var{expressions}}
* 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
@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}]]]}
number matrix corresponding to the immediately following assembly
instruction. The @var{fileno}, @var{lineno}, and optional @var{column}
arguments will be applied to the @code{.debug_line} state machine before
-the row is added.
+the row is added. It is an error for the input assembly file to generate
+a non-empty @code{.debug_line} and also use @code{loc} directives.
The @var{options} are a sequence of the following tokens in any order:
counter, and @code{.nolist} decrements it. Assembly listings are
generated whenever the counter is greater than zero.
+@node Nop
+@section @code{.nop [@var{size}]}
+
+@cindex @code{nop} directive
+@cindex filling memory with no-op instructions
+This directive emits no-op instructions. It is provided on all architectures,
+allowing the creation of architecture neutral tests involving actual code. The
+size of the generated instruction is target specific, but if the optional
+@var{size} argument is given and resolves to an absolute positive value at that
+point in assembly (no forward expressions allowed) then the fewest no-op
+instructions are emitted that equal or exceed a total @var{size} in bytes.
+@code{.nop} does affect the generation of DWARF debug line information.
+Some targets do not support using @code{.nop} with @var{size}.
+
@node Nops
@section @code{.nops @var{size}[, @var{control}]}
@cindex @code{nops} directive
@cindex filling memory with no-op instructions
-This directive emits @var{size} bytes filled with no-op instructions.
-@var{size} is absolute expression, which must be a positve value.
-@var{control} controls how no-op instructions should be generated. If
-the comma and @var{control} are omitted, @var{control} is assumed to be
-zero.
-
-Note: For Intel 80386 and AMD x86-64 targets, @var{control} specifies
-the size limit of a no-op instruction. The valid values of @var{control}
-are between 0 and 4 in 16-bit mode, between 0 and 7 when tuning for
-older processors in 32-bit mode, between 0 and 11 in 64-bit mode or when
-tuning for newer processors in 32-bit mode. When 0 is used, the no-op
+This directive emits no-op instructions. It is specific to the Intel 80386 and
+AMD x86-64 targets. It takes a @var{size} argument and generates @var{size}
+bytes of no-op instructions. @var{size} must be absolute and positive. These
+bytes do not affect the generation of DWARF debug line information.
+
+The optional @var{control} argument specifies a size limit for a single no-op
+instruction. If not provided then a value of 0 is assumed. The valid values
+of @var{control} are between 0 and 4 in 16-bit mode, between 0 and 7 when
+tuning for older processors in 32-bit mode, between 0 and 11 in 64-bit mode or
+when tuning for newer processors in 32-bit mode. When 0 is used, the no-op
instruction size limit is set to the maximum supported size.
@node Octa
section is used for thread-local-storage
@item ?
section is a member of the previously-current section's group, if any
+@item R
+retained section (apply SHF_GNU_RETAIN to prevent linker garbage
+collection, GNU ELF extension)
@item @code{<number>}
a numeric value indicating the bits to be set in the ELF section header's flags
field. Note - if one or more of the alphabetic characters described above is
flags can be added to an already defined section. The @code{.interp},
@code{.strtab} and @code{.symtab} sections can have the allocate flag
(@code{a}) set after they are initially defined, and the @code{.note-GNU-stack}
-section may have the executable (@code{x}) flag added.
+section may have the executable (@code{x}) flag added. Also note that the
+@code{.attach_to_group} directive can be used to add a section to a group even
+if the section was not originally declared to be part of that group.
The optional @var{type} argument may contain one of the following constants:
must be present along with an additional field like this:
@smallexample
-.section @var{name},"@var{flags}"o,@@@var{type},@var{SymbolName}
+.section @var{name},"@var{flags}"o,@@@var{type},@var{SymbolName}|@var{SectionIndex}
@end smallexample
The @var{SymbolName} field specifies the symbol name which the section
-references.
+references. Alternatively a numeric @var{SectionIndex} can be provided. This
+is not generally a good idea as section indicies are rarely known at assembly
+time, but the facility is provided for testing purposes. An index of zero is
+allowed. It indicates that the linked-to section has already been discarded.
Note: If both the @var{M} and @var{o} flags are present, then the fields
for the Merge flag should come first, like this:
This directive affects subsequent pages, as well as the current page if
it appears within ten lines of the top of a page.
+@ifset ELF
+@node Tls_common
+@section @code{.tls_common @var{symbol}, @var{length}[, @var{alignment}]}
+
+@cindex @code{tls_common} directive
+This directive behaves in the same way as the @code{.comm} directive
+(@pxref{Comm}) except that @var{symbol} has type of STT_TLS instead of
+STT_OBJECT.
+@end ifset
+
@ifset COFF-ELF
@node Type
@section @code{.type}
projects / thirdparty / binutils-gdb.git / blobdiff