\input texinfo
-@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1991-2019 Free Software Foundation, Inc.
@setfilename internals.info
@node Top
@top Assembler Internals
This chapter is not updated regularly, and it may be out of date.
@menu
-* GAS versions:: GAS versions
* Data types:: Data types
* GAS processing:: What GAS does when it runs
* Porting GAS:: Porting GAS
* Test suite:: Test suite
@end menu
-@node GAS versions
-@section GAS versions
-
-GAS has acquired layers of code over time. The original GAS only supported the
-a.out object file format, with three sections. Support for multiple sections
-has been added in two different ways.
-
-The preferred approach is to use the version of GAS created when the symbol
-@code{BFD_ASSEMBLER} is defined. The other versions of GAS are documented for
-historical purposes, and to help anybody who has to debug code written for
-them.
-
-The type @code{segT} is used to represent a section in code which must work
-with all versions of GAS.
-
-@menu
-* Original GAS:: Original GAS version
-* MANY_SEGMENTS:: MANY_SEGMENTS gas version
-* BFD_ASSEMBLER:: BFD_ASSEMBLER gas version
-@end menu
-
-@node Original GAS
-@subsection Original GAS
-
-The original GAS only supported the a.out object file format with three
-sections: @samp{.text}, @samp{.data}, and @samp{.bss}. This is the version of
-GAS that is compiled if neither @code{BFD_ASSEMBLER} nor @code{MANY_SEGMENTS}
-is defined. This version of GAS is still used for the m68k-aout target, and
-perhaps others.
-
-This version of GAS should not be used for any new development.
-
-There is still code that is specific to this version of GAS, notably in
-@file{write.c}. There is no way for this code to loop through all the
-sections; it simply looks at global variables like @code{text_frag_root} and
-@code{data_frag_root}.
-
-The type @code{segT} is an enum.
-
-@node MANY_SEGMENTS
-@subsection MANY_SEGMENTS gas version
-@cindex MANY_SEGMENTS
-
-The @code{MANY_SEGMENTS} version of gas is only used for COFF. It uses the BFD
-library, but it writes out all the data itself using @code{bfd_write}. This
-version of gas supports up to 40 normal sections. The section names are stored
-in the @code{seg_name} array. Other information is stored in the
-@code{segment_info} array.
-
-The type @code{segT} is an enum. Code that wants to examine all the sections
-can use a @code{segT} variable as loop index from @code{SEG_E0} up to but not
-including @code{SEG_UNKNOWN}.
-
-Most of the code specific to this version of GAS is in the file
-@file{config/obj-coff.c}, in the portion of that file that is compiled when
-@code{BFD_ASSEMBLER} is not defined.
-
-This version of GAS is still used for several COFF targets.
-
-@node BFD_ASSEMBLER
-@subsection BFD_ASSEMBLER gas version
-@cindex BFD_ASSEMBLER
-
-The preferred version of GAS is the @code{BFD_ASSEMBLER} version. In this
-version of GAS, the output file is a normal BFD, and the BFD routines are used
-to generate the output.
-
-@code{BFD_ASSEMBLER} will automatically be used for certain targets, including
-those that use the ELF, ECOFF, and SOM object file formats, and also all Alpha,
-MIPS, PowerPC, and SPARC targets. You can force the use of
-@code{BFD_ASSEMBLER} for other targets with the configure option
-@samp{--enable-bfd-assembler}; however, it has not been tested for many
-targets, and can not be assumed to work.
-
@node Data types
@section Data types
@cindex internals, data types
@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}.
-These accessor functions should work for any GAS version.
Symbol structures contain the following fields:
@item sy_next
@itemx sy_previous
-These pointers to other @code{symbolS} structures describe a singly or doubly
-linked list. (If @code{SYMBOLS_NEED_BACKPOINTERS} is not defined, the
-@code{sy_previous} field will be omitted; @code{SYMBOLS_NEED_BACKPOINTERS} is
-always defined if @code{BFD_ASSEMBLER}.) These fields should be accessed with
+These pointers to other @code{symbolS} structures describe a doubly
+linked list. These fields should be accessed with
the @code{symbol_next} and @code{symbol_previous} macros.
@item sy_frag
Whether the symbol is an MRI common symbol created by the @code{COMMON}
pseudo-op when assembling in MRI mode.
-@item bsym
-If @code{BFD_ASSEMBLER} is defined, this points to the BFD @code{asymbol} that
-will be used in writing the object file.
+@item sy_volatile
+Whether the symbol can be re-defined.
+
+@item sy_forward_ref
+Whether the symbol's value must only be evaluated upon use.
-@item sy_name_offset
-(Only used if @code{BFD_ASSEMBLER} is not defined.) This is the position of
-the symbol's name in the string table of the object file. On some formats,
-this will start at position 4, with position 0 reserved for unnamed symbols.
-This field is not used until @code{write_object_file} is called.
+@item sy_weakrefr
+Whether the symbol is a @code{weakref} alias to another symbol.
-@item sy_symbol
-(Only used if @code{BFD_ASSEMBLER} is not defined.) This is the
-format-specific symbol structure, as it would be written into the object file.
+@item sy_weakrefd
+Whether the symbol is or was referenced by one or more @code{weakref} aliases,
+and has not had any direct references.
-@item sy_number
-(Only used if @code{BFD_ASSEMBLER} is not defined.) This is a 24-bit symbol
-number, for use in constructing relocation table entries.
+@item bsym
+This points to the BFD @code{asymbol} that
+will be used in writing the object file.
@item sy_obj
This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by
@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.
+Return non-zero if the symbol is weak, or if it is a @code{weakref} alias or
+symbol that has not been strongly referenced.
+
+@item S_IS_WEAKREFR
+@cindex S_IS_WEAKREFR
+Return non-zero if the symbol is a @code{weakref} alias.
+
+@item S_IS_WEAKREFD
+@cindex S_IS_WEAKREFD
+Return non-zero if the symbol was aliased by a @code{weakref} alias and has not
+had any strong references.
+
+@item S_IS_VOLATILE
+@cindex S_IS_VOLATILE
+Return non-zero if the symbol may be re-defined. Such symbols get created by
+the @code{=} operator, @code{equ}, or @code{set}.
+
+@item S_IS_FORWARD_REF
+@cindex S_IS_FORWARD_REF
+Return non-zero if the symbol is a forward reference, that is its value must
+only be determined upon use.
@item S_IS_COMMON
@cindex S_IS_COMMON
@cindex S_SET_WEAK
Mark the symbol as weak.
+@item S_SET_WEAKREFR
+@cindex S_SET_WEAKREFR
+Mark the symbol as the referrer in a @code{weakref} directive. The symbol it
+aliases must have been set to the value expression before this point. If the
+alias has already been used, the symbol is marked as used too.
+
+@item S_CLEAR_WEAKREFR
+@cindex S_CLEAR_WEAKREFR
+Clear the @code{weakref} alias status of a symbol. This is implicitly called
+whenever a symbol is defined or set to a new expression.
+
+@item S_SET_WEAKREFD
+@cindex S_SET_WEAKREFD
+Mark the symbol as the referred symbol in a @code{weakref} directive.
+Implicitly marks the symbol as weak, but see below. It should only be called
+if the referenced symbol has just been added to the symbol table.
+
+@item S_SET_WEAKREFD
+@cindex S_SET_WEAKREFD
+Clear the @code{weakref} aliased status of a symbol. This is implicitly called
+whenever the symbol is looked up, as part of a direct reference or a
+definition, but not as part of a @code{weakref} directive.
+
+@item S_SET_VOLATILE
+@cindex S_SET_VOLATILE
+Indicate that the symbol may be re-defined.
+
+@item S_CLEAR_VOLATILE
+@cindex S_CLEAR_VOLATILE
+Indicate that the symbol may no longer be re-defined.
+
+@item S_SET_FORWARD_REF
+@cindex S_SET_FORWARD_REF
+Indicate that the symbol is a forward reference, that is its value must only
+be determined upon use.
+
@item S_GET_TYPE
-@item S_GET_DESC
-@item S_GET_OTHER
+@itemx S_GET_DESC
+@itemx S_GET_OTHER
@cindex S_GET_TYPE
@cindex S_GET_DESC
@cindex S_GET_OTHER
a.out).
@item S_SET_TYPE
-@item S_SET_DESC
-@item S_SET_OTHER
+@itemx S_SET_DESC
+@itemx S_SET_OTHER
@cindex S_SET_TYPE
@cindex S_SET_DESC
@cindex S_SET_OTHER
@end table
-When @code{BFD_ASSEMBLER} is defined, GAS attempts to store local
+GAS attempts to store local
symbols--symbols which will not be written to the output file--using a
different structure, @code{struct local_symbol}. This structure can only
represent symbols whose value is an offset within a frag.
@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
@cindex fix_new_exp
A fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both
take a frag (@pxref{Frags}), a position within the frag, a size, an indication
-of whether the fixup is PC relative, and a type. In a @code{BFD_ASSEMBLER}
-GAS, the type is nominally a @code{bfd_reloc_code_real_type}, but several
+of whether the fixup is PC relative, and a type.
+The type is nominally a @code{bfd_reloc_code_real_type}, but several
targets use other type codes to represent fixups that can not be described as
relocations.
@item fx_addnumber
Some CPU backends use this field to convey information between
-@code{md_apply_fix3} and @code{tc_gen_reloc}. The machine independent code does
+@code{md_apply_fix} and @code{tc_gen_reloc}. The machine independent code does
not use it.
@item fx_next
The next fixup in the section.
@item fx_r_type
-The type of the fixup. This field is only defined if @code{BFD_ASSEMBLER}, or
-if the target defines @code{NEED_FX_R_TYPE}.
+The type of the fixup.
@item fx_size
The size of the fixup. This is mostly used for error checking.
@item frch_subseg
Subsection (subsegment) number of this frag chain.
@item fix_root, fix_tail
-(Defined only if @code{BFD_ASSEMBLER} is defined). Point to first and last
-@code{fixS} structures associated with this subsection.
+Point to first and last @code{fixS} structures associated with this subsection.
@item frch_obstack
Not currently used. Intended to be used for frag allocation for this
subsection. This should reduce frag generation caused by switching sections.
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
When the input file is finished, the @code{write_object_file} routine is
called. It assigns addresses to all the frags (@code{relax_segment}), resolves
all the fixups (@code{fixup_segment}), resolves all the symbol values (using
-@code{resolve_symbol_value}), and finally writes out the file (in the
-@code{BFD_ASSEMBLER} case, this is done by simply calling @code{bfd_close}).
+@code{resolve_symbol_value}), and finally writes out the file.
@end itemize
@node Porting GAS
@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}.
passed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in
@file{as.h}, as the start of a set of long option indices, if necessary.
@code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}.
+
GAS will call @code{md_parse_option} whenever @code{getopt} returns an
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.
+@code{md_longopts}. This function should return non-zero if it handled the
+option and zero otherwise. There is no need to print a message about an option
+not being recognized. This will be handled by the generic code.
+
+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
@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
If this macro is defined, it is a pointer to a null terminated list of
characters which may appear in an operand. GAS already assumes that all
-alphanumberic characters, and @samp{$}, @samp{.}, and @samp{_} may appear in an
+alphanumeric characters, and @samp{$}, @samp{.}, and @samp{_} may appear in an
operand (see @samp{symbol_chars} in @file{app.c}). This macro may be defined
to treat additional characters as appearing in an operand. This affects the
way in which GAS removes whitespace before passing the string to
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
Same as TC_START_LABEL, but should be used instead of TC_START_LABEL when
LABELS_WITHOUT_COLONS is defined.
+@item TC_FAKE_LABEL
+@cindex TC_FAKE_LABEL
+You may define this macro to control what GAS considers to be a fake
+label. The default fake label is FAKE_LABEL_NAME.
+
@item NO_PSEUDO_DOT
@cindex NO_PSEUDO_DOT
If you define this macro, GAS will not require pseudo-ops to start with a
If you define this macro, it should return nonzero if the instruction is
permitted to contain an @kbd{=} character. GAS will call it with two
arguments, the character before the @kbd{=} character, and the value of
-@code{input_line_pointer} at that point. GAS uses this macro to decide if a
+the string preceding the equal sign. GAS uses this macro to decide if a
@kbd{=} is an assignment or an instruction.
@item TC_EOL_IN_INSN
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
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
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
@cindex TC_CONS_FIX_NEW
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.
+Used to implement @code{dc.a}. The target must have a reloc for this size.
+
@item TC_INIT_FIX_DATA (@var{fixp})
@cindex TC_INIT_FIX_DATA
A C statement to initialize the target specific fields of fixup @var{fixp}.
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
-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
@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
-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})
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{BFD_ASSEMBLER} and not @code{MANY_SEGMENTS}). It holds the size of a
-relocation entry.
-
@item WORKING_DOT_WORD
@itemx md_short_jump_size
@itemx md_long_jump_size
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 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.
set. The macro is given the N_TYPE bits for the section in its
@var{segT} argument. If the macro evaluates to a non-zero value
then the fixups will be converted into relocs, otherwise they will
-be passed to @var{md_apply_fix3} as normal.
+be passed to @var{md_apply_fix} as normal.
@item md_convert_frag
@cindex md_convert_frag
@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
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 md_apply_fix3 (@var{fixP}, @var{valP}, @var{seg})
-@cindex md_apply_fix3
+@item md_apply_fix (@var{fixP}, @var{valP}, @var{seg})
+@cindex md_apply_fix
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}
+object file. @code{struct fix *@var{fixP}} is the fixup @code{md_apply_fix}
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
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
+@code{md_apply_fix} returns. If the overflow check is relevant for the target
+machine, then @code{md_apply_fix} should modify *@var{valP}, typically to the
value stored in the object file.
@item TC_FORCE_RELOCATION (@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}
+@code{fx_pcrel} 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
+@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
+@code{md_apply_fix}. If undefined, the default of
@w{@code{! SEG_NORMAL (@var{seg})}} 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.
-@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.
-@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.
+@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
-to @code{md_apply_fix3}. If the macro is undefined, or returns non-zero, the
+to @code{md_apply_fix}. 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})
+@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
+This function 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, common or weak, or for ELF assemblers that support ELF shared
-library linking semantics, global.
+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
@item tc_gen_reloc
@cindex tc_gen_reloc
-A @code{BFD_ASSEMBLER} GAS will call this to generate a reloc. GAS will pass
+GAS will call this to generate a reloc. GAS will pass
the resulting reloc to @code{bfd_install_relocation}. This currently works
poorly, as @code{bfd_install_relocation} often does the wrong thing, and
instances of @code{tc_gen_reloc} have been written to work around the problems,
@cindex tc_frob_label
If you define this macro, GAS will call it each time a label is defined.
+@item tc_new_dot_label
+@cindex tc_new_dot_label
+If you define this macro, GAS will call it each time a fake label is created
+off the special dot symbol.
+
@item md_section_align
@cindex md_section_align
GAS will call this function for each section at the end of the assembly, to
@item tc_frob_section
@cindex tc_frob_section
-If you define this macro, a @code{BFD_ASSEMBLER} GAS will call it for each
+If you define this macro, GAS will call it for each
section at the end of the assembly.
@item tc_frob_file_before_adjust
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 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 ()
+@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
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.
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.
+@item MD_DEBUG_FORMAT_SELECTOR
+@cindex MD_DEBUG_FORMAT_SELECTOR
+If defined this macro is the name of a function to be called when the
+@samp{--gen-debug} switch is detected on the assembler's command line. The
+prototype for the function looks like this:
+
+@smallexample
+ enum debug_info_type MD_DEBUG_FORMAT_SELECTOR (int * use_gnu_extensions)
+@end smallexample
+
+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.
+
+@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
The object format @file{.h} file must include @file{targ-cpu.h}.
-This section will only define the @code{BFD_ASSEMBLER} version of GAS. It is
-impossible to support a new object file format using any other version anyhow,
-as the original GAS version only supports a.out, and the @code{MANY_SEGMENTS}
-GAS version only supports COFF.
-
@table @code
@item OBJ_@var{format}
@cindex OBJ_@var{format}
@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
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_set_weak_hook
+@cindex obj_set_weak_hook
+If you define this macro, @code{S_SET_WEAK} will call it before modifying the
+symbol's flags.
+
+@item obj_clear_weak_hook
+@cindex obj_clear_weak_hook
+If you define this macro, @code{S_CLEAR_WEAKREFD} will call it after cleaning
+the @code{weakrefd} flag, but before modifying any other flags.
+
@item obj_frob_file
@cindex obj_frob_file
If you define this macro, GAS will call it after the symbol table has been
@cindex SET_SECTION_RELOCS
If you define this, it will be called after the relocations have been set for
the section @var{sec}. The list of relocations is in @var{relocs}, and the
-number of relocations is in @var{n}. This is only used with
-@code{BFD_ASSEMBLER}.
+number of relocations is in @var{n}.
@end table
@node Emulations
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.
@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
during this invocation.
@end deftypefun
-@deftypefun @{@} void as_perror (const char *@var{gripe}, const char *@var{filename})
-Displays a BFD or system error, then clears the error status.
-@end deftypefun
-
@deftypefun @{@} void as_tsktsk (const char *@var{format}, ...)
@deftypefunx @{@} void as_warn (const char *@var{format}, ...)
@deftypefunx @{@} void as_bad (const char *@var{format}, ...)
original filename and line number that they are applicable to.
@end deftypefun
-@deftypefun @{@} void fprint_value (FILE *@var{file}, valueT @var{val})
-@deftypefunx @{@} void sprint_value (char *@var{buf}, valueT @var{val})
-These functions are helpful for converting a @code{valueT} value into printable
+@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.
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
-@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
-@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
-@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
projects / deliverable / binutils-gdb.git / blobdiff