X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gas%2Fdoc%2Fas.texinfo;h=d03d0b64c4805b57e02fb9cc6f8f635d8060880a;hb=f96bd6c2d7a3801fabbf9d834f7a29b752aa7532;hp=1c2fe081fac572ccbc6427eea9bc17caabafb026;hpb=d3b47e2bd4f2924e965c586d3bf4d0b0cc6b40cc;p=deliverable%2Fbinutils-gdb.git diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo index 1c2fe081fa..d03d0b64c4 100644 --- a/gas/doc/as.texinfo +++ b/gas/doc/as.texinfo @@ -1,5 +1,5 @@ \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 @@ -100,7 +100,7 @@ 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 @@ -149,7 +149,7 @@ done. @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 @@ -234,16 +234,23 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. [@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{-o} - @var{objfile}] [@b{-R}] [@b{--reduce-memory-overheads}] [@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{--size-check=[error|warning]}] + [@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{-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{--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:} @@ -262,7 +269,10 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. @ifset ARC @emph{Target ARC options:} - [@b{-marc[5|6|7|8]}] + [@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 @@ -406,6 +416,7 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. [@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}] @@ -415,6 +426,7 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. [@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}] @@ -473,7 +485,8 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. @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}] @@ -481,6 +494,13 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. [@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:} @@ -499,6 +519,12 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. [@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:} @@ -518,10 +544,21 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. @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 @@ -552,7 +589,8 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. @ifset XTENSA @emph{Target Xtensa options:} - [@b{--[no-]text-section-literals}] [@b{--[no-]absolute-literals}] + [@b{--[no-]text-section-literals}] [@b{--[no-]auto-litpools}] + [@b{--[no-]absolute-literals}] [@b{--[no-]target-align}] [@b{--[no-]longcalls}] [@b{--[no-]transform}] [@b{--rename-section} @var{oldname}=@var{newname}] @@ -625,10 +663,10 @@ Begin in alternate macro mode. @end ifclear @item --compress-debug-sections -Compress DWARF debug sections using zlib. The debug sections are renamed -to begin with @samp{.zdebug}, and the resulting object file may not be -compatible with older linkers and object file utilities. Note if compression -would make a given section @emph{larger} then it is not compressed or renamed. +Compress DWARF debug sections using zlib with SHF_COMPRESSED from the +ELF ABI. The resulting object file may not be compatible with older +linkers and object file utilities. Note if compression would make a +given section @emph{larger} then it is not compressed. @ifset ELF @cindex @samp{--compress-debug-sections=} option @@ -640,14 +678,19 @@ 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-gnu} are equivalent to +@option{--compress-debug-sections=zlib-gabi} are equivalent to @option{--compress-debug-sections}. -@option{--compress-debug-sections=zlib-gabi} compresses -DWARF debug sections with SHF_COMPRESSED from the ELF ABI. +@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. + @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 @@ -699,10 +742,18 @@ will have its dwarf line number information placed into a section called 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. @@ -748,13 +799,18 @@ Set the maximum width of an input source line, as displayed in a listing, to 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}. @item -R Fold the data section into the text section. -@kindex --hash-size=@var{number} +@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 @@ -766,6 +822,14 @@ 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. +@ifset ELF +@item --sectname-subst +Honor substitution sequences in section names. +@ifclear man +@xref{Section Name Substitutions,,@code{.section @var{name}}}. +@end ifclear +@end ifset + @item --statistics Print the maximum space (in bytes) and total time (in seconds) used by assembly. @@ -845,14 +909,16 @@ processor. @c man begin OPTIONS @ifset ARC -The following options are available when @value{AS} is configured for -an ARC processor. +The following options are available when @value{AS} is configured for an ARC +processor. @table @gcctabopt -@item -marc[5|6|7|8] +@item -mcpu=@var{cpu} This option selects the core processor variant. @item -EB | -EL Select either big-endian (-EB) or little-endian (-EL) output. +@item -mcode-density +Enable Code Density extenssion instructions. @end table @end ifset @@ -1174,6 +1240,24 @@ Generate ``little endian'' format output. @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. @@ -1267,6 +1351,7 @@ behaviour in the shell. @end ifset @ifset MIPS +@c man begin OPTIONS The following options are available when @value{AS} is configured for a MIPS processor. @@ -1404,10 +1489,17 @@ This tells the assembler to accept DSP Release 1 instructions. @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. @@ -1456,6 +1548,17 @@ The @samp{--relax-branch} option enables the relaxation of out-of-range 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. @@ -1491,6 +1594,7 @@ break exception. 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 @@ -1588,6 +1692,25 @@ PowerPC processor. @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. @@ -1606,9 +1729,11 @@ Select the word size, either 31/32 bits or 64 bits. 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. @@ -2021,23 +2146,42 @@ file_name:@b{NNN}:Warning Message Text @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. @@ -2097,6 +2241,7 @@ assembler.) * 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 @@ -2433,6 +2578,15 @@ The rule is written to the file named in its argument. 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} @@ -2619,7 +2773,7 @@ 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}. +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 @@ -2725,10 +2879,15 @@ On most machines, you can also use @code{$} in symbol names; exceptions are noted in @ref{Machine Dependencies}. @end ifset No symbol may begin with a digit. Case is significant. -There is no length limit: all characters are significant. Multibyte characters +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}. + +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 +backslash @code{\} character. @cindex length of symbols @node Statements @@ -2843,11 +3002,19 @@ escape character). The complete list of escapes follows. @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. @@ -2855,12 +3022,12 @@ 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. @@ -2868,8 +3035,8 @@ 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. @@ -2877,7 +3044,7 @@ 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. @@ -2887,20 +3054,20 @@ 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. @@ -2911,7 +3078,7 @@ 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 @@ -2938,12 +3105,13 @@ sequence. @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{;}) @@ -3654,6 +3822,9 @@ on the H8/300), and underscores. Case of letters is significant: @code{foo} is a different symbol name than @code{Foo}. +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 enclose it within double quotes and use escape codes. cf @xref{Strings}. Generating a multibyte symbol name from a label is not @@ -3685,15 +3856,15 @@ to retain the local symbols in the object files. @cindex local labels @cindex temporary symbol names @cindex symbol names, temporary -Local labels help compilers and programmers use names temporarily. -They create symbols which are guaranteed to be unique over the entire scope of -the input source code and which can be referred to by a simple notation. -To define a local label, write a label of the form @samp{@b{N}:} (where @b{N} -represents any positive integer). To refer to the most recent previous -definition of that label write @samp{@b{N}b}, using the same number as when -you defined the label. To refer to the next definition of a local label, write -@samp{@b{N}f}---the @samp{b} stands for ``backwards'' and the @samp{f} stands -for ``forwards''. +Local labels are different from local symbols. Local labels help compilers and +programmers use names temporarily. They create symbols which are guaranteed to +be unique over the entire scope of the input source code and which can be +referred to by a simple notation. To define a local label, write a label of +the form @samp{@b{N}:} (where @b{N} represents any non-negative integer). +To refer to the most recent previous definition of that label write +@samp{@b{N}b}, using the same number as when you defined the label. To refer +to the next definition of a local label, write @samp{@b{N}f}. The @samp{b} +stands for ``backwards'' and the @samp{f} stands for ``forwards''. There is no restriction on how you can use these labels, and you can reuse them too. So that it is possible to repeatedly define the same local label (using @@ -3758,12 +3929,12 @@ the 44th @code{3:} may be named @code{.L3@kbd{C-B}44}. @subheading Dollar Local Labels @cindex dollar local symbols -@code{@value{AS}} also supports an even more local form of local labels called -dollar labels. These labels go out of scope (i.e., they become undefined) as -soon as a non-local label is defined. Thus they remain valid for only a small -region of the input source code. Normal local labels, by contrast, remain in -scope for the entire file, or until they are redefined by another occurrence of -the same local label. +On some targets @code{@value{AS}} also supports an even more local form of +local labels called dollar labels. These labels go out of scope (i.e., they +become undefined) as soon as a non-local label is defined. Thus they remain +valid for only a small region of the input source code. Normal local labels, +by contrast, remain in scope for the entire file, or until they are redefined +by another occurrence of the same local label. Dollar labels are defined in exactly the same way as ordinary local labels, except that they have a dollar sign suffix to their numeric value, e.g., @@ -4194,7 +4365,8 @@ address; you can only have a defined section in one of the two arguments. @cindex pseudo-ops, machine independent @cindex machine independent directives All assembler directives have names that begin with a period (@samp{.}). -The rest of the name is letters, usually in lower case. +The names are case insensitive for most targets, and usually written +in lower case. This chapter discusses directives that are available regardless of the target machine configuration for the @sc{gnu} assembler. @@ -4380,6 +4552,14 @@ Some machine configurations provide additional directives. * Weak:: @code{.weak @var{names}} * Weakref:: @code{.weakref @var{alias}, @var{symbol}} * Word:: @code{.word @var{expressions}} +@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 @@ -4618,6 +4798,17 @@ 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}. +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 @@ -4635,6 +4826,7 @@ unwind entry previously opened by @code{.cfi_startproc}, and emits it to @code{.eh_frame}. @subsection @code{.cfi_personality @var{encoding} [, @var{exp}]} +@cindex @code{cfi_personality} directive @code{.cfi_personality} defines personality routine and its encoding. @var{encoding} must be a constant determining how the personality should be encoded. If it is 255 (@code{DW_EH_PE_omit}), second @@ -4645,13 +4837,46 @@ can be loaded from, not the personality routine itself. The default after @code{.cfi_startproc} is @code{.cfi_personality 0xff}, no personality routine. +@subsection @code{.cfi_personality_id @var{id}} +@cindex @code{cfi_personality_id} directive +@code{cfi_personality_id} defines a personality routine by its index as +defined in a compact unwinding format. +Only valid when generating compact EH frames (i.e. +with @code{.cfi_sections eh_frame_entry}. + +@subsection @code{.cfi_fde_data [@var{opcode1} [, @dots{}]]} +@cindex @code{cfi_fde_data} directive +@code{cfi_fde_data} is used to describe the compact unwind opcodes to be +used for the current function. These are emitted inline in the +@code{.eh_frame_entry} section if small enough and there is no LSDA, or +in the @code{.gnu.extab} section otherwise. +Only valid when generating compact EH frames (i.e. +with @code{.cfi_sections eh_frame_entry}. + @subsection @code{.cfi_lsda @var{encoding} [, @var{exp}]} @code{.cfi_lsda} defines LSDA and its encoding. @var{encoding} must be a constant determining how the LSDA -should be encoded. If it is 255 (@code{DW_EH_PE_omit}), second -argument is not present, otherwise second argument should be a constant +should be encoded. If it is 255 (@code{DW_EH_PE_omit}), the second +argument is not present, otherwise the second argument should be a constant or a symbol name. The default after @code{.cfi_startproc} is @code{.cfi_lsda 0xff}, -no LSDA. +meaning that no LSDA is present. + +@subsection @code{.cfi_inline_lsda} [@var{align}] +@code{.cfi_inline_lsda} marks the start of a LSDA data section and +switches to the corresponding @code{.gnu.extab} section. +Must be preceded by a CFI block containing a @code{.cfi_lsda} directive. +Only valid when generating compact EH frames (i.e. +with @code{.cfi_sections eh_frame_entry}. + +The table header and unwinding opcodes will be generated at this point, +so that they are immediately followed by the LSDA data. The symbol +referenced by the @code{.cfi_lsda} directive should still be defined +in case a fallback FDE based encoding is used. The LSDA data is terminated +by a section directive. + +The optional @var{align} argument specifies the alignment required. +The alignment is specified as a power of two, as with the +@code{.p2align} directive. @subsection @code{.cfi_def_cfa @var{register}, @var{offset}} @code{.cfi_def_cfa} defines a rule for computing CFA as: @i{take @@ -4670,12 +4895,15 @@ CFA address. @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} @@ -4698,11 +4926,54 @@ From now on the previous value of @var{register} can't be restored anymore. 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 @@ -4926,7 +5197,7 @@ The syntax for @code{equ} on the HPPA is @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 @@ -6161,6 +6432,7 @@ ways: 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) @@ -6215,8 +6487,41 @@ For ELF targets, the @code{.section} directive is used like this: .section @var{name} [, "@var{flags}"[, @@@var{type}[,@var{flag_specific_arguments}]]] @end smallexample +@anchor{Section Name Substitutions} +@kindex --sectname-subst +@cindex section name substitution +If the @samp{--sectname-subst} command-line option is provided, the @var{name} +argument may contain a substitution sequence. Only @code{%S} is supported +at the moment, and substitutes the current section name. For example: + +@smallexample +.macro exception_code +.section %S.exception +[exception code here] +.previous +.endm + +.text +[code] +exception_code +[...] + +.section .init +[init code] +exception_code +[...] +@end smallexample + +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 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 @@ -6236,9 +6541,24 @@ section is a member of a section group section is used for thread-local-storage @item ? section is a member of the previously-current section's group, if any +@item @code{} +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{} +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 @@ -6252,14 +6572,23 @@ section contains an array of pointers to init functions section contains an array of pointers to finish functions @item @@preinit_array section contains an array of pointers to pre-init functions +@item @@@code{} +a numeric value to be set as the ELF section header's type field. +@item @@@code{} +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: @@ -6286,6 +6615,7 @@ be present along with an additional field 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 @@ -6321,6 +6651,7 @@ directive for compatibility with the Solaris assembler: Note that the section name is quoted. There may be a sequence of comma separated flags: + @table @code @item #alloc section is allocatable @@ -6351,7 +6682,14 @@ changes @var{symbol}'s value and type to conform to @var{expression}. If @var{symbol} was flagged as external, it remains flagged (@pxref{Symbol Attributes}). -You may @code{.set} a symbol many times in the same assembly. +You may @code{.set} a symbol many times in the same assembly provided that the +values given to the symbol are constants. Values that are based on expressions +involving other symbols are allowed, but some targets may restrict this to only +being done once per assembly. This is because those targets do not set the +addresses of symbols at assembly time, but rather delay the assignment until a +final link is performed. This allows the linker a chance to change the code in +the files, changing the location of, and the relative distance between, various +different symbols. If you @code{.set} a global symbol, the value stored in the object file is the last value stored into it. @@ -6807,7 +7145,7 @@ Mark the symbol as being a data object. @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 @@ -6988,6 +7326,60 @@ assembly language programmers. @end ifset @c end DIFF-TBL-KLUGE +@ifclear no-space-dir +@node Zero +@section @code{.zero @var{size}} + +@cindex @code{zero} directive +@cindex filling memory with zero bytes +This directive emits @var{size} 0-valued bytes. @var{size} must be an absolute +expression. This directive is actually an alias for the @samp{.skip} directive +so in can take an optional second argument of the value to store in the bytes +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 @@ -7126,6 +7518,22 @@ The vector ABI used by this object file. The value will be: @end itemize @end table +@subsection IBM z Systems Attributes + +@table @r +@item Tag_GNU_S390_ABI_Vector (8) +The vector ABI used by this object file. The value will be: + +@itemize @bullet +@item +0 for files not affected by the vector ABI. +@item +1 for files using software vector ABI. +@item +2 for files using hardware vector ABI. +@end itemize +@end table + @node Defining New Object Attributes @section Defining New Object Attributes @@ -7274,9 +7682,15 @@ subject, see the hardware manufacturer's manual. @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 @@ -7314,8 +7728,11 @@ subject, see the hardware manufacturer's manual. @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 @@ -7500,10 +7917,18 @@ family. @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 @@ -7553,6 +7978,10 @@ family. @include c-visium.texi @end ifset +@ifset WASM32 +@include c-wasm32.texi +@end ifset + @ifset XGATE @include c-xgate.texi @end ifset