\input texinfo
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001
+@c 2001, 2002, 2003
@c Free Software Foundation, Inc.
@setfilename internals.info
@node Top
The assembler always has a current frag, named @code{frag_now}. More space is
allocated for the current frag using the @code{frag_more} function; this
-returns a pointer to the amount of requested space. Relaxing is done using
-variant frags allocated by @code{frag_var} or @code{frag_variant}
-(@pxref{Relaxation}).
+returns a pointer to the amount of requested space. The function
+@code{frag_room} says by how much the current frag can be extended.
+Relaxing is done using variant frags allocated by @code{frag_var}
+or @code{frag_variant} (@pxref{Relaxation}).
@node GAS processing
@section What GAS does when it runs
@itemx md_longopts_size
@itemx md_parse_option
@itemx md_show_usage
+@itemx md_after_parse_args
@cindex md_shortopts
@cindex md_longopts
@cindex md_longopts_size
@cindex md_parse_option
@cindex md_show_usage
+@cindex md_after_parse_args
GAS uses these variables and functions during option processing.
@code{md_shortopts} is a @code{const char *} which GAS adds to the machine
independent string passed to @code{getopt}. @code{md_longopts} is a
unrecognized code, presumably indicating a special code value which appears in
@code{md_longopts}. GAS will call @code{md_show_usage} when a usage message is
printed; it should print a description of the machine specific options.
+@code{md_after_pase_args}, if defined, is called after all options are
+processed, to let the backend override settings done by the generic option
+parsing.
@item md_begin
@cindex md_begin
If you define this macro, it should return nonzero if the current input line
pointer should be treated as the end of a line.
+@item TC_CASE_SENSITIVE
+@cindex TC_CASE_SENSITIVE
+Define this macro if instruction mnemonics and pseudos are case sensitive.
+The default is to have it undefined giving case insensitive names.
+
@item md_parse_name
@cindex md_parse_name
If this macro is defined, GAS will call it for any symbol found in an
gas/bignum.h). 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})
+This macro is used only by @file{atof-ieee.c}. It should evaluate to true
+if floats of the given precision use the largest exponent for normal numbers
+instead of NaNs and infinities. @var{precision} is @samp{F_PRECISION} for
+single precision, @samp{D_PRECISION} for double precision, or
+@samp{X_PRECISION} for extended double precision.
+
+The macro has a default definition which returns 0 for all cases.
+
@item md_reloc_size
@cindex md_reloc_size
This variable is only used in the original version of gas (not
@code{md_convert_frag} the frag information may or may not be necessary, as may
the resolved values of the symbols. The default value is 1.
-@item md_apply_fix3
-@cindex md_apply_fix3
-GAS will call this for each fixup. It should store the correct value in the
-object file. @code{fixup_segment} performs a generic overflow check on the
-@code{valueT *val} argument after @code{md_apply_fix3} returns. If the overflow
-check is relevant for the target machine, then @code{md_apply_fix3} should
-modify @code{valueT *val}, typically to the value stored in the object file.
+@item TC_VALIDATE_FIX (@var{fixP}, @var{seg}, @var{skip})
+@cindex TC_VALIDATE_FIX
+This macro is evaluated for each fixup (when @var{linkrelax} is not set).
+It may be used to change the fixup in @code{struct fix *@var{fixP}} before
+the generic code sees it, or to fully process the fixup. In the latter case,
+a @code{goto @var{skip}} will bypass the generic code.
-@item TC_HANDLES_FX_DONE
-@cindex TC_HANDLES_FX_DONE
-If this macro is defined, it means that @code{md_apply_fix3} correctly sets the
-@code{fx_done} field in the fixup.
+@item md_apply_fix3 (@var{fixP}, @var{valP}, @var{seg})
+@cindex md_apply_fix3
+GAS will call this for each fixup that passes the @code{TC_VALIDATE_FIX} test
+when @var{linkrelax} is not set. It should store the correct value in the
+object file. @code{struct fix *@var{fixP}} is the fixup @code{md_apply_fix3}
+is operating on. @code{valueT *@var{valP}} is the value to store into the
+object files, or at least is the generic code's best guess. Specifically,
+*@var{valP} is the value of the fixup symbol, perhaps modified by
+@code{MD_APPLY_SYM_VALUE}, plus @code{@var{fixP}->fx_offset} (symbol addend),
+less @code{MD_PCREL_FROM_SECTION} for pc-relative fixups.
+@code{segT @var{seg}} is the section the fix is in.
+@code{fixup_segment} performs a generic overflow check on *@var{valP} after
+@code{md_apply_fix3} returns. If the overflow check is relevant for the target
+machine, then @code{md_apply_fix3} should modify *@var{valP}, typically to the
+value stored in the object file.
+
+@item TC_FORCE_RELOCATION (@var{fix})
+@cindex TC_FORCE_RELOCATION
+If this macro returns non-zero, it guarantees that a relocation will be emitted
+even when the value can be resolved locally, as @code{fixup_segment} tries to
+reduce the number of relocations emitted. For example, a fixup expression
+against an absolute symbol will normally not require a reloc. If undefined,
+a default of @w{@code{(S_FORCE_RELOC ((@var{fix})->fx_addsy))}} is used.
+
+@item TC_FORCE_RELOCATION_ABS (@var{fix})
+@cindex TC_FORCE_RELOCATION_ABS
+Like @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against an
+absolute symbol. If undefined, @code{TC_FORCE_RELOCATION} will be used.
+
+@item TC_FORCE_RELOCATION_LOCAL (@var{fix})
+@cindex TC_FORCE_RELOCATION_LOCAL
+Like @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against a
+symbol in the current section. If undefined, fixups that are not
+@code{fx_pcrel} or @code{fx_plt} or for which @code{TC_FORCE_RELOCATION}
+returns non-zero, will emit relocs.
+
+@item TC_FORCE_RELOCATION_SUB_SAME (@var{fix}, @var{seg})
+@cindex TC_FORCE_RELOCATION_SUB_SAME
+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_fix3}. If undefined, the default of
+@w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will
+be used.
+
+@item TC_FORCE_RELOCATION_SUB_ABS (@var{fix})
+@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})
+@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})
+@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 MD_APPLY_SYM_VALUE (@var{fix})
+@cindex MD_APPLY_SYM_VALUE
+This macro controls whether the symbol value becomes part of the value passed
+to @code{md_apply_fix3}. If the macro is undefined, or returns non-zero, the
+symbol value will be included. For ELF, a suitable definition might simply be
+@code{0}, because ELF relocations don't include the symbol value in the addend.
+
+@item S_FORCE_RELOC (@var{sym}, @var{strict})
+@cindex S_FORCE_RELOC
+This macro (or function, for @code{BFD_ASSEMBLER} gas) returns true for symbols
+that should not be reduced to section symbols or eliminated from expressions,
+because they may be overridden by the linker. ie. for symbols that are
+undefined or common, and when @var{strict} is set, weak, or global (for ELF
+assemblers that support ELF shared library linking semantics).
+
+@item EXTERN_FORCE_RELOC
+@cindex EXTERN_FORCE_RELOC
+This macro controls whether @code{S_FORCE_RELOC} returns true for global
+symbols. If undefined, the default is @code{true} for ELF assemblers, and
+@code{false} for non-ELF.
@item tc_gen_reloc
@cindex tc_gen_reloc
preprocessor so that whitespace around colons is preserved. This is useful
when colons might be removed from the input after preprocessing but before
assembling, so that adjoining tokens can still be distinguished if there is
-whitespace, or concatentated if there is not.
+whitespace, or concatenated if there is not.
@item tc_frob_section
@cindex tc_frob_section
@item tc_frob_symbol
@cindex tc_frob_symbol
If you define this macro, GAS will call it for each symbol. You can indicate
-that the symbol should not be included in the object file by definining this
+that the symbol should not be included in the object file by defining this
macro to set its second argument to a non-zero value.
@item tc_frob_file
If you define this macro, GAS will call it after the relocs have been
generated.
+@item md_post_relax_hook
+If you define this macro, GAS will call it after relaxing and sizing the
+segments.
+
@item LISTING_HEADER
A string to use on the header line of a listing. The default value is simply
@code{"GAS LISTING"}.
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 ()
+@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
+the size of internal DWARF section offsets and the format of the DWARF initial
+length fields. When @code{dwarf2_format_32bit} is returned, the initial
+length field will be 4 bytes long and section offsets are 32 bits in size.
+For @code{dwarf2_format_64bit} and @code{dwarf2_format_64bit_irix}, section
+offsets are 64 bits in size, but the initial length field differs. An 8 byte
+initial length is indicated by @code{dwarf2_format_64bit_irix} and
+@code{dwarf2_format_64bit} indicates a 12 byte initial length field in
+which the first four bytes are 0xffffffff and the next 8 bytes are
+the section's length.
+
+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}
+sections generated by the assembler. DWARF 2 sections generated by
+other tools will be unaffected by this setting.
+
+@item DWARF2_ADDR_SIZE (@var{bfd})
+@cindex DWARF2_ADDR_SIZE
+It should return the size of an address, as it should be represented in
+debugging info. If you don't define this macro, the default definition uses
+the number of bits per address, as defined in @var{bfd}, divided by 8.
+
@end table
@node Object format backend
one symbol to another. GAS will call it when one symbol is equated to
another.
-@item obj_fix_adjustable
-@cindex obj_fix_adjustable
-You may define this macro to indicate whether a fixup against a locally defined
-symbol should be adjusted to be against the section symbol. It should return a
-non-zero value if the adjustment is acceptable.
-
@item obj_sec_sym_ok_for_reloc
@cindex obj_sec_sym_ok_for_reloc
You may define this macro to indicate that it is OK to use a section symbol in
-a relocateion entry. If it is not, GAS will define a new symbol at the start
+a relocation entry. If it is not, GAS will define a new symbol at the start
of a section.
@item EMIT_SECTION_SYMBOLS
@item obj_frob_symbol
@cindex obj_frob_symbol
If you define this macro, GAS will call it for each symbol. You can indicate
-that the symbol should not be included in the object file by definining this
+that the symbol should not be included in the object file by defining this
macro to set its second argument to a non-zero value.
@item obj_frob_file
The @code{fr_subtype} field of a frag is an index into a CPU-specific
relaxation table. That table entry indicates the range of values that can be
stored, the number of bytes that will have to be added to the frag to
-accomodate the addressing mode, and the index of the next entry to examine if
+accommodate the addressing mode, and the index of the next entry to examine if
the value to be stored is outside the range accessible by the current
addressing mode. The @code{fr_symbol} field of the frag indicates what symbol
is to be accessed; the @code{fr_offset} field is added in.
@var{sec} argument), the narrowest likely relaxation mode is stored in
@code{fr_subtype}, and that's that.
-If the symbol is undefined, or in a different section (and therefore moveable
+If the symbol is undefined, or in a different section (and therefore movable
to an arbitrarily large distance), the largest available relaxation mode is
specified, @code{fix_new} is called to produce the relocation record,
@code{fr_fix} is increased to include the relocated field (remember, this
If you generate frags separately for the basic insn opcode and any relaxable
operands, do not call @code{fix_new} thinking you can emit fixups for the
-opcode field from the relaxable frag. It is not garanteed to be the same frag.
+opcode field from the relaxable frag. It is not guaranteed to be the same frag.
If you need to emit fixups for the opcode field from inspection of the
relaxable frag, then you need to generate a common frag for both the basic
opcode and relaxable fields, or you need to provide the frag for the opcode to
projects / deliverable / binutils-gdb.git / blobdiff