diff options
Diffstat (limited to 'gas/doc/as.texinfo')
-rw-r--r-- | gas/doc/as.texinfo | 414 |
1 files changed, 229 insertions, 185 deletions
diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo index 92b4cde..78b241e7 100644 --- a/gas/doc/as.texinfo +++ b/gas/doc/as.texinfo @@ -3354,8 +3354,8 @@ 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 instead of being terminated by a colon, they are terminated by a -dollar sign, e.g., @samp{@b{55$}}. +except that they have a dollar sign suffix to their numeric value, e.g., +@samp{@b{55$:}}. They can also be distinguished from ordinary local labels by their transformed names which use ASCII character @samp{\001} (control-A) as the magic character @@ -3373,8 +3373,9 @@ The special symbol @samp{.} refers to the current address that @command{@value{AS}} is assembling into. Thus, the expression @samp{melvin: .long .} defines @code{melvin} to contain its own address. Assigning a value to @code{.} is treated the same as a @code{.org} -directive. Thus, the expression @samp{.=.+4} is the same as saying +directive. @ifclear no-space-dir +Thus, the expression @samp{.=.+4} is the same as saying @samp{.space 4}. @end ifclear @@ -3807,10 +3808,8 @@ Some machine configurations provide additional directives. * Asciz:: @code{.asciz "@var{string}"}@dots{} * Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}} * Byte:: @code{.byte @var{expressions}} -* Comm:: @code{.comm @var{symbol} , @var{length} } - * CFI directives:: @code{.cfi_startproc [simple]}, @code{.cfi_endproc}, etc. - +* Comm:: @code{.comm @var{symbol} , @var{length} } * Data:: @code{.data @var{subsection}} @ifset COFF * Def:: @code{.def @var{name}} @@ -3841,10 +3840,7 @@ Some machine configurations provide additional directives. * Exitm:: @code{.exitm} * Extern:: @code{.extern} * Fail:: @code{.fail} -@ifclear no-file-dir -* File:: @code{.file @var{string}} -@end ifclear - +* File:: @code{.file} * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}} * Float:: @code{.float @var{flonums}} * Func:: @code{.func} @@ -3875,8 +3871,11 @@ Some machine configurations provide additional directives. * Linkonce:: @code{.linkonce [@var{type}]} * List:: @code{.list} * Ln:: @code{.ln @var{line-number}} - -* LNS directives:: @code{.file}, @code{.loc}, etc. +* Loc:: @code{.loc @var{fileno} @var{lineno}} +* Loc_mark_labels:: @code{.loc_mark_labels @var{enable}} +@ifset ELF +* Local:: @code{.local @var{names}} +@end ifset * Long:: @code{.long @var{expressions}} @ignore @@ -3923,10 +3922,14 @@ Some machine configurations provide additional directives. @ifset COFF-ELF * Size:: @code{.size [@var{name} , @var{expression}]} @end ifset - +@ifclear no-space-dir * Skip:: @code{.skip @var{size} , @var{fill}} +@end ifclear + * Sleb128:: @code{.sleb128 @var{expressions}} +@ifclear no-space-dir * Space:: @code{.space @var{size} , @var{fill}} +@end ifclear @ifset have-stabs * Stab:: @code{.stabd, .stabn, .stabs} @end ifset @@ -4035,6 +4038,42 @@ GAS also provides @code{.balign} and @code{.p2align} directives, described later, which have a consistent behavior across all architectures (but are specific to GAS). +@node Altmacro +@section @code{.altmacro} +Enable alternate macro mode, enabling: + +@ftable @code +@item LOCAL @var{name} [ , @dots{} ] +One additional directive, @code{LOCAL}, is available. It is used to +generate a string replacement for each of the @var{name} arguments, and +replace any instances of @var{name} in each macro expansion. The +replacement string is unique in the assembly, and different for each +separate macro expansion. @code{LOCAL} allows you to write macros that +define symbols, without fear of conflict between separate macro expansions. + +@item String delimiters +You can write strings delimited in these other ways besides +@code{"@var{string}"}: + +@table @code +@item '@var{string}' +You can delimit strings with single-quote characters. + +@item <@var{string}> +You can delimit strings with matching angle brackets. +@end table + +@item single-character string escape +To include any single character literally in a string (even if the +character would otherwise have some special meaning), you can prefix the +character with @samp{!} (an exclamation mark). For example, you can +write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}. + +@item Expression results as strings +You can write @samp{%@var{expr}} to evaluate the expression @var{expr} +and use the result as a string. +@end ftable + @node Ascii @section @code{.ascii "@var{string}"}@dots{} @@ -4097,37 +4136,6 @@ undefined. @code{.byte} expects zero or more expressions, separated by commas. Each expression is assembled into the next byte. -@node Comm -@section @code{.comm @var{symbol} , @var{length} } - -@cindex @code{comm} directive -@cindex symbol, common -@code{.comm} declares a common symbol named @var{symbol}. When linking, a -common symbol in one object file may be merged with a defined or common symbol -of the same name in another object file. If @code{@value{LD}} does not see a -definition for the symbol--just one or more common symbols--then it will -allocate @var{length} bytes of uninitialized memory. @var{length} must be an -absolute expression. If @code{@value{LD}} sees multiple common symbols with -the same name, and they do not all have the same size, it will allocate space -using the largest size. - -@ifset ELF -When using ELF, the @code{.comm} directive takes an optional third argument. -This is the desired alignment of the symbol, specified as a byte boundary (for -example, an alignment of 16 means that the least significant 4 bits of the -address should be zero). The alignment must be an absolute expression, and it -must be a power of two. If @code{@value{LD}} allocates uninitialized memory -for the common symbol, it will use the alignment when placing the symbol. If -no alignment is specified, @command{@value{AS}} will set the alignment to the -largest power of two less than or equal to the size of the symbol, up to a -maximum of 16. -@end ifset - -@ifset HPPA -The syntax for @code{.comm} differs slightly on the HPPA. The syntax is -@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional. -@end ifset - @node CFI directives @section @code{.cfi_startproc [simple]} @cindex @code{cfi_startproc} directive @@ -4230,60 +4238,47 @@ Allows the user to add arbitrary bytes to the unwind info. One might use this to add OS-specific CFI opcodes, or generic CFI opcodes that GAS does not yet support. -@node LNS directives -@section @code{.file @var{fileno} @var{filename}} -@cindex @code{file} directive -When emitting dwarf2 line number information @code{.file} assigns filenames -to the @code{.debug_line} file name table. 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. +@section @code{.cfi_val_encoded_addr @var{register}, @var{encoding}, @var{label}} +The current value of @var{register} is @var{label}. The value of @var{label} +will be encoded in the output file according to @var{encoding}; see the +description of @code{.cfi_personality} for details on this encoding. -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. +The usefulness of equating a register to a fixed label is probably +limited to the return address register. Here, it can be useful to +mark a code segment that has only one return address which is reached +by a direct branch and no copy of the return address exists in memory +or another register. -@section @code{.loc @var{fileno} @var{lineno} [@var{column}] [@var{options}]} -@cindex @code{loc} directive -The @code{.loc} directive will add row to the @code{.debug_line} line -number matrix corresponding to the immediately following assembly -instruction. The @var{fileno}, @var{lineno}, and optional @var{column} -arguments will be applied to the @code{.debug_line} state machine before -the row is added. - -The @var{options} are a sequence of the following tokens in any order: - -@table @code -@item basic_block -This option will set the @code{basic_block} register in the -@code{.debug_line} state machine to @code{true}. - -@item prologue_end -This option will set the @code{prologue_end} register in the -@code{.debug_line} state machine to @code{true}. - -@item epilogue_begin -This option will set the @code{epilogue_begin} register in the -@code{.debug_line} state machine to @code{true}. - -@item is_stmt @var{value} -This option will set the @code{is_stmt} register in the -@code{.debug_line} state machine to @code{value}, which must be -either 0 or 1. +@node Comm +@section @code{.comm @var{symbol} , @var{length} } -@item isa @var{value} -This directive will set the @code{isa} register in the @code{.debug_line} -state machine to @var{value}, which must be an unsigned integer. +@cindex @code{comm} directive +@cindex symbol, common +@code{.comm} declares a common symbol named @var{symbol}. When linking, a +common symbol in one object file may be merged with a defined or common symbol +of the same name in another object file. If @code{@value{LD}} does not see a +definition for the symbol--just one or more common symbols--then it will +allocate @var{length} bytes of uninitialized memory. @var{length} must be an +absolute expression. If @code{@value{LD}} sees multiple common symbols with +the same name, and they do not all have the same size, it will allocate space +using the largest size. -@end table +@ifset ELF +When using ELF, the @code{.comm} directive takes an optional third argument. +This is the desired alignment of the symbol, specified as a byte boundary (for +example, an alignment of 16 means that the least significant 4 bits of the +address should be zero). The alignment must be an absolute expression, and it +must be a power of two. If @code{@value{LD}} allocates uninitialized memory +for the common symbol, it will use the alignment when placing the symbol. If +no alignment is specified, @command{@value{AS}} will set the alignment to the +largest power of two less than or equal to the size of the symbol, up to a +maximum of 16. +@end ifset -@section @code{.loc_mark_labels @var{enable}} -@cindex @code{loc_mark_labels} directive -The @code{.loc_mark_labels} directive makes the assembler emit an entry -to the @code{.debug_line} line number matrix with the @code{basic_block} -register in the state machine set whenever a code label is seen. -The @var{enable} argument should be either 1 or 0, to enable or disable -this function respectively. +@ifset HPPA +The syntax for @code{.comm} differs slightly on the HPPA. The syntax is +@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional. +@end ifset @node Data @section @code{.data @var{subsection}} @@ -4515,21 +4510,51 @@ than 500, @command{@value{AS}} will print an error message. The message will include the value of @var{expression}. This can occasionally be useful inside complex nested macros or conditional assembly. -@ifclear no-file-dir @node File -@section @code{.file @var{string}} - +@section @code{.file} @cindex @code{file} directive + +@ifclear no-file-dir +There are two different versions of the @code{.file} directive. Targets +that support DWARF2 line number information use the DWARF2 version of +@code{.file}. Other targets use the default version. + +@subheading Default Version + @cindex logical file name @cindex file name, logical -@code{.file} tells @command{@value{AS}} that we are about to start a new logical -file. @var{string} is the new file name. In general, the filename is +This version of the @code{.file} directive tells @command{@value{AS}} that we +are about to start a new logical file. The syntax is: + +@smallexample +.file @var{string} +@end smallexample + +@var{string} is the new file name. In general, the filename is recognized whether or not it is surrounded by quotes @samp{"}; but if you wish to specify an empty file name, you must give the quotes--@code{""}. This statement may go away in future: it is only recognized to be compatible with old @command{@value{AS}} programs. + +@subheading DWARF2 Version @end ifclear +When emitting DWARF2 line number information, @code{.file} assigns filenames +to the @code{.debug_line} file name table. The syntax is: + +@smallexample +.file @var{fileno} @var{filename} +@end smallexample + +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. + +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. + @node Fill @section @code{.fill @var{repeat} , @var{size} , @var{value}} @@ -4910,13 +4935,6 @@ assemblers, but ignores it. @section @code{.line @var{line-number}} @cindex @code{line} directive -@end ifclear -@ifset no-line-dir -@node Ln -@section @code{.ln @var{line-number}} - -@cindex @code{ln} directive -@end ifset @cindex logical line number @ifset aout-bout Change the logical line number. @var{line-number} must be an absolute @@ -4925,10 +4943,8 @@ statements on the current line (after a statement separator character) are reported as on logical line number @var{line-number} @minus{} 1. One day @command{@value{AS}} will no longer support this directive: it is recognized only for compatibility with existing assembler programs. - @end ifset -@ifclear no-line-dir Even though this is a directive associated with the @code{a.out} or @code{b.out} object-code formats, @command{@value{AS}} still recognizes it when producing COFF output, and treats @samp{.line} as though it @@ -4977,6 +4993,21 @@ Warn if any of the duplicates have different sizes. Warn if any of the duplicates do not have exactly the same contents. @end table +@node List +@section @code{.list} + +@cindex @code{list} directive +@cindex listing control, turning on +Control (in conjunction with the @code{.nolist} directive) whether or +not assembly listings are generated. These two directives maintain an +internal counter (which is zero initially). @code{.list} increments the +counter, and @code{.nolist} decrements it. Assembly listings are +generated whenever the counter is greater than zero. + +By default, listings are disabled. When you enable them (with the +@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}), +the initial value of the listing counter is one. + @node Ln @section @code{.ln @var{line-number}} @@ -4998,30 +5029,67 @@ output format. @end ifset @end ifset -@node MRI -@section @code{.mri @var{val}} +@node Loc +@section @code{.loc @var{fileno} @var{lineno} [@var{column}] [@var{options}]} +@cindex @code{loc} directive +When emitting DWARF2 line number information, +the @code{.loc} directive will add a row to the @code{.debug_line} line +number matrix corresponding to the immediately following assembly +instruction. The @var{fileno}, @var{lineno}, and optional @var{column} +arguments will be applied to the @code{.debug_line} state machine before +the row is added. -@cindex @code{mri} directive -@cindex MRI mode, temporarily -If @var{val} is non-zero, this tells @command{@value{AS}} to enter MRI mode. If -@var{val} is zero, this tells @command{@value{AS}} to exit MRI mode. This change -affects code assembled until the next @code{.mri} directive, or until the end -of the file. @xref{M, MRI mode, MRI mode}. +The @var{options} are a sequence of the following tokens in any order: -@node List -@section @code{.list} +@table @code +@item basic_block +This option will set the @code{basic_block} register in the +@code{.debug_line} state machine to @code{true}. -@cindex @code{list} directive -@cindex listing control, turning on -Control (in conjunction with the @code{.nolist} directive) whether or -not assembly listings are generated. These two directives maintain an -internal counter (which is zero initially). @code{.list} increments the -counter, and @code{.nolist} decrements it. Assembly listings are -generated whenever the counter is greater than zero. +@item prologue_end +This option will set the @code{prologue_end} register in the +@code{.debug_line} state machine to @code{true}. -By default, listings are disabled. When you enable them (with the -@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}), -the initial value of the listing counter is one. +@item epilogue_begin +This option will set the @code{epilogue_begin} register in the +@code{.debug_line} state machine to @code{true}. + +@item is_stmt @var{value} +This option will set the @code{is_stmt} register in the +@code{.debug_line} state machine to @code{value}, which must be +either 0 or 1. + +@item isa @var{value} +This directive will set the @code{isa} register in the @code{.debug_line} +state machine to @var{value}, which must be an unsigned integer. + +@end table + +@node Loc_mark_labels +@section @code{.loc_mark_labels @var{enable}} +@cindex @code{loc_mark_labels} directive +When emitting DWARF2 line number information, +the @code{.loc_mark_labels} directive makes the assembler emit an entry +to the @code{.debug_line} line number matrix with the @code{basic_block} +register in the state machine set whenever a code label is seen. +The @var{enable} argument should be either 1 or 0, to enable or disable +this function respectively. + +@ifset ELF +@node Local +@section @code{.local @var{names}} + +@cindex @code{local} directive +This directive, which is available for ELF targets, marks each symbol in +the comma-separated list of @code{names} as a local symbol so that it +will not be externally visible. If the symbols do not already exist, +they will be created. + +For targets where the @code{.lcomm} directive (@pxref{Lcomm}) does not +accept an alignment argument, which is the case for most ELF targets, +the @code{.local} directive can be used in combination with @code{.comm} +(@pxref{Comm}) to define aligned local common data. +@end ifset @node Long @section @code{.long @var{expressions}} @@ -5224,41 +5292,15 @@ macro syntax'' with @samp{--alternate} or @code{.altmacro}.} @xref{Altmacro,,@code{.altmacro}}. @end ftable -@node Altmacro -@section @code{.altmacro} -Enable alternate macro mode, enabling: - -@ftable @code -@item LOCAL @var{name} [ , @dots{} ] -One additional directive, @code{LOCAL}, is available. It is used to -generate a string replacement for each of the @var{name} arguments, and -replace any instances of @var{name} in each macro expansion. The -replacement string is unique in the assembly, and different for each -separate macro expansion. @code{LOCAL} allows you to write macros that -define symbols, without fear of conflict between separate macro expansions. - -@item String delimiters -You can write strings delimited in these other ways besides -@code{"@var{string}"}: - -@table @code -@item '@var{string}' -You can delimit strings with single-quote characters. - -@item <@var{string}> -You can delimit strings with matching angle brackets. -@end table - -@item single-character string escape -To include any single character literally in a string (even if the -character would otherwise have some special meaning), you can prefix the -character with @samp{!} (an exclamation mark). For example, you can -write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}. +@node MRI +@section @code{.mri @var{val}} -@item Expression results as strings -You can write @samp{%@var{expr}} to evaluate the expression @var{expr} -and use the result as a string. -@end ftable +@cindex @code{mri} directive +@cindex MRI mode, temporarily +If @var{val} is non-zero, this tells @command{@value{AS}} to enter MRI mode. If +@var{val} is zero, this tells @command{@value{AS}} to exit MRI mode. This change +affects code assembled until the next @code{.mri} directive, or until the end +of the file. @xref{M, MRI mode, MRI mode}. @node Noaltmacro @section @code{.noaltmacro} @@ -5362,6 +5404,22 @@ the endianness of the processor). If it skips 1 or 3 bytes, the fill value is undefined. @ifset ELF +@node PopSection +@section @code{.popsection} + +@cindex @code{popsection} directive +@cindex Section Stack +This is one of the ELF section stack manipulation directives. The others are +@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}), +@code{.pushsection} (@pxref{PushSection}), and @code{.previous} +(@pxref{Previous}). + +This directive replaces the current section (and subsection) with the top +section (and subsection) on the section stack. This section is popped off the +stack. +@end ifset + +@ifset ELF @node Previous @section @code{.previous} @@ -5414,22 +5472,6 @@ In terms of the section stack, this directive swaps the current section with the top section on the section stack. @end ifset -@ifset ELF -@node PopSection -@section @code{.popsection} - -@cindex @code{popsection} directive -@cindex Section Stack -This is one of the ELF section stack manipulation directives. The others are -@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}), -@code{.pushsection} (@pxref{PushSection}), and @code{.previous} -(@pxref{Previous}). - -This directive replaces the current section (and subsection) with the top -section (and subsection) on the section stack. This section is popped off the -stack. -@end ifset - @node Print @section @code{.print @var{string}} @@ -5887,14 +5929,6 @@ symbols. @end ifset @end ifset -@node Sleb128 -@section @code{.sleb128 @var{expressions}} - -@cindex @code{sleb128} directive -@var{sleb128} stands for ``signed little endian base 128.'' This is a -compact, variable length representation of numbers used by the DWARF -symbolic debugging format. @xref{Uleb128, ,@code{.uleb128}}. - @ifclear no-space-dir @node Skip @section @code{.skip @var{size} , @var{fill}} @@ -5905,7 +5939,17 @@ This directive emits @var{size} bytes, each of value @var{fill}. Both @var{size} and @var{fill} are absolute expressions. If the comma and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as @samp{.space}. +@end ifclear + +@node Sleb128 +@section @code{.sleb128 @var{expressions}} + +@cindex @code{sleb128} directive +@var{sleb128} stands for ``signed little endian base 128.'' This is a +compact, variable length representation of numbers used by the DWARF +symbolic debugging format. @xref{Uleb128, ,@code{.uleb128}}. +@ifclear no-space-dir @node Space @section @code{.space @var{size} , @var{fill}} |