\input texinfo
@setfilename internals.info
@node Assembler Internals
@chapter Assembler Internals
@cindex internals

@menu
* Data types::		Data types
@end menu

@node foo
@section foo

BFD_ASSEMBLER
BFD, MANY_SECTIONS, BFD_HEADERS


@node Data types
@section Data types
@cindex internals, data types

@subheading Symbols
@cindex internals, symbols
@cindex symbols, internal

... `local' symbols ... flags ...

The definition for @code{struct symbol}, also known as @code{symbolS},
is located in @file{struc-symbol.h}.  Symbol structures can contain the
following fields:

@table @code
@item sy_value
This is an @code{expressionS} that describes the value of the symbol.
It might refer to another symbol; if so, its true value may not be known
until @code{foo} is run.

More generally, however, ... undefined? ... or an offset from the start
of a frag pointed to by the @code{sy_frag} field.

@item sy_resolved
This field is non-zero if the symbol's value has been completely
resolved.  It is used during the final pass over the symbol table.

@item sy_resolving
This field is used to detect loops while resolving the symbol's value.

@item sy_used_in_reloc
This field is non-zero if the symbol is used by a relocation entry.  If
a local symbol is used in a relocation entry, it must be possible to
redirect those relocations to other symbols, or this symbol cannot be
removed from the final symbol list.

@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.)  These fields
should be accessed with @code{symbol_next} and @code{symbol_previous}.

@item sy_frag
This points to the @code{fragS} that this symbol is attached to.

@item sy_used
Whether the symbol is used as an operand or in an expression.  Note: Not
all the backends keep this information accurate; backends which use this
bit are responsible for setting it when a symbol is used in backend
routines.

@item bsym
If @code{BFD_ASSEMBLER} is defined, this points to the @code{asymbol}
that will be used in writing the object file.

@item sy_name_offset
(Only used if @code{BFD_ASSEMBLER} is not defined.)
This is the position of the symbol's name in the symbol 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_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_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 sy_obj
This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}.  If no
macro by that name is defined in @file{obj-format.h}, this field is not
defined.

@item sy_tc
This processor-specific data is of type @code{TC_SYMFIELD_TYPE}.  If no
macro by that name is defined in @file{targ-cpu.h}, this field is not
defined.

@item TARGET_SYMBOL_FIELDS
If this macro is defined, it defines additional fields in the symbol
structure.  This macro is obsolete, and should be replaced when possible
by uses of @code{OBJ_SYMFIELD_TYPE} and @code{TC_SYMFIELD_TYPE}.

@end table

Access with S_SET_SEGMENT, S_SET_VALUE, S_GET_VALUE, S_GET_SEGMENT,
etc., etc.

@node Expressions
@section Expressions
@cindex internals, expressions
@cindex expressions, internal

Expressions are stored as a combination of operator, symbols, blah.

@subheading Fixups
@cindex internals, fixups
@cindex fixups

@subheading Frags
@cindex internals, frags
@cindex frags

@subheading Broken Words
@cindex internals, broken words
@cindex broken words
@cindex promises, promises

@node What Happens?
@section What Happens?

Blah blah blah, initialization, argument parsing, file reading,
whitespace munging, opcode parsing and lookup, operand parsing.  Now
it's time to write the output file.

In @code{BFD_ASSEMBLER} mode, processing of relocations and symbols and
creation of the output file is initiated by calling
@code{write_object_file}.

@node Target Dependent Definitions
@section Target Dependent Definitions

@subheading Format-specific definitions

@defmac obj_sec_sym_ok_for_reloc (section)
(@code{BFD_ASSEMBLER} only.)
Is it okay to use this section's section-symbol in a relocation entry?
If not, a new internal-linkage symbol is generated and emitted if such a
relocation entry is needed.  (Default: Always use a new symbol.)

@end defmac

@defmac obj_adjust_symtab
(@code{BFD_ASSEMBLER} only.)
If this macro is defined, it is invoked just before setting the symbol
table of the output BFD.  Any finalizing changes needed in the symbol
table should be done here.  For example, in the COFF support, if there
is no @code{.file} symbol defined already, one is generated at this
point.  If no such adjustments are needed, this macro need not be
defined.

@end defmac

@defmac EMIT_SECTION_SYMBOLS
(@code{BFD_ASSEMBLER} only.)
Should section symbols be included in the symbol list if they're used in
relocations?  Some formats can generate section-relative relocations,
and thus don't need symbols emitted for them.
(Default: 1.)

@end defmac

@defmac obj_frob_file
Any final cleanup needed before writing out the BFD may be done here.
For example, ECOFF formats (and MIPS ELF format) may do some work on the
MIPS-style symbol table with its integrated debug information.  The
symbol table should not be modified at this time.

@end defmac

@subheading CPU-specific definitions

@defmac tc_frob_file
Like @code{obj_frob_file}, this macro handles miscellaneous last-minute
cleanup.  Currently only used on PowerPC/POWER support, for setting up a
@code{.debug} section.  This macro should not cause the symbol table to
be modified.

@end defmac

@node Source File Summary
@section Source File Summary

@subsection File Format Descriptions

@subheading a.out

The @code{a.out} format is described by @file{obj-aout.*}.

@subheading b.out

The @code{b.out} format, described by @file{obj-bout.*}, is similar to
@code{a.out} format, except for a few additional fields in the file
header describing section alignment and address.

@subheading COFF

Originally, @file{obj-coff} was a purely non-BFD version, and
@file{obj-coffbfd} was created to use BFD for low-level byte-swapping.
When the @code{BFD_ASSEMBLER} conversion started, the first COFF target
to be converted was using @file{obj-coff}, and the two files had
diverged somewhat, and I didn't feel like first converting the support
of that target over to use the low-level BFD interface.

So @file{obj-coff} got converted, and to simplify certain things,
@file{obj-coffbfd} got ``merged'' in with a brute-force approach.
Specifically, preprocessor conditionals testing for @code{BFD_ASSEMBLER}
effectively split the @file{obj-coff} files into the two separate
versions.  They will be merged more thoroughly, and eventually only the
higher-level interface will be used.

@subheading ECOFF

@subheading ELF

@subheading HP300?

@subheading IEEE?

@subheading SOM

@subheading VMS!

@subsection Processor Descriptions

Foo: a29k, alpha, h8300, h8500, hppa, i386, i860, i960, m68k, m88k,
mips, ns32k, ppc, sh, sparc, tahoe, vax, z8k.

@subsection ``Emulation'' Descriptions

@subsection Host header files

Someday these @file{config/ho-*.h} files will be replaced by header
files generated by @code{autoconf} configure scripts.

@node Foo
@section Foo

@subsection Warning and Error Messages

@deftypefun  int had_warnings (void)
@deftypefunx int had_errors (void)

Returns non-zero if any warnings or errors, respectively, have been
printed 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}, ...)
@deftypefunx void as_fatal (const char *@var{format}, ...)

These functions display messages about something amiss with the input
file, or internal problems in the assembler itself.  The current file
name and line number are printed, followed by the supplied message,
formatted using @code{vfprintf}, and a final newline.

@end deftypefun

@deftypefun  void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
@deftypefunx void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)

These variants permit specification of the file name and line number,
and are used when problems are detected when reprocessing information
saved away when processing some earlier part of the file.  For example,
fixups are processed 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

@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 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 (FIXME: currently without
`0x' prefix).  The value itself is not examined to make this
determination.

@end deftypefun

@bye
