1 @node Assembler Internals
2 @chapter Assembler Internals
6 * Data types:: Data types
13 BFD, MANY_SECTIONS, BFD_HEADERS
18 @cindex internals, data types
21 @cindex internals, symbols
22 @cindex symbols, internal
24 ... `local' symbols ... flags ...
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
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.
36 More generally, however, ... undefined? ... or an offset from the start
37 of a frag pointed to by the @code{sy_frag} field.
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.
44 This field is used to detect loops while resolving the symbol's value.
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.
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}.
60 This points to the @code{fragS} that this symbol is attached to.
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
69 If @code{BFD_ASSEMBLER} is defined, this points to the @code{asymbol}
70 that will be used in writing the object file.
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.
80 (Only used if @code{BFD_ASSEMBLER} is not defined.)
81 This is the format-specific symbol structure, as it would be written into
85 (Only used if @code{BFD_ASSEMBLER} is not defined.)
86 This is a 24-bit symbol number, for use in constructing relocation table
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
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
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}.
106 Access with S_SET_SEGMENT, S_SET_VALUE, S_GET_VALUE, S_GET_SEGMENT,
110 @cindex internals, expressions
111 @cindex expressions, internal
113 Expressions are stored as a combination of operator, symbols, blah.
116 @cindex internals, fixups
120 @cindex internals, frags
123 @subheading Broken Words
124 @cindex internals, broken words
126 @cindex promises, promises
129 @section What Happens?
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.
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}.
139 @node Target Dependent Definitions
140 @section Target Dependent Definitions
142 @subheader Format-specific definitions
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.)
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,
157 @node Source File Summary
158 @section Source File Summary
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
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.
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.
180 @subsection Warning and Error Messages
182 @deftypefun int had_warnings (void)
183 @deftypefunx int had_errors (void)
185 Returns non-zero if any warnings or errors, respectively, have been
186 printed during this invocation.
190 @deftypefun void as_perror (const char *@var{gripe}, const char *@var{filename})
192 Displays a BFD or system error, then clears the error status.
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}, ...)
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.
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}, ...)
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
220 @deftypefun void fprint_value (FILE *@var{file}, valueT @var{val})
221 @deftypefunx void sprint_value (char *@var{buf}, valueT @var{val})
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