gas/doc/internals.texi

   1 @node Assembler Internals
   2 @chapter Assembler Internals
   3 @cindex internals
   4
   5 @menu
   6 * Data types::          Data types
   7 @end menu
   8
   9 @node foo
  10 @section foo
  11
  12 BFD_ASSEMBLER
  13 BFD, MANY_SECTIONS, BFD_HEADERS
  14
  15
  16 @node Data types
  17 @section Data types
  18 @cindex internals, data types
  19
  20 @subheading Symbols
  21 @cindex internals, symbols
  22 @cindex symbols, internal
  23
  24 ... `local' symbols ... flags ...
  25
  26 The definition for @code{struct symbol}, also known as @code{symbolS},
  27 is located in @file{struc-symbol.h}.  Symbol structures can contain the
  28 following fields:
  29
  30 @table @code
  31 @item sy_value
  32 This is an @code{expressionS} that describes the value of the symbol.
  33 It might refer to another symbol; if so, its true value may not be known
  34 until @code{foo} is run.
  35
  36 More generally, however, ... undefined? ... or an offset from the start
  37 of a frag pointed to by the @code{sy_frag} field.
  38
  39 @item sy_resolved
  40 This field is non-zero if the symbol's value has been completely
  41 resolved.  It is used during the final pass over the symbol table.
  42
  43 @item sy_resolving
  44 This field is used to detect loops while resolving the symbol's value.
  45
  46 @item sy_used_in_reloc
  47 This field is non-zero if the symbol is used by a relocation entry.  If
  48 a local symbol is used in a relocation entry, it must be possible to
  49 redirect those relocations to other symbols, or this symbol cannot be
  50 removed from the final symbol list.
  51
  52 @item sy_next
  53 @itemx sy_previous
  54 These pointers to other @code{symbolS} structures describe a singly or
  55 doubly linked list.  (If @code{SYMBOLS_NEED_BACKPOINTERS} is not
  56 defined, the @code{sy_previous} field will be omitted.)  These fields
  57 should be accessed with @code{symbol_next} and @code{symbol_previous}.
  58
  59 @item sy_frag
  60 This points to the @code{fragS} that this symbol is attached to.
  61
  62 @item sy_used
  63 Whether the symbol is used as an operand or in an expression.  Note: Not
  64 all the backends keep this information accurate; backends which use this
  65 bit are responsible for setting it when a symbol is used in backend
  66 routines.
  67
  68 @item bsym
  69 If @code{BFD_ASSEMBLER} is defined, this points to the @code{asymbol}
  70 that will be used in writing the object file.
  71
  72 @item sy_name_offset
  73 (Only used if @code{BFD_ASSEMBLER} is not defined.)
  74 This is the position of the symbol's name in the symbol table of the
  75 object file.  On some formats, this will start at position 4, with
  76 position 0 reserved for unnamed symbols.  This field is not used until
  77 @code{write_object_file} is called.
  78
  79 @item sy_symbol
  80 (Only used if @code{BFD_ASSEMBLER} is not defined.)
  81 This is the format-specific symbol structure, as it would be written into
  82 the object file.
  83
  84 @item sy_number
  85 (Only used if @code{BFD_ASSEMBLER} is not defined.)
  86 This is a 24-bit symbol number, for use in constructing relocation table
  87 entries.
  88
  89 @item sy_obj
  90 This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}.  If no
  91 macro by that name is defined in @file{obj-format.h}, this field is not
  92 defined.
  93
  94 @item sy_tc
  95 This processor-specific data is of type @code{TC_SYMFIELD_TYPE}.  If no
  96 macro by that name is defined in @file{targ-cpu.h}, this field is not
  97 defined.
  98
  99 @item TARGET_SYMBOL_FIELDS
 100 If this macro is defined, it defines additional fields in the symbol
 101 structure.  This macro is obsolete, and should be replaced when possible
 102 by uses of @code{OBJ_SYMFIELD_TYPE} and @code{TC_SYMFIELD_TYPE}.
 103
 104 @end table
 105
 106 Access with S_SET_SEGMENT, S_SET_VALUE, S_GET_VALUE, S_GET_SEGMENT,
 107 etc., etc.
 108
 109 @foo Expressions
 110 @cindex internals, expressions
 111 @cindex expressions, internal
 112
 113 Expressions are stored as a combination of operator, symbols, blah.
 114
 115 @subheading Fixups
 116 @cindex internals, fixups
 117 @cindex fixups
 118
 119 @subheading Frags
 120 @cindex internals, frags
 121 @cindex frags
 122
 123 @subheading Broken Words
 124 @cindex internals, broken words
 125 @cindex broken words
 126 @cindex promises, promises
 127
 128 @node What Happens?
 129 @section What Happens?
 130
 131 Blah blah blah, initialization, argument parsing, file reading,
 132 whitespace munging, opcode parsing and lookup, operand parsing.  Now
 133 it's time to write the output file.
 134
 135 In @code{BFD_ASSEMBLER} mode, processing of relocations and symbols and
 136 creation of the output file is initiated by calling
 137 @code{write_object_file}.
 138
 139 @node Target Dependent Definitions
 140 @section Target Dependent Definitions
 141
 142 @subheader Format-specific definitions
 143
 144 @defmac obj_sec_sym_ok_for_reloc section
 145 (@code{BFD_ASSEMBLER} only.)
 146 Is it okay to use this section's section-symbol in a relocation entry?
 147 If not, a new internal-linkage symbol is generated and emitted if such a
 148 relocation entry is needed.  (Default: Always use a new symbol.)
 149
 150 @defmac EMIT_SECTION_SYMBOLS
 151 (@code{BFD_ASSEMBLER} only.)
 152 Should section symbols be included in the symbol list if they're used in
 153 relocations?  Some formats can generate section-relative relocations,
 154 and thus don't need
 155 (Default: 1.)
 156
 157 @node Source File Summary
 158 @section Source File Summary
 159
 160 The code in the @file{obj-coff} back end assumes @code{BFD_ASSEMBLER} is
 161 defined; the code in @file{obj-coffbfd} uses @code{BFD},
 162 @code{BFD_HEADERS}, and @code{MANY_SEGMENTS}, but does a lot of the file
 163 positioning itself.  This confusing situation arose from the history of
 164 the code.
 165
 166 Originally, @file{obj-coff} was a purely non-BFD version, and
 167 @file{obj-coffbfd} was created to use BFD for low-level byte-swapping.
 168 When the @code{BFD_ASSEMBLER} conversion started, the first COFF target
 169 to be converted was using @file{obj-coff}, and the two files had
 170 diverged somewhat, and I didn't feel like first converting the support
 171 of that target over to use the low-level BFD interface.
 172
 173 Currently, all COFF targets use one of the two BFD interfaces, so the
 174 non-BFD code can be removed.  Eventually, all should be converted to
 175 using one COFF back end, which uses the high-level BFD interface.
 176
 177 @node Foo
 178 @section Foo
 179
 180 @subsection Warning and Error Messages
 181
 182 @deftypefun  int had_warnings (void)
 183 @deftypefunx int had_errors (void)
 184
 185 Returns non-zero if any warnings or errors, respectively, have been
 186 printed during this invocation.
 187
 188 @end deftypefun
 189
 190 @deftypefun  void as_perror (const char *@var{gripe}, const char *@var{filename})
 191
 192 Displays a BFD or system error, then clears the error status.
 193
 194 @end deftypefun
 195
 196 @deftypefun  void as_tsktsk (const char *@var{format}, ...)
 197 @deftypefunx void as_warn (const char *@var{format}, ...)
 198 @deftypefunx void as_bad (const char *@var{format}, ...)
 199 @deftypefunx void as_fatal (const char *@var{format}, ...)
 200
 201 These functions display messages about something amiss with the input
 202 file, or internal problems in the assembler itself.  The current file
 203 name and line number are printed, followed by the supplied message,
 204 formatted using @code{vfprintf}, and a final newline.
 205
 206 @end deftypefun
 207
 208 @deftypefun  void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
 209 @deftypefunx void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
 210
 211 These variants permit specification of the file name and line number,
 212 and are used when problems are detected when reprocessing information
 213 saved away when processing some earlier part of the file.  For example,
 214 fixups are processed after all input has been read, but messages about
 215 fixups should refer to the original filename and line number that they
 216 are applicable to.
 217
 218 @end deftypefun
 219
 220 @deftypefun  void fprint_value (FILE *@var{file}, valueT @var{val})
 221 @deftypefunx void sprint_value (char *@var{buf}, valueT @var{val})
 222
 223 These functions are helpful for converting a @code{valueT} value into
 224 printable format, in case it's wider than modes that @code{*printf} can
 225 handle.  If the type is narrow enough, a decimal number will be
 226 produced; otherwise, it will be in hexadecimal (FIXME: currently without
 227 `0x' prefix).  The value itself is not examined to make this
 228 determination.
 229
 230 @end deftypefun