X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gas%2Fdoc%2Fas.texi;h=f8d892eaa5c1771237189a6963285fb60e6a3197;hb=efb763a5ea351f9d865cbe491909f03472ebf2d6;hp=acecd35225f48127700bb3e41c62897bf0fb68b1;hpb=1f041c6edf49a896b99db253066fce427a7d2264;p=deliverable%2Fbinutils-gdb.git diff --git a/gas/doc/as.texi b/gas/doc/as.texi index acecd35225..f8d892eaa5 100644 --- a/gas/doc/as.texi +++ b/gas/doc/as.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-Texinfo-*- -@c Copyright (C) 1991-2018 Free Software Foundation, Inc. +@c Copyright (C) 1991-2020 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 @@ -40,6 +40,9 @@ @ifset Blackfin @set Blackfin @end ifset +@ifset BPF +@set BPF +@end ifset @ifset H8/300 @set H8 @end ifset @@ -97,7 +100,7 @@ This file documents the GNU Assembler "@value{AS}". @c man begin COPYRIGHT -Copyright @copyright{} 1991-2018 Free Software Foundation, Inc. +Copyright @copyright{} 1991-2020 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 @@ -146,7 +149,7 @@ done. @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 1991-2018 Free Software Foundation, Inc. +Copyright @copyright{} 1991-2020 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 @@ -227,7 +230,8 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. [@b{--compress-debug-sections}] [@b{--nocompress-debug-sections}] [@b{--debug-prefix-map} @var{old}=@var{new}] [@b{--defsym} @var{sym}=@var{val}] [@b{-f}] [@b{-g}] [@b{--gstabs}] - [@b{--gstabs+}] [@b{--gdwarf-2}] [@b{--gdwarf-sections}] + [@b{--gstabs+}] [@b{--gdwarf-}] [@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}] @@ -296,6 +300,11 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. [@b{-mno-fdpic}] [@b{-mnopic}] @end ifset +@ifset BPF + +@emph{Target BPF options:} + [@b{-EL}] [@b{-EB}] +@end ifset @ifset CRIS @emph{Target CRIS options:} @@ -453,6 +462,7 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. [@b{-mfix-rm7000}] [@b{-mno-fix-rm7000}] [@b{-mfix-vr4120}] [@b{-mno-fix-vr4120}] [@b{-mfix-vr4130}] [@b{-mno-fix-vr4130}] + [@b{-mfix-r5900}] [@b{-mno-fix-r5900}] [@b{-mdebug}] [@b{-no-mdebug}] [@b{-mpdr}] [@b{-mno-pdr}] @end ifset @@ -616,17 +626,17 @@ gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. [@b{--[no-]transform}] [@b{--rename-section} @var{oldname}=@var{newname}] [@b{--[no-]trampolines}] + [@b{--abi-windowed}|@b{--abi-call0}] @end ifset @ifset Z80 @emph{Target Z80 options:} - [@b{-z80}] [@b{-r800}] - [@b{ -ignore-undocumented-instructions}] [@b{-Wnud}] - [@b{ -ignore-unportable-instructions}] [@b{-Wnup}] - [@b{ -warn-undocumented-instructions}] [@b{-Wud}] - [@b{ -warn-unportable-instructions}] [@b{-Wup}] - [@b{ -forbid-undocumented-instructions}] [@b{-Fud}] - [@b{ -forbid-unportable-instructions}] [@b{-Fup}] + [@b{-march=@var{CPU}@var{[-EXT]}@var{[+EXT]}}] + [@b{-local-prefix=}@var{PREFIX}] + [@b{-colonless}] + [@b{-sdcc}] + [@b{-fp-s=}@var{FORMAT}] + [@b{-fp-d=}@var{FORMAT}] @end ifset @ifset Z8000 @@ -754,6 +764,27 @@ Generate DWARF2 debugging information for each assembler line. This may help debugging assembler code, if the debugger can handle it. Note---this option is only supported by some targets, not all of them. +@item --gdwarf-3 +This option is the same as the @option{--gdwarf-2} option, except that it +allows for the possibility of the generation of extra debug information as per +version 3 of the DWARF specification. Note - enabling this option does not +guarantee the generation of any extra infortmation, the choice to do so is on a +per target basis. + +@item --gdwarf-4 +This option is the same as the @option{--gdwarf-2} option, except that it +allows for the possibility of the generation of extra debug information as per +version 4 of the DWARF specification. Note - enabling this option does not +guarantee the generation of any extra infortmation, the choice to do so is on a +per target basis. + +@item --gdwarf-5 +This option is the same as the @option{--gdwarf-2} option, except that it +allows for the possibility of the generation of extra debug information as per +version 5 of the DWARF specification. Note - enabling this option does not +guarantee the generation of any extra infortmation, the choice to do so is on a +per target basis. + @item --gdwarf-sections Instead of creating a .debug_line section, create a series of .debug_line.@var{foo} sections where @var{foo} is the name of the @@ -763,6 +794,11 @@ 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. +@item --gdwarf-cie-version=@var{version} +Control which version of DWARF Common Information Entries (CIEs) are produced. +When this flag is not specificed the default is version 1, though some targets +can modify this default. Other possible values for @var{version} are 3 or 4. + @ifset ELF @item --size-check=error @itemx --size-check=warning @@ -1000,6 +1036,25 @@ the Blackfin processor family. @end ifset +@ifset BPF + +@ifclear man +@xref{BPF Options}, for the options available when @value{AS} is +configured for the Linux kernel BPF processor family. +@end ifclear + +@ifset man +@c man begin OPTIONS +The following options are available when @value{AS} is configured for +the Linux kernel BPF processor family. +@c man end +@c man begin INCLUDE +@include c-bpf.texi +@c ended inside the included file +@end ifset + +@end ifset + @c man begin OPTIONS @ifset CRIS See the info pages for documentation of the CRIS-specific options. @@ -1444,6 +1499,14 @@ of an mfhi or mflo instruction occurs in the following two instructions. Cause nops to be inserted if a dmult or dmultu instruction is followed by a load instruction. +@item -mfix-r5900 +@itemx -mno-fix-r5900 +Do not attempt to schedule the preceding instruction into the delay slot +of a branch instruction placed at the end of a short loop of six +instructions or fewer and always schedule a @code{nop} instruction there +instead. The short loop bug under certain conditions causes loops to +execute only once or twice, due to a hardware bug in the R5900 chip. + @item -mdebug @itemx -no-mdebug Cause stabs-style debugging output to go into an ECOFF-style .mdebug @@ -1807,7 +1870,8 @@ 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{z14} (or @samp{arch12}). +@samp{z13} (or @samp{arch11}), @samp{z14} (or @samp{arch12}), or @samp{z15} +(or @samp{arch13}). @item -mregnames @itemx -mno-regnames Allow or disallow symbolic names for registers. @@ -1894,38 +1958,24 @@ Xtensa processor. @end ifset -@c man begin OPTIONS - @ifset Z80 -The following options are available when @value{AS} is configured for -a Z80 family processor. -@table @gcctabopt -@item -z80 -Assemble for Z80 processor. -@item -r800 -Assemble for R800 processor. -@item -ignore-undocumented-instructions -@itemx -Wnud -Assemble undocumented Z80 instructions that also work on R800 without warning. -@item -ignore-unportable-instructions -@itemx -Wnup -Assemble all undocumented Z80 instructions without warning. -@item -warn-undocumented-instructions -@itemx -Wud -Issue a warning for undocumented Z80 instructions that also work on R800. -@item -warn-unportable-instructions -@itemx -Wup -Issue a warning for undocumented Z80 instructions that do not work on R800. -@item -forbid-undocumented-instructions -@itemx -Fud -Treat all undocumented instructions as errors. -@item -forbid-unportable-instructions -@itemx -Fup -Treat undocumented Z80 instructions that do not work on R800 as errors. -@end table -@end ifset +@ifclear man +@xref{Z80 Options}, for the options available when @value{AS} is configured +for an Z80 processor. +@end ifclear + +@ifset man +@c man begin OPTIONS +The following options are available when @value{AS} is configured for an +Z80 processor. @c man end +@c man begin INCLUDE +@include c-z80.texi +@c ended inside the included file +@end ifset + +@end ifset @menu * Manual:: Structure of this Manual @@ -2793,8 +2843,9 @@ anything else you may get from your C compiler's preprocessor. You can 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}. +@samp{.S} suffix. @url{https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#Overall-Options, +See the 'Options Controlling the Kind of Output' section of the GCC manual for +more details} Excess whitespace, comments, and character constants cannot be used in the portions of the input text that are not @@ -4318,11 +4369,11 @@ Some machine configurations provide additional directives. * ABORT (COFF):: @code{.ABORT} @end ifset -* Align:: @code{.align @var{abs-expr} , @var{abs-expr}} +* Align:: @code{.align [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]} * Altmacro:: @code{.altmacro} * Ascii:: @code{.ascii "@var{string}"}@dots{} * Asciz:: @code{.asciz "@var{string}"}@dots{} -* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}} +* Balign:: @code{.balign [@var{abs-expr}[, @var{abs-expr}]]} * Bundle directives:: @code{.bundle_align_mode @var{abs-expr}}, etc * Byte:: @code{.byte @var{expressions}} * CFI directives:: @code{.cfi_startproc [simple]}, @code{.cfi_endproc}, etc. @@ -4410,7 +4461,7 @@ Some machine configurations provide additional directives. * Octa:: @code{.octa @var{bignums}} * Offset:: @code{.offset @var{loc}} * Org:: @code{.org @var{new-lc}, @var{fill}} -* P2align:: @code{.p2align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} +* P2align:: @code{.p2align [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]} @ifset ELF * PopSection:: @code{.popsection} * Previous:: @code{.previous} @@ -4460,7 +4511,7 @@ Some machine configurations provide additional directives. * Struct:: @code{.struct @var{expression}} @ifset ELF * SubSection:: @code{.subsection} -* Symver:: @code{.symver @var{name},@var{name2@@nodename}} +* Symver:: @code{.symver @var{name},@var{name2@@nodename}[,@var{visibility}]} @end ifset @ifset COFF @@ -4521,13 +4572,14 @@ synonym for @samp{.abort}. @end ifset @node Align -@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} +@section @code{.align [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]} @cindex padding the location counter @cindex @code{align} directive Pad the location counter (in the current subsection) to a particular storage boundary. The first expression (which must be absolute) is the alignment -required, as described below. +required, as described below. If this expression is omitted then a default +value of 0 is used, effectively disabling alignment requirements. The second expression (also absolute) gives the fill value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the @@ -4545,7 +4597,7 @@ with no-op instructions when appropriate. The way the required alignment is specified varies from system to system. For the arc, hppa, i386 using ELF, iq2000, m68k, or1k, -s390, sparc, tic4x, tic80 and xtensa, the first expression is the +s390, sparc, tic4x and xtensa, the first expression is the alignment request in bytes. For example @samp{.align 8} advances the location counter until it is a multiple of 8. If the location counter is already a multiple of 8, no change is needed. For the tic54x, the @@ -4555,7 +4607,7 @@ For other systems, including ppc, i386 using a.out format, arm and strongarm, it is the number of low-order zero bits the location counter must have after advancement. For example @samp{.align 3} advances the location -counter until it a multiple of 8. If the location counter is already a +counter until it is a multiple of 8. If the location counter is already a multiple of 8, no change is needed. This inconsistency is due to the different behaviors of the various @@ -4619,7 +4671,7 @@ trailing zero byte) into consecutive addresses. a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. @node Balign -@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} +@section @code{.balign[wl] [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]} @cindex padding the location counter given number of bytes @cindex @code{balign} directive @@ -4627,7 +4679,8 @@ Pad the location counter (in the current subsection) to a particular storage boundary. The first expression (which must be absolute) is the alignment request in bytes. For example @samp{.balign 8} advances the location counter until it is a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. +is already a multiple of 8, no change is needed. If the expression is omitted +then a default value of 0 is used, effectively disabling alignment requirements. The second expression (also absolute) gives the fill value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the @@ -5315,13 +5368,29 @@ to the @code{.debug_line} file name table. The syntax is: The @var{fileno} operand should be a unique positive integer to use as the index of the entry in the table. The @var{filename} operand is a C string -literal. +literal enclosed in double quotes. The @var{filename} can include directory +elements. If it does, then the directory will be added to the directory table +and the basename will be added to the file table. The detail of filename indices is exposed to the user because the filename table is shared with the @code{.debug_info} section of the DWARF2 debugging information, and thus the user must know the exact indices that table entries will have. +If DWARF-5 support has been enabled via the @option{-gdwarf-5} option then +an extended version of the @code{file} is also allowed: + +@smallexample +.file @var{fileno} [@var{dirname}] @var{filename} [md5 @var{value}] +@end smallexample + +With this version a separate directory name is allowed, although if this is +used then @var{filename} should not contain any directory components. In +addtion an md5 hash value of the contents of @var{filename} can be provided. +This will be stored in the the file table as well, and can be used by tools +reading the debug information to verify that the contents of the source file +match the contents of the compiled file. + @node Fill @section @code{.fill @var{repeat} , @var{size} , @var{value}} @@ -6172,7 +6241,7 @@ absolute expression. If the comma and @var{fill} are omitted, @var{fill} defaults to zero. @node P2align -@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} +@section @code{.p2align[wl] [@var{abs-expr}[, @var{abs-expr}[, @var{abs-expr}]]]} @cindex padding the location counter given a power of two @cindex @code{p2align} directive @@ -6180,8 +6249,9 @@ Pad the location counter (in the current subsection) to a particular storage boundary. The first expression (which must be absolute) is the number of low-order zero bits the location counter must have after advancement. For example @samp{.p2align 3} advances the location -counter until it a multiple of 8. If the location counter is already a -multiple of 8, no change is needed. +counter until it is a multiple of 8. If the location counter is already a +multiple of 8, no change is needed. If the expression is omitted then a +default value of 0 is used, effectively disabling alignment requirements. The second expression (also absolute) gives the fill value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the @@ -6559,6 +6629,9 @@ section is allocatable section is a GNU_MBIND section @item e section is excluded from executable and shared library. +@item o +section references a symbol defined in another section (the linked-to +section) in the same file. @item w section is writable @item x @@ -6638,6 +6711,23 @@ which is a suffix of a larger string is considered a duplicate. Thus @code{"def"} will be merged with @code{"abcdef"}; A reference to the first @code{"def"} will be changed to a reference to @code{"abcdef"+3}. +If @var{flags} contains the @code{o} flag, then the @var{type} argument +must be present along with an additional field like this: + +@smallexample +.section @var{name},"@var{flags}"o,@@@var{type},@var{SymbolName} +@end smallexample + +The @var{SymbolName} field specifies the symbol name which the section +references. + +Note: If both the @var{M} and @var{o} flags are present, then the fields +for the Merge flag should come first, like this: + +@smallexample +.section @var{name},"@var{flags}"Mo,@@@var{type},@var{entsize},@var{SymbolName} +@end smallexample + If @var{flags} contains the @code{G} symbol then the @var{type} argument must be present along with an additional field like this: @@ -6662,6 +6752,13 @@ the Merge flag should come first, like this: .section @var{name} , "@var{flags}"MG, @@@var{type}, @var{entsize}, @var{GroupName}[, @var{linkage}] @end smallexample +If both @code{o} flag and @code{G} flag are present, then the +@var{SymbolName} field for @code{o} comes first, like this: + +@smallexample +.section @var{name},"@var{flags}"oG,@@@var{type},@var{SymbolName},@var{GroupName}[,@var{linkage}] +@end smallexample + If @var{flags} contains the @code{?} symbol then it may not also contain the @code{G} symbol and the @var{GroupName} or @var{linkage} fields should not be present. Instead, @code{?} says to consider the section that's current before @@ -6669,6 +6766,18 @@ this directive. If that section used @code{G}, then the new section will use @code{G} with those same @var{GroupName} and @var{linkage} fields implicitly. If not, then the @code{?} symbol has no effect. +The optional @var{unique,@code{}} argument must come last. It +assigns @var{@code{}} as a unique section ID to distinguish +different sections with the same section name like these: + +@smallexample +.section @var{name},"@var{flags}",@@@var{type},@var{unique,@code{}} +.section @var{name},"@var{flags}"G,@@@var{type},@var{GroupName},[@var{linkage}],@var{unique,@code{}} +.section @var{name},"@var{flags}"MG,@@@var{type},@var{entsize},@var{GroupName}[,@var{linkage}],@var{unique,@code{}} +@end smallexample + +The valid values of @var{@code{}} are between 0 and 4294967295. + If no flags are specified, the default flags depend upon the section name. If the section name is not recognized, the default will be for the section to have none of the above flags: it will not be allocated in memory, nor writable, nor @@ -6727,7 +6836,7 @@ If you @code{.set} a global symbol, the value stored in the object file is the last value stored into it. @ifset Z80 -On Z80 @code{set} is a real instruction, use +On Z80 @code{set} is a real instruction, use @code{.set} or @samp{@var{symbol} defl @var{expression}} instead. @end ifset @@ -7005,9 +7114,9 @@ shared library. For ELF targets, the @code{.symver} directive can be used like this: @smallexample -.symver @var{name}, @var{name2@@nodename} +.symver @var{name}, @var{name2@@nodename}[ ,@var{visibility}] @end smallexample -If the symbol @var{name} is defined within the file +If the original symbol @var{name} is defined within the file being assembled, the @code{.symver} directive effectively creates a symbol alias with the name @var{name2@@nodename}, and in fact the main reason that we just don't try and create a regular alias is that the @var{@@} character isn't @@ -7020,7 +7129,14 @@ function is being mentioned. The @var{nodename} portion of the alias should be the name of a node specified in the version script supplied to the linker when building a shared library. If you are attempting to override a versioned symbol from a shared library, then @var{nodename} should correspond to the -nodename of the symbol you are trying to override. +nodename of the symbol you are trying to override. The optional argument +@var{visibility} updates the visibility of the original symbol. The valid +visibilities are @code{local}, @code{hidden}, and @code{remove}. The +@code{local} visibility makes the original symbol a local symbol +(@pxref{Local}). The @code{hidden} visibility sets the visibility of the +original symbol to @code{hidden} (@pxref{Hidden}). The @code{remove} +visibility removes the original symbol from the symbol table. If visibility +isn't specified, the original symbol is unchanged. If the symbol @var{name} is not defined within the file being assembled, all references to @var{name} will be changed to @var{name2@@nodename}. If no @@ -7179,6 +7295,10 @@ systems). @end table +Changing between incompatible types other than from/to STT_NOTYPE will +result in a diagnostic. An intermediate change to STT_NOTYPE will silence +this. + Note: Some targets support extra types in addition to those listed above. @end ifset @@ -7345,7 +7465,7 @@ assembly language programmers. @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 +so it 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 @@ -7545,6 +7665,23 @@ The vector ABI used by this object file. The value will be: @end itemize @end table +@subsection MSP430 Attributes + +@table @r +@item Tag_GNU_MSP430_Data_Region (4) +The data region used by this object file. The value will be: + +@itemize @bullet +@item +0 for files not using the large memory model. +@item +1 for files which have been compiled with the condition that all +data is in the lower memory region, i.e. below address 0x10000. +@item +2 for files which allow data to be placed in the full 20-bit memory range. +@end itemize +@end table + @node Defining New Object Attributes @section Defining New Object Attributes @@ -7606,6 +7743,9 @@ subject, see the hardware manufacturer's manual. @ifset Blackfin * Blackfin-Dependent:: Blackfin Dependent Features @end ifset +@ifset BPF +* BPF-Dependent:: BPF Dependent Features +@end ifset @ifset CR16 * CR16-Dependent:: CR16 Dependent Features @end ifset @@ -7655,7 +7795,7 @@ subject, see the hardware manufacturer's manual. * M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features @end ifset @ifset S12Z -* S12Z-Dependent:: S12Z Dependent Features +* S12Z-Dependent:: S12Z Dependent Features @end ifset @ifset METAG * Meta-Dependent :: Meta Dependent Features @@ -7793,6 +7933,10 @@ subject, see the hardware manufacturer's manual. @include c-bfin.texi @end ifset +@ifset BPF +@include c-bpf.texi +@end ifset + @ifset CR16 @include c-cr16.texi @end ifset