diff options
| -rw-r--r-- | gas/ChangeLog | 4 | ||||
| -rw-r--r-- | gas/doc/as.texinfo | 128 |
2 files changed, 115 insertions, 17 deletions
diff --git a/gas/ChangeLog b/gas/ChangeLog index cb86b17..754dccf 100644 --- a/gas/ChangeLog +++ b/gas/ChangeLog @@ -1,3 +1,7 @@ +Thu Mar 20 19:18:58 1997 Ian Lance Taylor <ian@cygnus.com> + + * doc/as.texinfo (Symbol Names): Don't use obsolete @ctrl macro. + Thu Mar 20 16:49:14 1997 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * config/tc-m68k.c (mri_chip): Replace calls to get_symbol_end by diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo index 864229a..739ffc8 100644 --- a/gas/doc/as.texinfo +++ b/gas/doc/as.texinfo @@ -195,7 +195,7 @@ Here is a brief summary of how to invoke @code{@value{AS}}. For details, @c We don't use deffn and friends for the following because they seem @c to be limited to one line for the header. @smallexample -@value{AS} [ -a[dhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ] +@value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ] [ -f ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] [ -version ] [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ] @@ -862,7 +862,7 @@ precisely what options it passes to each compilation pass, including the assembler.) @menu -* a:: -a[dhlns] enable listings +* a:: -a[cdhlns] enable listings * D:: -D for compatibility * f:: -f to work faster * I:: -I for .include search path @@ -884,9 +884,10 @@ assembler.) @end menu @node a -@section Enable Listings: @code{-a[dhlns]} +@section Enable Listings: @code{-a[cdhlns]} @kindex -a +@kindex -ac @kindex -ad @kindex -ah @kindex -al @@ -905,6 +906,11 @@ High-level listings require that a compiler debugging option like @samp{-g} be used, and that assembly listings (@samp{-al}) be requested also. +Use the @samp{-ac} option to omit false conditionals from a listing. Any lines +which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any +other conditional), or a true @code{.if} followed by an @code{.else}, will be +omitted from the listing. + Use the @samp{-ad} option to omit debugging directives from the listing. @@ -2324,10 +2330,19 @@ not dictate data to load into it before your program executes. When your program starts running, all the contents of the bss section are zeroed bytes. -Addresses in the bss section are allocated with special directives; you -may not assemble anything directly into the bss section. Hence there -are no bss subsections. @xref{Comm,,@code{.comm}}, -@pxref{Lcomm,,@code{.lcomm}}. +The @code{.lcomm} pseudo-op defines a symbol in the bss section; see +@ref{Lcomm,,@code{.lcomm}}. + +The @code{.comm} pseudo-op may be used to declare a common symbol, which is +another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}. + +@ifset GENERIC +When assembling for a target which supports multiple sections, such as ELF or +COFF, you may switch into the @code{.bss} section and define symbols as usual; +see @ref{Section,,@code{.section}}. You may only assemble zero values into the +section. Typically the section will only contain symbol definitions and +@code{.skip} directives (@pxref{Skip,,@code{.skip}}). +@end ifset @node Symbols @chapter Symbols @@ -2456,7 +2471,7 @@ If the label is written @samp{0:} then the digit is @samp{0}. If the label is written @samp{1:} then the digit is @samp{1}. And so on up through @samp{9:}. -@item @ctrl{A} +@item @kbd{C-A} This unusual character is included so you do not accidentally invent a symbol of the same name. The character has ASCII value @samp{\001}. @@ -2468,8 +2483,8 @@ number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:} through @samp{9:}. @end table -For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th -@code{3:} is named @code{L3@ctrl{A}44}. +For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th +@code{3:} is named @code{L3@kbd{C-A}44}. @node Dot @section The Special Dot Symbol @@ -2908,6 +2923,8 @@ Some machine configurations provide additional directives. * Endif:: @code{.endif} * Equ:: @code{.equ @var{symbol}, @var{expression}} +* Equiv:: @code{.equiv @var{symbol}, @var{expression}} +* Err:: @code{.err} * Extern:: @code{.extern} @ifclear no-file-dir * File:: @code{.file @var{string}} @@ -2969,6 +2986,9 @@ Some machine configurations provide additional directives. @end ifset * String:: @code{.string "@var{str}"} +@ifset ELF +* Symver:: @code{.symver @var{name},@var{name2@@nodename}} +@end ifset @ifset COFF * Tag:: @code{.tag @var{structname}} @end ifset @@ -3137,13 +3157,26 @@ Each expression is assembled into the next byte. @cindex @code{comm} directive @cindex symbol, common -@code{.comm} declares a named common area in the bss section. Normally -@code{@value{LD}} reserves memory addresses for it during linking, so no partial -program defines the location of the symbol. Use @code{.comm} to tell -@code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}} -allocates space for each @code{.comm} symbol that is at least as -long as the longest @code{.comm} request in any of the partial programs -linked. @var{length} is an absolute expression. +@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, @code{@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 @@ -3295,6 +3328,27 @@ The syntax for @code{equ} on the HPPA is @samp{@var{symbol} .equ @var{expression}}. @end ifset +@node Equiv +@section @code{.equiv @var{symbol}, @var{expression}} +@cindex @code{equiv} directive +The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that +the assembler will signal an error if @var{symbol} is already defined. + +Except for the contents of the error message, this is roughly equivalent to +@smallexample +.ifdef SYM +.err +.endif +.equ SYM,VAL +@end smallexample + +@node Err +@section @code{.err} +@cindex @code{err} directive +If @code{@value{AS}} assembles a @code{.err} directive, it will print an error +message and, unless the @code{-Z} option was used, it will not generate an +object file. This can be used to signal error an conditionally compiled code. + @node Extern @section @code{.extern} @@ -3556,6 +3610,11 @@ section, so that at run-time the bytes start off zeroed. @var{Symbol} is not declared global (@pxref{Global,,@code{.global}}), so is normally not visible to @code{@value{LD}}. +@ifset GENERIC +Some targets permit a third argument to be used with @code{.lcomm}. This +argument specifies the desired alignment of the symbol in the bss section. +@end ifset + @ifset HPPA The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional. @@ -4036,6 +4095,8 @@ section is not loaded writable section @item d data section +@item r +read-only section @item x executable section @end table @@ -4293,6 +4354,39 @@ one string to copy, separated by commas. Unless otherwise specified for a particular machine, the assembler marks the end of each string with a 0 byte. You can use any of the escape sequences described in @ref{Strings,,Strings}. +@ifset ELF +@node Symver +@section @code{.symver} +@cindex @code{symver} directive +@cindex symbol versioning +@cindex versions of symbols +Use the @code{.symver} directive to bind symbols to specific version nodes +within a source file. This is only supported on ELF platforms, and is +typically used when assembling files to be linked into a shared library. +There are cases where it may make sense to use this in objects to be bound +into an application itself so as to override a versioned symbol from a +shared library. + +For ELF targets, the @code{.symver} directive is used like this: +@smallexample +.symver @var{name}, @var{name2@@nodename} +@end smallexample +In this case, the symbol @var{name} must exist and be defined within the file +being assembled. The @code{.versym} 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 +permitted in symbol names. The @var{name2} part of the name is the actual name +of the symbol by which it will be externally referenced. The name @var{name} +itself is merely a name of convenience that is used so that it is possible to +have definitions for multiple versions of a function within a single source +file, and so that the compiler can unambiguously know which version of a +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. +@end ifset + @ifset COFF @node Tag @section @code{.tag @var{structname}} |