Imported binutils-2.20

[msp430-binutils.git] / gas / doc / internals.texi

diff --git a/gas/doc/internals.texi b/gas/doc/internals.texi
index c63a2dbd7705ccbef6581a729c293eb1e2e1e673..21334864b7e95afdddd4e0368f1258e15a6a7583 100644 (file)
--- a/gas/doc/internals.texi
+++ b/gas/doc/internals.texi
@@ -1,6 +1,6 @@
 \input texinfo
 @c  Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
 \input texinfo
 @c  Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,

-@c  2001, 2002, 2003, 2004, 2005, 2006
+@c  2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009

 @c  Free Software Foundation, Inc.
 @setfilename internals.info
 @node Top
 @c  Free Software Foundation, Inc.
 @setfilename internals.info
 @node Top


@@ -1045,6 +1045,16 @@ pointer, for any expression that can not be recognized.  When the function
 is called, @code{input_line_pointer} will point to the start of the
 expression.
 
 is called, @code{input_line_pointer} will point to the start of the
 expression.
 

+@item md_register_arithmetic
+@cindex md_register_arithmetic
+If this macro is defined and evaluates to zero then GAS will not fold
+expressions that add or subtract a constant to/from a register to give
+another register.  For example GAS's default behaviour is to fold the
+expression "r8 + 1" into "r9", which is probably not the result
+intended by the programmer.  The default is to allow such folding,
+since this maintains backwards compatibility with earlier releases of
+GAS.
+

 @item tc_unrecognized_line
 @cindex tc_unrecognized_line
 If you define this macro, GAS will call it when it finds a line that it can not
 @item tc_unrecognized_line
 @cindex tc_unrecognized_line
 If you define this macro, GAS will call it when it finds a line that it can not


@@ -1134,17 +1144,25 @@ simple macro.
 @cindex md_atof
 This function is called to convert an ASCII string into a floating point value
 in format used by the CPU.  It takes three arguments.  The first is @var{type}
 @cindex md_atof
 This function is called to convert an ASCII string into a floating point value
 in format used by the CPU.  It takes three arguments.  The first is @var{type}

-which is a byte describing the type of floating point number to be created.
-Possible values are @var{'f'} or @var{'s'} for single precision, @var{'d'} or
-@var{'r'} for double precision and @var{'x'} or @var{'p'} for extended
-precision.  Either lower or upper case versions of these letters can be used.
+which is a byte describing the type of floating point number to be created.  It
+is one of the characters defined in the @code{FLT_CHARS} macro.  Possible
+values are @var{'f'} or @var{'s'} for single precision, @var{'d'} or @var{'r'}
+for double precision and @var{'x'} or @var{'p'} for extended precision.  Either
+lower or upper case versions of these letters can be used.  Note: some targets
+do not support all of these types, and some targets may also support other
+types not mentioned here.

 
 The second parameter is @var{litP} which is a pointer to a byte array where the
 
 The second parameter is @var{litP} which is a pointer to a byte array where the

-converted value should be stored.  The third argument is @var{sizeP}, which is
-a pointer to a integer that should be filled in with the number of
-@var{LITTLENUM}s emitted into the byte array.  (@var{LITTLENUM} is defined in
-gas/bignum.h).  The function should return NULL upon success or an error string
-upon failure.
+converted value should be stored.  The value is converted into LITTLENUMs and
+is stored in the target's endian-ness order.  (@var{LITTLENUM} is defined in
+gas/bignum.h).  Single precision values occupy 2 littlenums.  Double precision
+values occupy 4 littlenums and extended precision values occupy either 5 or 6
+littlenums, depending upon the target.
+
+The third argument is @var{sizeP}, which is a pointer to a integer that should
+be filled in with the number of chars emitted into the byte array.
+
+The function should return NULL upon success or an error string upon failure.

 
 @item TC_LARGEST_EXPONENT_IS_NORMAL
 @cindex TC_LARGEST_EXPONENT_IS_NORMAL (@var{precision})
 
 @item TC_LARGEST_EXPONENT_IS_NORMAL
 @cindex TC_LARGEST_EXPONENT_IS_NORMAL (@var{precision})


@@ -1291,22 +1309,27 @@ the subtrahend will be resolved and @code{fx_subsy} set to @code{NULL} for
 @w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will
 be used.
 
 @w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will
 be used.
 

-@item TC_FORCE_RELOCATION_SUB_ABS (@var{fix})
+@item TC_FORCE_RELOCATION_SUB_ABS (@var{fix}, @var{seg})

 @cindex TC_FORCE_RELOCATION_SUB_ABS
 Like @code{TC_FORCE_RELOCATION_SUB_SAME}, but used when the subtrahend is an
 absolute symbol.  If the macro is undefined a default of @code{0} is used.
 
 @cindex TC_FORCE_RELOCATION_SUB_ABS
 Like @code{TC_FORCE_RELOCATION_SUB_SAME}, but used when the subtrahend is an
 absolute symbol.  If the macro is undefined a default of @code{0} is used.
 

-@item TC_FORCE_RELOCATION_SUB_LOCAL (@var{fix})
+@item TC_FORCE_RELOCATION_SUB_LOCAL (@var{fix}, @var{seg})

 @cindex TC_FORCE_RELOCATION_SUB_LOCAL
 Like @code{TC_FORCE_RELOCATION_SUB_ABS}, but the subtrahend is a symbol in the
 same section as the fixup.
 
 @cindex TC_FORCE_RELOCATION_SUB_LOCAL
 Like @code{TC_FORCE_RELOCATION_SUB_ABS}, but the subtrahend is a symbol in the
 same section as the fixup.
 

-@item TC_VALIDATE_FIX_SUB (@var{fix})
+@item TC_VALIDATE_FIX_SUB (@var{fix}, @var{seg})

 @cindex TC_VALIDATE_FIX_SUB
 This macro is evaluated for any fixup with a @code{fx_subsy} that
 @code{fixup_segment} cannot reduce to a number.  If the macro returns
 @code{false} an error will be reported.
 
 @cindex TC_VALIDATE_FIX_SUB
 This macro is evaluated for any fixup with a @code{fx_subsy} that
 @code{fixup_segment} cannot reduce to a number.  If the macro returns
 @code{false} an error will be reported.
 

+@item TC_GLOBAL_REGISTER_SYMBOL_OK
+@cindex TC_GLOBAL_REGISTER_SYMBOL_OK
+Define this macro if global register symbols are supported. The default
+is to disallow global register symbols.
+

 @item MD_APPLY_SYM_VALUE (@var{fix})
 @cindex MD_APPLY_SYM_VALUE
 This macro controls whether the symbol value becomes part of the value passed
 @item MD_APPLY_SYM_VALUE (@var{fix})
 @cindex MD_APPLY_SYM_VALUE
 This macro controls whether the symbol value becomes part of the value passed


@@ -1476,7 +1499,7 @@ The COFF @code{.section} directive will use the value of this macro to set
 a new section's attributes when a directive has no valid flags or when the
 flag is @code{w}. The default value of the macro is @code{SEC_LOAD | SEC_DATA}.
 
 a new section's attributes when a directive has no valid flags or when the
 flag is @code{w}. The default value of the macro is @code{SEC_LOAD | SEC_DATA}.
 

-@item DWARF2_FORMAT ()
+@item DWARF2_FORMAT (@var{sec})

 @cindex DWARF2_FORMAT
 If you define this, it should return one of @code{dwarf2_format_32bit},
 @code{dwarf2_format_64bit}, or @code{dwarf2_format_64bit_irix} to indicate
 @cindex DWARF2_FORMAT
 If you define this, it should return one of @code{dwarf2_format_32bit},
 @code{dwarf2_format_64bit}, or @code{dwarf2_format_64bit_irix} to indicate


@@ -1493,7 +1516,7 @@ the section's length.
 If you don't define this, @code{dwarf2_format_32bit} will be used as
 the default.
 
 If you don't define this, @code{dwarf2_format_32bit} will be used as
 the default.
 

-This define only affects @code{.debug_info} and @code{.debug_line}
+This define only affects debug

 sections generated by the assembler.  DWARF 2 sections generated by
 other tools will be unaffected by this setting.
 
 sections generated by the assembler.  DWARF 2 sections generated by
 other tools will be unaffected by this setting.
 


@@ -1517,6 +1540,23 @@ The function should return the debug format that is preferred by the CPU
 backend.  This format will be used when generating assembler specific debug
 information.
 
 backend.  This format will be used when generating assembler specific debug
 information.
 

+@item md_allow_local_subtract (@var{left}, @var{right}, @var{section})
+If defined, GAS will call this macro when evaluating an expression which is the
+difference of two symbols defined in the same section.  It takes three
+arguments: @code{expressioS * @var{left}} which is the symbolic expression on
+the left hand side of the subtraction operation, @code{expressionS *
+@var{right}} which is the symbolic expression on the right hand side of the
+subtraction, and @code{segT @var{section}} which is the section containing the two
+symbols.  The macro should return a non-zero value if the expression should be
+evaluated.  Targets which implement link time relaxation which may change the
+position of the two symbols relative to each other should ensure that this
+macro returns zero in situations where this can occur.
+
+@item md_allow_eh_opt
+If defined, GAS will check this macro before performing any optimizations on
+the DWARF call frame debug information that is emitted.  Targets which
+implement link time relaxation may need to define this macro and set it to zero
+if it is possible to change the size of a function's prologue.

 @end table
 
 @node Object format backend
 @end table
 
 @node Object format backend


@@ -1886,21 +1926,23 @@ Creates the hash table control structure.
 Destroy a hash table.
 @end deftypefun
 
 Destroy a hash table.
 @end deftypefun
 

-@deftypefun @{@} PTR hash_delete (struct hash_control *, const char *)
-Deletes entry from the hash table, returns the value it had.
+@deftypefun @{@} void *hash_delete (struct hash_control *, const char *, int)
+Deletes entry from the hash table, returns the value it had.  If the last
+arg is non-zero, free memory allocated for this entry and all entries
+allocated more recently than this entry.

 @end deftypefun
 
 @end deftypefun
 

-@deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR)
+@deftypefun @{@} void *hash_replace (struct hash_control *, const char *, void *)

 Updates the value for an entry already in the table, returning the old value.
 If no entry was found, just returns NULL.
 @end deftypefun
 
 Updates the value for an entry already in the table, returning the old value.
 If no entry was found, just returns NULL.
 @end deftypefun
 

-@deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR)
+@deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, void *)

 Inserting a value already in the table is an error.
 Returns an error message or NULL.
 @end deftypefun
 
 Inserting a value already in the table is an error.
 Returns an error message or NULL.
 @end deftypefun
 

-@deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR)
+@deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, void *)

 Inserts if the value isn't already present, updates it if it is.
 @end deftypefun
 
 Inserts if the value isn't already present, updates it if it is.
 @end deftypefun