Assembler Internals
*******************

foo
===

BFD_ASSEMBLER BFD, MANY_SECTIONS, BFD_HEADERS

Data types
==========

Symbols
-------

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

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

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

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

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.

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

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.

sy_next
sy_previous
     These pointers to other symbolS structures describe a singly or doubly linked list.  (If SYMBOLS_NEED_BACKPOINTERS is not defined, the sy_previous field will be omitted.)  These fields should be accessed with symbol_next and symbol_previous.

sy_frag
     This points to the fragS that this symbol is attached to.

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.

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

sy_name_offset
     (Only used if 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 write_object_file is called.

sy_symbol
     (Only used if BFD_ASSEMBLER is not defined.) This is the format-specific symbol structure, as it would be written into the object file.

sy_number
     (Only used if BFD_ASSEMBLER is not defined.) This is a 24-bit symbol number, for use in constructing relocation table entries.

sy_obj
     This format-specific data is of type OBJ_SYMFIELD_TYPE.  If no macro by that name is defined in obj-format.h, this field is not defined.

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

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 OBJ_SYMFIELD_TYPE and TC_SYMFIELD_TYPE.

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

Expressions

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

Fixups
------

Frags
-----

Broken Words
------------

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 BFD_ASSEMBLER mode, processing of relocations and symbols and creation of the output file is initiated by calling write_object_file.

Target Dependent Definitions
============================

Format-specific definitions

 -- Macro: obj_sec_sym_ok_for_reloc section
     (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.)

      -- Macro: EMIT_SECTION_SYMBOLS
          (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 (Default: 1.)

Source File Summary
===================

The code in the obj-coff back end assumes BFD_ASSEMBLER is defined; the code in obj-coffbfd uses BFD, BFD_HEADERS, and MANY_SEGMENTS, but does a lot of the file positioning itself.  This confusing situation arose from the history of the code.

Originally, obj-coff was a purely non-BFD version, and obj-coffbfd was created to use BFD for low-level byte-swapping. When the BFD_ASSEMBLER conversion started, the first COFF target to be converted was using 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.

Currently, all COFF targets use one of the two BFD interfaces, so the non-BFD code can be removed.  Eventually, all should be converted to using one COFF back end, which uses the high-level BFD interface.

Foo
===

Warning and Error Messages
--------------------------

 -- Function: int had_warnings (void)
 -- Function: int had_errors (void)

     Returns non-zero if any warnings or errors, respectively, have been printed during this invocation.

 -- Function: void as_perror (const char *GRIPE, const char *FILENAME)

     Displays a BFD or system error, then clears the error status.

 -- Function: void as_tsktsk (const char *FORMAT, ...)
 -- Function: void as_warn (const char *FORMAT, ...)
 -- Function: void as_bad (const char *FORMAT, ...)
 -- Function: void as_fatal (const char *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 vfprintf, and a final newline.

 -- Function: void as_warn_where (char *FILE, unsigned int LINE, const char *FORMAT, ...)
 -- Function: void as_bad_where (char *FILE, unsigned int LINE, const char *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.

 -- Function: void fprint_value (FILE *FILE, valueT VAL)
 -- Function: void sprint_value (char *BUF, valueT VAL)

     These functions are helpful for converting a valueT value into printable format, in case it's wider than modes that *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.