\input texinfo @c -*-Texinfo-*-
-@c Copyright (C) 1991-2015 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2017 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-2015 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2017 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-2015 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2017 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
[@b{-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{--no-pad-sections}]
[@b{-o} @var{objfile}] [@b{-R}]
[@b{--hash-size}=@var{NUM}] [@b{--reduce-memory-overheads}]
[@b{--statistics}]
[@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{--target-help}] [@var{target-options}]
[@b{--}|@var{files} @dots{}]
@c
+@c man end
@c Target dependent options are listed below. Keep the list sorted.
@c Add an empty line for separation.
+@c man begin TARGET
@ifset AARCH64
@emph{Target AArch64 options:}
[@b{-mcpu=@var{cpu}}]
[@b{-mA6}|@b{-mARC600}|@b{-mARC601}|@b{-mA7}|@b{-mARC700}|@b{-mEM}|@b{-mHS}]
[@b{-mcode-density}]
+ [@b{-mrelax}]
[@b{-EB}|@b{-EL}]
@end ifset
@ifset ARM
[@b{-mips32r3}] [@b{-mips32r5}] [@b{-mips32r6}] [@b{-mips64}] [@b{-mips64r2}]
[@b{-mips64r3}] [@b{-mips64r5}] [@b{-mips64r6}]
[@b{-construct-floats}] [@b{-no-construct-floats}]
+ [@b{-mignore-branch-isa}] [@b{-mno-ignore-branch-isa}]
[@b{-mnan=@var{encoding}}]
[@b{-trap}] [@b{-no-break}] [@b{-break}] [@b{-no-trap}]
[@b{-mips16}] [@b{-no-mips16}]
[@b{-mdmx}] [@b{-no-mdmx}]
[@b{-mdsp}] [@b{-mno-dsp}]
[@b{-mdspr2}] [@b{-mno-dspr2}]
+ [@b{-mdspr3}] [@b{-mno-dspr3}]
[@b{-mmsa}] [@b{-mno-msa}]
[@b{-mxpa}] [@b{-mno-xpa}]
[@b{-mmt}] [@b{-mno-mt}]
@b{-m440}|@b{-m464}|@b{-m476}|@b{-m7400}|@b{-m7410}|@b{-m7450}|@b{-m7455}|@b{-m750cl}|@b{-mppc64}|
@b{-m620}|@b{-me500}|@b{-e500x2}|@b{-me500mc}|@b{-me500mc64}|@b{-me5500}|@b{-me6500}|@b{-mppc64bridge}|
@b{-mbooke}|@b{-mpower4}|@b{-mpwr4}|@b{-mpower5}|@b{-mpwr5}|@b{-mpwr5x}|@b{-mpower6}|@b{-mpwr6}|
- @b{-mpower7}|@b{-mpwr7}|@b{-mpower8}|@b{-mpwr8}|@b{-ma2}|@b{-mcell}|@b{-mspe}|@b{-mtitan}|@b{-me300}|@b{-mcom}]
+ @b{-mpower7}|@b{-mpwr7}|@b{-mpower8}|@b{-mpwr8}|@b{-mpower9}|@b{-mpwr9}@b{-ma2}|
+ @b{-mcell}|@b{-mspe}|@b{-mtitan}|@b{-me300}|@b{-mcom}]
[@b{-many}] [@b{-maltivec}|@b{-mvsx}|@b{-mhtm}|@b{-mvle}]
[@b{-mregnames}|@b{-mno-regnames}]
[@b{-mrelocatable}|@b{-mrelocatable-lib}|@b{-K PIC}] [@b{-memb}]
[@b{-msolaris}|@b{-mno-solaris}]
[@b{-nops=@var{count}}]
@end ifset
+@ifset PRU
+
+@emph{Target PRU options:}
+ [@b{-link-relax}]
+ [@b{-mnolink-relax}]
+ [@b{-mno-warn-regname-label}]
+@end ifset
@ifset RL78
@emph{Target RL78 options:}
[@b{-mint-register=@var{number}}]
[@b{-mgcc-abi}|@b{-mrx-abi}]
@end ifset
+@ifset RISCV
+
+@emph{Target RISC-V options:}
+ [@b{-march}=@var{ISA}]
+ [@b{-mabi}=@var{ABI}]
+@end ifset
@ifset S390
@emph{Target s390 options:}
@emph{Target SPARC options:}
@c The order here is important. See c-sparc.texi.
- [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Asparclet}|@b{-Asparclite}
- @b{-Av8plus}|@b{-Av8plusa}|@b{-Av9}|@b{-Av9a}]
- [@b{-xarch=v8plus}|@b{-xarch=v8plusa}] [@b{-bump}]
+ [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Aleon}|@b{-Asparclet}|@b{-Asparclite}
+ @b{-Av8plus}|@b{-Av8plusa}|@b{-Av8plusb}|@b{-Av8plusc}|@b{-Av8plusd}
+ @b{-Av8plusv}|@b{-Av8plusm}|@b{-Av9}|@b{-Av9a}|@b{-Av9b}|@b{-Av9c}
+ @b{-Av9d}|@b{-Av9e}|@b{-Av9v}|@b{-Av9m}|@b{-Asparc}|@b{-Asparcvis}
+ @b{-Asparcvis2}|@b{-Asparcfmaf}|@b{-Asparcima}|@b{-Asparcvis3}
+ @b{-Asparcvisr}|@b{-Asparc5}]
+ [@b{-xarch=v8plus}|@b{-xarch=v8plusa}]|@b{-xarch=v8plusb}|@b{-xarch=v8plusc}
+ @b{-xarch=v8plusd}|@b{-xarch=v8plusv}|@b{-xarch=v8plusm}|@b{-xarch=v9}
+ @b{-xarch=v9a}|@b{-xarch=v9b}|@b{-xarch=v9c}|@b{-xarch=v9d}|@b{-xarch=v9e}
+ @b{-xarch=v9v}|@b{-xarch=v9m}|@b{-xarch=sparc}|@b{-xarch=sparcvis}
+ @b{-xarch=sparcvis2}|@b{-xarch=sparcfmaf}|@b{-xarch=sparcima}
+ @b{-xarch=sparcvis3}|@b{-xarch=sparcvisr}|@b{-xarch=sparc5}
+ @b{-bump}]
[@b{-32}|@b{-64}]
+ [@b{--enforce-aligned-data}][@b{--dcti-couples-detect}]
@end ifset
@ifset TIC54X
@end ifset
@item --nocompress-debug-sections
-Do not compress DWARF debug sections. This is the default.
+Do not compress DWARF debug sections. This is usually the default for all
+targets except the x86/x86_64, but a configure time option can be used to
+override this.
@item -D
Ignored. This option is accepted for script compatibility with calls to
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}.
+@end ifset
+
@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 --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
+which might be needed on targets which have tight memory constraints.
+
@item -o @var{objfile}
Name the object-file output from @command{@value{AS}} @var{objfile}.
@end table
@end ifset
+@ifset PRU
+
+@ifclear man
+@xref{PRU Options}, for the options available when @value{AS} is configured
+for a PRU processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+PRU processor.
+@c man end
+@c man begin INCLUDE
+@include c-pru.texi
+@c ended inside the included file
+@end ifset
+@end ifset
+
@ifset M68HC11
The following options are available when @value{AS} is configured for the
Motorola 68HC11 or 68HC12 series.
@end ifset
@ifset MIPS
+@c man begin OPTIONS
The following options are available when @value{AS} is configured for
a MIPS processor.
@item -mdspr2
@itemx -mno-dspr2
Generate code for the DSP Release 2 Application Specific Extension.
-This option implies -mdsp.
+This option implies @samp{-mdsp}.
This tells the assembler to accept DSP Release 2 instructions.
@samp{-mno-dspr2} turns off this option.
+@item -mdspr3
+@itemx -mno-dspr3
+Generate code for the DSP Release 3 Application Specific Extension.
+This option implies @samp{-mdsp} and @samp{-mdspr2}.
+This tells the assembler to accept DSP Release 3 instructions.
+@samp{-mno-dspr3} turns off this option.
+
@item -mmsa
@itemx -mno-msa
Generate code for the MIPS SIMD Architecture Extension.
branches. By default @samp{--no-relax-branch} is selected, causing any
out-of-range branches to produce an error.
+@item -mignore-branch-isa
+@itemx -mno-ignore-branch-isa
+Ignore branch checks for invalid transitions between ISA modes. The
+semantics of branches does not provide for an ISA mode switch, so in
+most cases the ISA mode a branch has been encoded for has to be the
+same as the ISA mode of the branch's target label. Therefore GAS has
+checks implemented that verify in branch assembly that the two ISA
+modes match. @samp{-mignore-branch-isa} disables these checks. By
+default @samp{-mno-ignore-branch-isa} is selected, causing any invalid
+branch requiring a transition between ISA modes to produce an error.
+
@item -mnan=@var{encoding}
Select between the IEEE 754-2008 (@option{-mnan=2008}) or the legacy
(@option{-mnan=legacy}) NaN encoding format. The latter is the default.
When this option is used, @command{@value{AS}} will issue a warning every
time it generates a nop instruction from a macro.
@end table
+@c man end
@end ifset
@ifset MCORE
@end ifset
+@ifset RISCV
+
+@ifclear man
+@xref{RISC-V-Opts}, for the options available when @value{AS} is configured
+for a RISC-V processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+RISC-V processor.
+@c man end
+@c man begin INCLUDE
+@include c-riscv.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
@c man begin OPTIONS
@ifset RX
See the info pages for documentation of the RX-specific options.
Select the architecture mode, either the Enterprise System
Architecture (esa) or the z/Architecture mode (zarch).
@item -march=@var{processor}
-Specify which s390 processor variant is the target, @samp{g6}, @samp{g6},
-@samp{z900}, @samp{z990}, @samp{z9-109}, @samp{z9-ec}, @samp{z10},
-@samp{z196}, @samp{zEC12}, or @samp{z13}.
+Specify which s390 processor variant is the target, @samp{g5} (or
+@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{arch12}.
@item -mregnames
@itemx -mno-regnames
Allow or disallow symbolic names for registers.
@end smallexample
@noindent
-@cindex line numbers, in warnings/errors
-(where @b{NNN} is a line number). If a logical file name has been given
-(@pxref{File,,@code{.file}}) it is used for the filename, otherwise the name of
-the current input file is used. If a logical line number was given
+@cindex file names and line numbers, in warnings/errors
+(where @b{NNN} is a line number). If both a logical file name
+(@pxref{File,,@code{.file}}) and a logical line number
@ifset GENERIC
(@pxref{Line,,@code{.line}})
@end ifset
-then it is used to calculate the number printed,
-otherwise the actual line in the current source file is printed. The
-message text is intended to be self explanatory (in the grand Unix
-tradition).
+have been given then they will be used, otherwise the file name and line number
+in the current assembler source file will be used. The message text is
+intended to be self explanatory (in the grand Unix tradition).
+
+Note the file name must be set via the logical version of the @code{.file}
+directive, not the DWARF2 version of the @code{.file} directive. For example:
+
+@smallexample
+ .file 2 "bar.c"
+ error_assembler_source
+ .file "foo.c"
+ .line 30
+ error_c_source
+@end smallexample
+
+produces this output:
+
+@smallexample
+ Assembler messages:
+ asm.s:2: Error: no such instruction: `error_assembler_source'
+ foo.c:31: Error: no such instruction: `error_c_source'
+@end smallexample
@cindex format of error messages
Error messages have the format
+
@smallexample
file_name:@b{NNN}:FATAL:Error Message Text
@end smallexample
+
The file name and line number are derived as for warning
messages. The actual message text may be rather less explanatory
because many of them aren't supposed to happen.
* listing:: --listing-XXX to configure listing output
* M:: -M or --mri to assemble in MRI compatibility mode
* MD:: --MD for dependency tracking
+* no-pad-sections:: --no-pad-sections to stop section padding
* o:: -o to name the object file
* R:: -R to join data and text sections
* statistics:: --statistics to see statistics about assembly
This feature is used in the automatic updating of makefiles.
+@node no-pad-sections
+@section Output Section Padding
+@kindex --no-pad-sections
+@cindex output section padding
+Normally the assembler will pad the end of each output section up to its
+alignment boundary. But this can waste space, which can be significant on
+memory constrained targets. So the @option{--no-pad-sections} option will
+disable this behaviour.
+
@node o
@section Name the Object File: @option{-o}
(@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}.
+Output, gcc info, Using GNU CC}.
Excess whitespace, comments, and character constants
cannot be used in the portions of the input text that are not
@cindex escape codes, character
@cindex character escape codes
+@c NOTE: Cindex entries must not start with a backlash character.
+@c NOTE: This confuses the pdf2texi script when it is creating the
+@c NOTE: index based upon the first character and so it generates:
+@c NOTE: \initial {\\}
+@c NOTE: which then results in the error message:
+@c NOTE: Argument of \\ has an extra }.
+@c NOTE: So in the index entries below a space character has been
+@c NOTE: prepended to avoid this problem.
@table @kbd
@c @item \a
@c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
@c
-@cindex @code{\b} (backspace character)
+@cindex @code{ \b} (backspace character)
@cindex backspace (@code{\b})
@item \b
Mnemonic for backspace; for ASCII this is octal code 010.
@c @item \e
@c Mnemonic for EOText; for ASCII this is octal code 004.
@c
-@cindex @code{\f} (formfeed character)
+@cindex @code{ \f} (formfeed character)
@cindex formfeed (@code{\f})
-@item \f
+@item backslash-f
Mnemonic for FormFeed; for ASCII this is octal code 014.
-@cindex @code{\n} (newline character)
+@cindex @code{ \n} (newline character)
@cindex newline (@code{\n})
@item \n
Mnemonic for newline; for ASCII this is octal code 012.
@c @item \p
@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
@c
-@cindex @code{\r} (carriage return character)
-@cindex carriage return (@code{\r})
+@cindex @code{ \r} (carriage return character)
+@cindex carriage return (@code{backslash-r})
@item \r
Mnemonic for carriage-Return; for ASCII this is octal code 015.
@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
@c other assemblers.
@c
-@cindex @code{\t} (tab)
+@cindex @code{ \t} (tab)
@cindex tab (@code{\t})
@item \t
Mnemonic for horizontal Tab; for ASCII this is octal code 011.
@c @item \x @var{digit} @var{digit} @var{digit}
@c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
@c
-@cindex @code{\@var{ddd}} (octal character code)
+@cindex @code{ \@var{ddd}} (octal character code)
@cindex octal character code (@code{\@var{ddd}})
@item \ @var{digit} @var{digit} @var{digit}
An octal character code. The numeric code is 3 octal digits.
For compatibility with other Unix systems, 8 and 9 are accepted as digits:
for example, @code{\008} has the value 010, and @code{\009} the value 011.
-@cindex @code{\@var{xd...}} (hex character code)
+@cindex @code{ \@var{xd...}} (hex character code)
@cindex hex character code (@code{\@var{xd...}})
@item \@code{x} @var{hex-digits...}
A hex character code. All trailing hex digits are combined. Either upper or
lower case @code{x} works.
-@cindex @code{\\} (@samp{\} character)
+@cindex @code{ \\} (@samp{\} character)
@cindex backslash (@code{\\})
@item \\
Represents one @samp{\} character.
@c (@xref{Characters,,Character Constants}.) to represent
@c a @samp{'}.
@c
-@cindex @code{\"} (doublequote character)
+@cindex @code{ \"} (doublequote character)
@cindex doublequote (@code{\"})
@item \"
Represents one @samp{"} character. Needed in strings to represent
@cindex single character constant
@cindex character, single
@cindex constant, single character
-A single character may be written as a single quote immediately
-followed by that character. The same escapes apply to characters as
-to strings. So if you want to write the character backslash, you
-must write @kbd{'\\} where the first @code{\} escapes the second
-@code{\}. As you can see, the quote is an acute accent, not a
-grave accent. A newline
+A single character may be written as a single quote immediately followed by
+that character. Some backslash escapes apply to characters, @code{\b},
+@code{\f}, @code{\n}, @code{\r}, @code{\t}, and @code{\"} with the same meaning
+as for strings, plus @code{\'} for a single quote. So if you want to write the
+character backslash, you must write @kbd{'\\} where the first @code{\} escapes
+the second @code{\}. As you can see, the quote is an acute accent, not a grave
+accent. A newline
@ifclear GENERIC
@ifclear abnormal-separator
(or semicolon @samp{;})
@ifclear no-space-dir
* Zero:: @code{.zero @var{size}}
@end ifclear
+@ifset ELF
+* 2byte:: @code{.2byte @var{expressions}}
+* 4byte:: @code{.4byte @var{expressions}}
+* 8byte:: @code{.8byte @var{bignums}}
+@end ifset
* Deprecated:: Deprecated Directives
@end menu
On targets that support compact unwinding tables these can be generated
by specifying @code{.eh_frame_entry} instead of @code{.eh_frame}.
+Some targets may support an additional name, such as @code{.c6xabi.exidx}
+which is used by the @value{TIC6X} target.
+
+The @code{.cfi_sections} directive can be repeated, with the same or different
+arguments, provided that CFI generation has not yet started. Once CFI
+generation has started however the section list is fixed and any attempts to
+redefine it will result in an error.
+
@subsection @code{.cfi_startproc [simple]}
@cindex @code{cfi_startproc} directive
@code{.cfi_startproc} is used at the beginning of each function that
@subsection @code{.cfi_adjust_cfa_offset @var{offset}}
Same as @code{.cfi_def_cfa_offset} but @var{offset} is a relative
-value that is added/substracted from the previous offset.
+value that is added/subtracted from the previous offset.
@subsection @code{.cfi_offset @var{register}, @var{offset}}
Previous value of @var{register} is saved at offset @var{offset} from
CFA.
+@subsection @code{.cfi_val_offset @var{register}, @var{offset}}
+Previous value of @var{register} is CFA + @var{offset}.
+
@subsection @code{.cfi_rel_offset @var{register}, @var{offset}}
Previous value of @var{register} is saved at offset @var{offset} from
the current CFA register. This is transformed to @code{.cfi_offset}
Current value of @var{register} is the same like in the previous frame,
i.e. no restoration needed.
-@subsection @code{.cfi_remember_state},
-First save all current rules for all registers by @code{.cfi_remember_state},
-then totally screw them up by subsequent @code{.cfi_*} directives and when
-everything is hopelessly bad, use @code{.cfi_restore_state} to restore
-the previous saved state.
+@subsection @code{.cfi_remember_state} and @code{.cfi_restore_state}
+@code{.cfi_remember_state} pushes the set of rules for every register onto an
+implicit stack, while @code{.cfi_restore_state} pops them off the stack and
+places them in the current row. This is useful for situations where you have
+multiple @code{.cfi_*} directives that need to be undone due to the control
+flow of the program. For example, we could have something like this (assuming
+the CFA is the value of @code{rbp}):
+
+@smallexample
+ je label
+ popq %rbx
+ .cfi_restore %rbx
+ popq %r12
+ .cfi_restore %r12
+ popq %rbp
+ .cfi_restore %rbp
+ .cfi_def_cfa %rsp, 8
+ ret
+label:
+ /* Do something else */
+@end smallexample
+
+Here, we want the @code{.cfi} directives to affect only the rows corresponding
+to the instructions before @code{label}. This means we'd have to add multiple
+@code{.cfi} directives after @code{label} to recreate the original save
+locations of the registers, as well as setting the CFA back to the value of
+@code{rbp}. This would be clumsy, and result in a larger binary size. Instead,
+we can write:
+
+@smallexample
+ je label
+ popq %rbx
+ .cfi_remember_state
+ .cfi_restore %rbx
+ popq %r12
+ .cfi_restore %r12
+ popq %rbp
+ .cfi_restore %rbp
+ .cfi_def_cfa %rsp, 8
+ ret
+label:
+ .cfi_restore_state
+ /* Do something else */
+@end smallexample
+
+That way, the rules for the instructions after @code{label} will be the same
+as before the first @code{.cfi_restore} without having to use multiple
+@code{.cfi} directives.
@subsection @code{.cfi_return_column @var{register}}
Change return column @var{register}, i.e. the return address is either
@ifset Z80
The syntax for @code{equ} on the Z80 is
@samp{@var{symbol} equ @var{expression}}.
-On the Z80 it is an eror if @var{symbol} is already defined,
+On the Z80 it is an error if @var{symbol} is already defined,
but the symbol is not protected from later redefinition.
Compare @ref{Equiv}.
@end ifset
If the optional argument is quoted, it is taken as flags to use for the
section. Each flag is a single character. The following flags are recognized:
+
@table @code
@item b
bss section (uninitialized data)
The two @code{exception_code} invocations above would create the
@code{.text.exception} and @code{.init.exception} sections respectively.
-This is useful e.g. to discriminate between anciliary sections that are
-tied to setup code to be discarded after use from anciliary sections that
+This is useful e.g. to discriminate between ancillary sections that are
+tied to setup code to be discarded after use from ancillary sections that
need to stay resident without having to define multiple @code{exception_code}
macros just for that purpose.
The optional @var{flags} argument is a quoted string which may contain any
combination of the following characters:
+
@table @code
@item a
section is allocatable
section is used for thread-local-storage
@item ?
section is a member of the previously-current section's group, if any
+@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
+also included in the flags field, their bit values will be ORed into the
+resulting value.
+@item @code{<target specific>}
+some targets extend this list with their own flag characters
@end table
+Note - once a section's flags have been set they cannot be changed. There are
+a few exceptions to this rule however. Processor and application specific
+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.
+
The optional @var{type} argument may contain one of the following constants:
+
@table @code
@item @@progbits
section contains data
section contains an array of pointers to finish functions
@item @@preinit_array
section contains an array of pointers to pre-init functions
+@item @@@code{<number>}
+a numeric value to be set as the ELF section header's type field.
+@item @@@code{<target specific>}
+some targets extend this list with their own types
@end table
-Many targets only support the first three section types.
+Many targets only support the first three section types. The type may be
+enclosed in double quotes if necessary.
Note on targets where the @code{@@} character is the start of a comment (eg
ARM) then another character is used instead. For example the ARM port uses the
@code{%} character.
+Note - some sections, eg @code{.text} and @code{.data} are considered to be
+special and have fixed types. Any attempt to declare them with a different
+type will generate an error from the assembler.
+
If @var{flags} contains the @code{M} symbol then the @var{type} argument must
be specified as well as an extra argument---@var{entsize}---like this:
The @var{GroupName} field specifies the name of the section group to which this
particular section belongs. The optional linkage field can contain:
+
@table @code
@item comdat
indicates that only one copy of this section should be retained
Note that the section name is quoted. There may be a sequence of comma
separated flags:
+
@table @code
@item #alloc
section is allocatable
@item STT_TLS
@itemx tls_object
-Mark the symbol as being a thead-local data object.
+Mark the symbol as being a thread-local data object.
@item STT_COMMON
@itemx common
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
+@cindex two-byte integer
+@cindex integer, 2-byte
+
+This directive expects zero or more expressions, separated by commas. If there
+are no expressions then the directive does nothing. Otherwise each expression
+is evaluated in turn and placed in the next two bytes of the current output
+section, using the endian model of the target. If an expression will not fit
+in two bytes, a warning message is displayed and the least significant two
+bytes of the expression's value are used. If an expression cannot be evaluated
+at assembly time then relocations will be generated in order to compute the
+value at link time.
+
+This directive does not apply any alignment before or after inserting the
+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 four-byte integer
+@cindex integer, 4-byte
+
+Like the @option{.2byte} directive, except that it inserts unaligned, four byte
+long values into the output.
+
+@node 8byte
+@section @code{.8byte @var{expression} [, @var{expression}]*}
+@cindex @code{8byte} directive
+@cindex eight-byte integer
+@cindex integer, 8-byte
+
+Like the @option{.8byte} directive, except that it inserts unaligned, eight
+byte long bignum values into the output.
+
+@end ifset
+
@node Deprecated
@section Deprecated Directives
@ifset PPC
* PPC-Dependent:: PowerPC Dependent Features
@end ifset
+@ifset PRU
+* PRU-Dependent:: PRU Dependent Features
+@end ifset
@ifset RL78
* RL78-Dependent:: RL78 Dependent Features
@end ifset
+@ifset RISCV
+* RISC-V-Dependent:: RISC-V Dependent Features
+@end ifset
@ifset RX
* RX-Dependent:: RX Dependent Features
@end ifset
@ifset VISIUM
* Visium-Dependent:: Visium Dependent Features
@end ifset
+@ifset WASM32
+* WebAssembly-Dependent:: WebAssembly Dependent Features
+@end ifset
@ifset XGATE
-* XGATE-Dependent:: XGATE Features
+* XGATE-Dependent:: XGATE Dependent Features
@end ifset
@ifset XSTORMY16
* XSTORMY16-Dependent:: XStormy16 Dependent Features
@include c-ppc.texi
@end ifset
+@ifset PRU
+@include c-pru.texi
+@end ifset
+
@ifset RL78
@include c-rl78.texi
@end ifset
+@ifset RISCV
+@include c-riscv.texi
+@end ifset
+
@ifset RX
@include c-rx.texi
@end ifset
@include c-visium.texi
@end ifset
+@ifset WASM32
+@include c-wasm32.texi
+@end ifset
+
@ifset XGATE
@include c-xgate.texi
@end ifset
projects / deliverable / binutils-gdb.git / blobdiff