gprofng: fix bug 29353 - Fix a lay-out issue in the html disassembly files

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

diff --git a/gas/doc/internals.texi b/gas/doc/internals.texi
index 58b56868cee7e131f44d0d857ce61f9989fd0db5..59b2d3acee59fe31eab6cf8e61a11cbca937c3b0 100644 (file)
--- a/gas/doc/internals.texi
+++ b/gas/doc/internals.texi
@@ -1,7 +1,5 @@
 \input texinfo
 \input texinfo

-@c  Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c  2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
-@c  Free Software Foundation, Inc.
+@c  Copyright (C) 1991-2022 Free Software Foundation, Inc.

 @setfilename internals.info
 @node Top
 @top Assembler Internals
 @setfilename internals.info
 @node Top
 @top Assembler Internals


@@ -43,11 +41,10 @@ This section describes some fundamental GAS data types.
 @cindex symbolS structure
 
 The definition for the symbol structure, @code{symbolS}, is located in
 @cindex symbolS structure
 
 The definition for the symbol structure, @code{symbolS}, is located in

-@file{struc-symbol.h}.
+@file{symbols.c}.

 
 

-In general, the fields of this structure may not be referred to directly.
+The fields of this structure may not be referred to directly.

 Instead, you must use one of the accessor functions defined in @file{symbol.h}.
 Instead, you must use one of the accessor functions defined in @file{symbol.h}.

-These accessor functions should work for any GAS version.

 
 Symbol structures contain the following fields:
 
 
 Symbol structures contain the following fields:
 


@@ -153,10 +150,6 @@ Set the name of the symbol.
 @cindex S_IS_EXTERNAL
 Return non-zero if the symbol is externally visible.
 
 @cindex S_IS_EXTERNAL
 Return non-zero if the symbol is externally visible.
 

-@item S_IS_EXTERN
-@cindex S_IS_EXTERN
-A synonym for @code{S_IS_EXTERNAL}.  Don't use it.
-

 @item S_IS_WEAK
 @cindex S_IS_WEAK
 Return non-zero if the symbol is weak, or if it is a @code{weakref} alias or
 @item S_IS_WEAK
 @cindex S_IS_WEAK
 Return non-zero if the symbol is weak, or if it is a @code{weakref} alias or


@@ -404,12 +397,6 @@ deal with local symbols.  @code{struct local_symbol} is much smaller than
 @code{symbolS} (which also automatically creates a bfd @code{asymbol}
 structure), so this saves space when assembling large files.
 
 @code{symbolS} (which also automatically creates a bfd @code{asymbol}
 structure), so this saves space when assembling large files.
 

-The first field of @code{symbolS} is @code{bsym}, the pointer to the BFD
-symbol.  The first field of @code{struct local_symbol} is a pointer which is
-always set to NULL.  This is how the symbol accessor functions can distinguish
-local symbols from ordinary symbols.  The symbol accessor functions
-automatically convert a local symbol into an ordinary symbol when necessary.
-

 @node Expressions
 @subsection Expressions
 @cindex internals, expressions
 @node Expressions
 @subsection Expressions
 @cindex internals, expressions


@@ -732,7 +719,7 @@ all the fixups (@code{fixup_segment}), resolves all the symbol values (using
 @cindex porting
 
 Each GAS target specifies two main things: the CPU file and the object format
 @cindex porting
 
 Each GAS target specifies two main things: the CPU file and the object format

-file.  Two main switches in the @file{configure.in} file handle this.  The
+file.  Two main switches in the @file{configure.ac} file handle this.  The

 first switches on CPU type to set the shell variable @code{cpu_type}.  The
 second switches on the entire target to set the shell variable @code{fmt}.
 
 first switches on CPU type to set the shell variable @code{cpu_type}.  The
 second switches on the entire target to set the shell variable @code{fmt}.
 


@@ -886,6 +873,8 @@ comment.
 @item tc_comment_chars
 @cindex tc_comment_chars
 If this macro is defined, GAS will use it instead of @code{comment_chars}.
 @item tc_comment_chars
 @cindex tc_comment_chars
 If this macro is defined, GAS will use it instead of @code{comment_chars}.

+This has the advantage that this macro does not have to refer to a constant
+array.

 
 @item tc_symbol_chars
 @cindex tc_symbol_chars
 
 @item tc_symbol_chars
 @cindex tc_symbol_chars


@@ -910,6 +899,13 @@ listed in this array).  Note that line_separator_chars do not separate lines
 if found in a comment, such as after a character in line_comment_chars or
 comment_chars.
 
 if found in a comment, such as after a character in line_comment_chars or
 comment_chars.
 

+@item tc_line_separator_chars
+@cindex tc_line_separator_chars
+If this macro is defined, GAS will use it instead of
+@code{line_separator_chars}.  This has the advantage that this macro does not
+have to refer to a constant array.
+
+

 @item EXP_CHARS
 @cindex EXP_CHARS
 This is a null terminated @code{const char} array of characters which may be
 @item EXP_CHARS
 @cindex EXP_CHARS
 This is a null terminated @code{const char} array of characters which may be


@@ -1038,6 +1034,12 @@ Predefined symbols with fixed values, such as register names or condition
 codes, are typically entered directly into the symbol table when @code{md_begin}
 is called.  One argument is passed, a @code{char *} for the symbol.
 
 codes, are typically entered directly into the symbol table when @code{md_begin}
 is called.  One argument is passed, a @code{char *} for the symbol.
 

+@item md_resolve_symbol
+@cindex md_resolve_symbol
+If this macro is defined, GAS will call it upon resolving machine-dependent
+symbols (that is, for any symbol with operation O_md1..O_md32 inclusively).
+If this functions returns zero, then the symbol could not be resolved.
+

 @item md_operand
 @cindex md_operand
 GAS will call this function with one argument, an @code{expressionS}
 @item md_operand
 @cindex md_operand
 GAS will call this function with one argument, an @code{expressionS}


@@ -1093,11 +1095,6 @@ You may define this macro to parse an expression used in a data allocation
 pseudo-op such as @code{.word}.  You can use this to recognize relocation
 directives that may appear in such directives.
 
 pseudo-op such as @code{.word}.  You can use this to recognize relocation
 directives that may appear in such directives.
 

-@item BITFIELD_CONS_EXPRESSION
-@cindex BITFIELD_CONS_EXPRESSION
-If you define this macro, GAS will recognize bitfield instructions in data
-allocation pseudo-ops, as used on the i960.
-

 @item REPEAT_CONS_EXPRESSION
 @cindex REPEAT_CONS_EXPRESSION
 If you define this macro, GAS will recognize repeat counts in data allocation
 @item REPEAT_CONS_EXPRESSION
 @cindex REPEAT_CONS_EXPRESSION
 If you define this macro, GAS will recognize repeat counts in data allocation


@@ -1115,7 +1112,8 @@ You may define this macro to generate a fixup for a data allocation pseudo-op.
 @item TC_ADDRESS_BYTES
 @cindex TC_ADDRESS_BYTES
 Define this macro to specify the number of bytes used to store an address.
 @item TC_ADDRESS_BYTES
 @cindex TC_ADDRESS_BYTES
 Define this macro to specify the number of bytes used to store an address.

-Used to implement @code{dc.a}.  The target must have a reloc for this size.
+Used to implement @code{dc.a}.  If not defined by the target, a default will
+be supplied.  Targets are assumed to have a reloc for this size.

 
 @item TC_INIT_FIX_DATA (@var{fixp})
 @cindex TC_INIT_FIX_DATA
 
 @item TC_INIT_FIX_DATA (@var{fixp})
 @cindex TC_INIT_FIX_DATA


@@ -1127,10 +1125,11 @@ These fields are defined with the @code{TC_FIX_TYPE} macro.
 A C statement to output target specific debugging information for
 fixup @var{fixp} to @var{stream}.  This macro is called by @code{print_fixup}.
 
 A C statement to output target specific debugging information for
 fixup @var{fixp} to @var{stream}.  This macro is called by @code{print_fixup}.
 

-@item TC_FRAG_INIT (@var{fragp})
+@item TC_FRAG_INIT (@var{fragp}, @var{max_bytes})

 @cindex TC_FRAG_INIT
 @cindex TC_FRAG_INIT

-A C statement to initialize the target specific fields of frag @var{fragp}.
-These fields are defined with the @code{TC_FRAG_TYPE} macro.
+A C statement to initialize the target specific fields of frag @var{fragp}
+with maximum number of bytes @var{max_bytes}.  These fields are defined
+with the @code{TC_FRAG_TYPE} macro.

 
 @item md_number_to_chars
 @cindex md_number_to_chars
 
 @item md_number_to_chars
 @cindex md_number_to_chars


@@ -1218,6 +1217,11 @@ If you do not define @code{md_relax_frag}, you may define
 machine independent code knows how to use such a table to relax PC relative
 references.  See @file{tc-m68k.c} for an example.  @xref{Relaxation}.
 
 machine independent code knows how to use such a table to relax PC relative
 references.  See @file{tc-m68k.c} for an example.  @xref{Relaxation}.
 

+@item md_generic_table_relax_frag
+@cindex md_generic_table_relax_frag
+If defined, it is a C statement that is invoked, instead of
+the default implementation, to scan @code{TC_GENERIC_RELAX_TABLE}.
+

 @item md_prepare_relax_scan
 @cindex md_prepare_relax_scan
 If defined, it is a C statement that is invoked prior to scanning
 @item md_prepare_relax_scan
 @cindex md_prepare_relax_scan
 If defined, it is a C statement that is invoked prior to scanning


@@ -1226,7 +1230,7 @@ the relax table.
 @item LINKER_RELAXING_SHRINKS_ONLY
 @cindex LINKER_RELAXING_SHRINKS_ONLY
 If you define this macro, and the global variable @samp{linkrelax} is set
 @item LINKER_RELAXING_SHRINKS_ONLY
 @cindex LINKER_RELAXING_SHRINKS_ONLY
 If you define this macro, and the global variable @samp{linkrelax} is set

-(because of a command line option, or unconditionally in @code{md_begin}), a
+(because of a command-line option, or unconditionally in @code{md_begin}), a

 @samp{.align} directive will cause extra space to be allocated.  The linker can
 then discard this space when relaxing the section.
 
 @samp{.align} directive will cause extra space to be allocated.  The linker can
 then discard this space when relaxing the section.
 


@@ -1250,7 +1254,7 @@ It may also create any necessary relocations.
 @cindex TC_FINALIZE_SYMS_BEFORE_SIZE_SEG
 Specifies the value to be assigned to @code{finalize_syms} before the function
 @code{size_segs} is called.  Since @code{size_segs} calls @code{cvt_frag_to_fill}
 @cindex TC_FINALIZE_SYMS_BEFORE_SIZE_SEG
 Specifies the value to be assigned to @code{finalize_syms} before the function
 @code{size_segs} is called.  Since @code{size_segs} calls @code{cvt_frag_to_fill}

-which can call @code{md_convert_frag}, this constant governs whether the symbols 
+which can call @code{md_convert_frag}, this constant governs whether the symbols

 accessed in @code{md_convert_frag} will be fully resolved.  In particular it
 governs whether local symbols will have been resolved, and had their frag
 information removed.  Depending upon the processing performed by
 accessed in @code{md_convert_frag} will be fully resolved.  In particular it
 governs whether local symbols will have been resolved, and had their frag
 information removed.  Depending upon the processing performed by


@@ -1306,8 +1310,7 @@ This macro controls resolution of fixup expressions involving the
 difference of two symbols in the same section.  If this macro returns zero,
 the subtrahend will be resolved and @code{fx_subsy} set to @code{NULL} for
 @code{md_apply_fix}.  If undefined, the default of
 difference of two symbols in the same section.  If this macro returns zero,
 the subtrahend will be resolved and @code{fx_subsy} set to @code{NULL} for
 @code{md_apply_fix}.  If undefined, the default of

-@w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will
-be used.
+@w{@code{! SEG_NORMAL (@var{seg})}} will be used.

 
 @item TC_FORCE_RELOCATION_SUB_ABS (@var{fix}, @var{seg})
 @cindex TC_FORCE_RELOCATION_SUB_ABS
 
 @item TC_FORCE_RELOCATION_SUB_ABS (@var{fix}, @var{seg})
 @cindex TC_FORCE_RELOCATION_SUB_ABS


@@ -1467,6 +1470,12 @@ completed, but before the relocations have been generated.
 If you define this macro, GAS will call it after the relocs have been
 generated.
 
 If you define this macro, GAS will call it after the relocs have been
 generated.
 

+@item tc_cfi_reloc_for_encoding
+@cindex tc_cfi_reloc_for_encoding
+This macro is used to indicate whether a cfi encoding requires a relocation.
+It should return the required relocation type.  Defining this macro implies
+that Compact EH is supported.
+

 @item md_post_relax_hook
 If you define this macro, GAS will call it after relaxing and sizing the
 segments.
 @item md_post_relax_hook
 If you define this macro, GAS will call it after relaxing and sizing the
 segments.


@@ -1545,6 +1554,16 @@ 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_emit_single_noop_insn
+@itemx md_single_noop_insn
+These macro facilitate the @var{.nop} directive.  If defined the
+@var{md_emit_single_noop_insn) macro provides code to insert a single no-op
+instruction into the output stream.  If this involves calling @var{md_assemble}
+with a fixed string then the alternative macro @var{md_single_noop_insn} can be
+defined, specifying the string to pass.  If neither of these macros are defined
+then the @var{.nop} directive will call @var{md_assemble} with the string
+@option{nop}.
+

 @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
 @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


@@ -1585,7 +1604,7 @@ if it is necessary to add object file format specific code to the CPU file.
 
 @item obj_begin
 If you define this macro, GAS will call it at the start of the assembly, after
 
 @item obj_begin
 If you define this macro, GAS will call it at the start of the assembly, after

-the command line arguments have been parsed and all the machine independent
+the command-line arguments have been parsed and all the machine independent

 initializations have been completed.
 
 @item obj_app_file
 initializations have been completed.
 
 @item obj_app_file


@@ -1745,12 +1764,6 @@ no-op instructions, it must be able to expand or shrink the section contents
 while still preserving intra-section references and meeting alignment
 requirements.
 
 while still preserving intra-section references and meeting alignment
 requirements.
 

-For the i960 using b.out format, no expansion is done; instead, each
-@samp{.align} directive causes extra space to be allocated, enough that when
-the linker is relaxing a section and removing unneeded space, it can discard
-some or all of this extra padding and cause the following data to be correctly
-aligned.
-

 For the H8/300, I think the linker expands calls that can't reach, and doesn't
 worry about alignment issues; the cpu probably never needs any significant
 alignment beyond the instruction size.
 For the H8/300, I think the linker expands calls that can't reach, and doesn't
 worry about alignment issues; the cpu probably never needs any significant
 alignment beyond the instruction size.


@@ -1912,45 +1925,6 @@ after all input has been read, but messages about fixups should refer to the
 original filename and line number that they are applicable to.
 @end deftypefun
 
 original filename and line number that they are applicable to.
 @end deftypefun
 

-@deftypefun @{@} void sprint_value (char *@var{buf}, valueT @var{val})
-This function is helpful for converting a @code{valueT} value into printable
-format, in case it's wider than modes that @code{*printf} can handle.  If the
-type is narrow enough, a decimal number will be produced; otherwise, it will be
-in hexadecimal.  The value itself is not examined to make this determination.
-@end deftypefun
-
-@node Hash tables
-@subsection Hash tables
-@cindex hash tables
-
-@deftypefun @{@} @{struct hash_control *@} hash_new (void)
-Creates the hash table control structure.
-@end deftypefun
-
-@deftypefun @{@} void hash_die (struct hash_control *)
-Destroy a hash table.
-@end deftypefun
-
-@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
-
-@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
-
-@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
-
-@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
-

 @node Test suite
 @section Test suite
 @cindex test suite
 @node Test suite
 @section Test suite
 @cindex test suite