48d49e06495481c7df9fae913986086283c1749e
[deliverable/binutils-gdb.git] / gas / doc / internals.texi
1 \input texinfo
2 @setfilename internals.info
3 @node Top
4 @top Assembler Internals
5 @raisesections
6 @cindex internals
7
8 This chapter describes the internals of the assembler. It is incomplete, but
9 it may help a bit.
10
11 This chapter was last modified on $Date$. It is not updated regularly, and it
12 may be out of date.
13
14 @menu
15 * GAS versions:: GAS versions
16 * Data types:: Data types
17 * GAS processing:: What GAS does when it runs
18 * Porting GAS:: Porting GAS
19 * Relaxation:: Relaxation
20 * Broken words:: Broken words
21 * Internal functions:: Internal functions
22 * Test suite:: Test suite
23 @end menu
24
25 @node GAS versions
26 @section GAS versions
27
28 GAS has acquired layers of code over time. The original GAS only supported the
29 a.out object file format, with three sections. Support for multiple sections
30 has been added in two different ways.
31
32 The preferred approach is to use the version of GAS created when the symbol
33 @code{BFD_ASSEMBLER} is defined. The other versions of GAS are documented for
34 historical purposes, and to help anybody who has to debug code written for
35 them.
36
37 The type @code{segT} is used to represent a section in code which must work
38 with all versions of GAS.
39
40 @menu
41 * Original GAS:: Original GAS version
42 * MANY_SEGMENTS:: MANY_SEGMENTS gas version
43 * BFD_ASSEMBLER:: BFD_ASSEMBLER gas version
44 @end menu
45
46 @node Original GAS
47 @subsection Original GAS
48
49 The original GAS only supported the a.out object file format with three
50 sections: @samp{.text}, @samp{.data}, and @samp{.bss}. This is the version of
51 GAS that is compiled if neither @code{BFD_ASSEMBLER} nor @code{MANY_SEGMENTS}
52 is defined. This version of GAS is still used for the m68k-aout target, and
53 perhaps others.
54
55 This version of GAS should not be used for any new development.
56
57 There is still code that is specific to this version of GAS, notably in
58 @file{write.c}. There is no way for this code to loop through all the
59 sections; it simply looks at global variables like @code{text_frag_root} and
60 @code{data_frag_root}.
61
62 The type @code{segT} is an enum.
63
64 @node MANY_SEGMENTS
65 @subsection MANY_SEGMENTS gas version
66 @cindex MANY_SEGMENTS
67
68 The @code{MANY_SEGMENTS} version of gas is only used for COFF. It uses the BFD
69 library, but it writes out all the data itself using @code{bfd_write}. This
70 version of gas supports up to 40 normal sections. The section names are stored
71 in the @code{seg_name} array. Other information is stored in the
72 @code{segment_info} array.
73
74 The type @code{segT} is an enum. Code that wants to examine all the sections
75 can use a @code{segT} variable as loop index from @code{SEG_E0} up to but not
76 including @code{SEG_UNKNOWN}.
77
78 Most of the code specific to this version of GAS is in the file
79 @file{config/obj-coff.c}, in the portion of that file that is compiled when
80 @code{BFD_ASSEMBLER} is not defined.
81
82 This version of GAS is still used for several COFF targets.
83
84 @node BFD_ASSEMBLER
85 @subsection BFD_ASSEMBLER gas version
86 @cindex BFD_ASSEMBLER
87
88 The preferred version of GAS is the @code{BFD_ASSEMBLER} version. In this
89 version of GAS, the output file is a normal BFD, and the BFD routines are used
90 to generate the output.
91
92 @code{BFD_ASSEMBLER} will automatically be used for certain targets, including
93 those that use the ELF, ECOFF, and SOM object file formats, and also all Alpha,
94 MIPS, PowerPC, and SPARC targets. You can force the use of
95 @code{BFD_ASSEMBLER} for other targets with the configure option
96 @samp{--enable-bfd-assembler}; however, it has not been tested for many
97 targets, and can not be assumed to work.
98
99 @node Data types
100 @section Data types
101 @cindex internals, data types
102
103 This section describes some fundamental GAS data types.
104
105 @menu
106 * Symbols:: The symbolS structure
107 * Expressions:: The expressionS structure
108 * Fixups:: The fixS structure
109 * Frags:: The fragS structure
110 @end menu
111
112 @node Symbols
113 @subsection Symbols
114 @cindex internals, symbols
115 @cindex symbols, internal
116 @cindex symbolS structure
117
118 The definition for @code{struct symbol}, also known as @code{symbolS}, is
119 located in @file{struc-symbol.h}. Symbol structures contain the following
120 fields:
121
122 @table @code
123 @item sy_value
124 This is an @code{expressionS} that describes the value of the symbol. It might
125 refer to one or more other symbols; if so, its true value may not be known
126 until @code{resolve_symbol_value} is called in @code{write_object_file}.
127
128 The expression is often simply a constant. Before @code{resolve_symbol_value}
129 is called, the value is the offset from the frag (@pxref{Frags}). Afterward,
130 the frag address has been added in.
131
132 @item sy_resolved
133 This field is non-zero if the symbol's value has been completely resolved. It
134 is used during the final pass over the symbol table.
135
136 @item sy_resolving
137 This field is used to detect loops while resolving the symbol's value.
138
139 @item sy_used_in_reloc
140 This field is non-zero if the symbol is used by a relocation entry. If a local
141 symbol is used in a relocation entry, it must be possible to redirect those
142 relocations to other symbols, or this symbol cannot be removed from the final
143 symbol list.
144
145 @item sy_next
146 @itemx sy_previous
147 These pointers to other @code{symbolS} structures describe a singly or doubly
148 linked list. (If @code{SYMBOLS_NEED_BACKPOINTERS} is not defined, the
149 @code{sy_previous} field will be omitted; @code{SYMBOLS_NEED_BACKPOINTERS} is
150 always defined if @code{BFD_ASSEMBLER}.) These fields should be accessed with
151 the @code{symbol_next} and @code{symbol_previous} macros.
152
153 @item sy_frag
154 This points to the frag (@pxref{Frags}) that this symbol is attached to.
155
156 @item sy_used
157 Whether the symbol is used as an operand or in an expression. Note: Not all of
158 the backends keep this information accurate; backends which use this bit are
159 responsible for setting it when a symbol is used in backend routines.
160
161 @item sy_mri_common
162 Whether the symbol is an MRI common symbol created by the @code{COMMON}
163 pseudo-op when assembling in MRI mode.
164
165 @item bsym
166 If @code{BFD_ASSEMBLER} is defined, this points to the BFD @code{asymbol} that
167 will be used in writing the object file.
168
169 @item sy_name_offset
170 (Only used if @code{BFD_ASSEMBLER} is not defined.) This is the position of
171 the symbol's name in the string table of the object file. On some formats,
172 this will start at position 4, with position 0 reserved for unnamed symbols.
173 This field is not used until @code{write_object_file} is called.
174
175 @item sy_symbol
176 (Only used if @code{BFD_ASSEMBLER} is not defined.) This is the
177 format-specific symbol structure, as it would be written into the object file.
178
179 @item sy_number
180 (Only used if @code{BFD_ASSEMBLER} is not defined.) This is a 24-bit symbol
181 number, for use in constructing relocation table entries.
182
183 @item sy_obj
184 This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by
185 that name is defined in @file{obj-format.h}, this field is not defined.
186
187 @item sy_tc
188 This processor-specific data is of type @code{TC_SYMFIELD_TYPE}. If no macro
189 by that name is defined in @file{targ-cpu.h}, this field is not defined.
190
191 @item TARGET_SYMBOL_FIELDS
192 If this macro is defined, it defines additional fields in the symbol structure.
193 This macro is obsolete, and should be replaced when possible by uses of
194 @code{OBJ_SYMFIELD_TYPE} and @code{TC_SYMFIELD_TYPE}.
195 @end table
196
197 There are a number of access routines used to extract the fields of a
198 @code{symbolS} structure. When possible, these routines should be used rather
199 than referring to the fields directly. These routines will work for any GAS
200 version.
201
202 @table @code
203 @item S_SET_VALUE
204 @cindex S_SET_VALUE
205 Set the symbol's value.
206
207 @item S_GET_VALUE
208 @cindex S_GET_VALUE
209 Get the symbol's value. This will cause @code{resolve_symbol_value} to be
210 called if necessary, so @code{S_GET_VALUE} should only be called when it is
211 safe to resolve symbols (i.e., after the entire input file has been read and
212 all symbols have been defined).
213
214 @item S_SET_SEGMENT
215 @cindex S_SET_SEGMENT
216 Set the section of the symbol.
217
218 @item S_GET_SEGMENT
219 @cindex S_GET_SEGMENT
220 Get the symbol's section.
221
222 @item S_GET_NAME
223 @cindex S_GET_NAME
224 Get the name of the symbol.
225
226 @item S_SET_NAME
227 @cindex S_SET_NAME
228 Set the name of the symbol.
229
230 @item S_IS_EXTERNAL
231 @cindex S_IS_EXTERNAL
232 Return non-zero if the symbol is externally visible.
233
234 @item S_IS_EXTERN
235 @cindex S_IS_EXTERN
236 A synonym for @code{S_IS_EXTERNAL}. Don't use it.
237
238 @item S_IS_WEAK
239 @cindex S_IS_WEAK
240 Return non-zero if the symbol is weak.
241
242 @item S_IS_COMMON
243 @cindex S_IS_COMMON
244 Return non-zero if this is a common symbol. Common symbols are sometimes
245 represented as undefined symbols with a value, in which case this function will
246 not be reliable.
247
248 @item S_IS_DEFINED
249 @cindex S_IS_DEFINED
250 Return non-zero if this symbol is defined. This function is not reliable when
251 called on a common symbol.
252
253 @item S_IS_DEBUG
254 @cindex S_IS_DEBUG
255 Return non-zero if this is a debugging symbol.
256
257 @item S_IS_LOCAL
258 @cindex S_IS_LOCAL
259 Return non-zero if this is a local assembler symbol which should not be
260 included in the final symbol table. Note that this is not the opposite of
261 @code{S_IS_EXTERNAL}. The @samp{-L} assembler option affects the return value
262 of this function.
263
264 @item S_SET_EXTERNAL
265 @cindex S_SET_EXTERNAL
266 Mark the symbol as externally visible.
267
268 @item S_CLEAR_EXTERNAL
269 @cindex S_CLEAR_EXTERNAL
270 Mark the symbol as not externally visible.
271
272 @item S_SET_WEAK
273 @cindex S_SET_WEAK
274 Mark the symbol as weak.
275
276 @item S_GET_TYPE
277 @item S_GET_DESC
278 @item S_GET_OTHER
279 @cindex S_GET_TYPE
280 @cindex S_GET_DESC
281 @cindex S_GET_OTHER
282 Get the @code{type}, @code{desc}, and @code{other} fields of the symbol. These
283 are only defined for object file formats for which they make sense (primarily
284 a.out).
285
286 @item S_SET_TYPE
287 @item S_SET_DESC
288 @item S_SET_OTHER
289 @cindex S_SET_TYPE
290 @cindex S_SET_DESC
291 @cindex S_SET_OTHER
292 Set the @code{type}, @code{desc}, and @code{other} fields of the symbol. These
293 are only defined for object file formats for which they make sense (primarily
294 a.out).
295
296 @item S_GET_SIZE
297 @cindex S_GET_SIZE
298 Get the size of a symbol. This is only defined for object file formats for
299 which it makes sense (primarily ELF).
300
301 @item S_SET_SIZE
302 @cindex S_SET_SIZE
303 Set the size of a symbol. This is only defined for object file formats for
304 which it makes sense (primarily ELF).
305 @end table
306
307 @node Expressions
308 @subsection Expressions
309 @cindex internals, expressions
310 @cindex expressions, internal
311 @cindex expressionS structure
312
313 Expressions are stored in an @code{expressionS} structure. The structure is
314 defined in @file{expr.h}.
315
316 @cindex expression
317 The macro @code{expression} will create an @code{expressionS} structure based
318 on the text found at the global variable @code{input_line_pointer}.
319
320 @cindex make_expr_symbol
321 @cindex expr_symbol_where
322 A single @code{expressionS} structure can represent a single operation.
323 Complex expressions are formed by creating @dfn{expression symbols} and
324 combining them in @code{expressionS} structures. An expression symbol is
325 created by calling @code{make_expr_symbol}. An expression symbol should
326 naturally never appear in a symbol table, and the implementation of
327 @code{S_IS_LOCAL} (@pxref{Symbols}) reflects that. The function
328 @code{expr_symbol_where} returns non-zero if a symbol is an expression symbol,
329 and also returns the file and line for the expression which caused it to be
330 created.
331
332 The @code{expressionS} structure has two symbol fields, a number field, an
333 operator field, and a field indicating whether the number is unsigned.
334
335 The operator field is of type @code{operatorT}, and describes how to interpret
336 the other fields; see the definition in @file{expr.h} for the possibilities.
337
338 An @code{operatorT} value of @code{O_big} indicates either a floating point
339 number, stored in the global variable @code{generic_floating_point_number}, or
340 an integer to large to store in an @code{offsetT} type, stored in the global
341 array @code{generic_bignum}. This rather inflexible approach makes it
342 impossible to use floating point numbers or large expressions in complex
343 expressions.
344
345 @node Fixups
346 @subsection Fixups
347 @cindex internals, fixups
348 @cindex fixups
349 @cindex fixS structure
350
351 A @dfn{fixup} is basically anything which can not be resolved in the first
352 pass. Sometimes a fixup can be resolved by the end of the assembly; if not,
353 the fixup becomes a relocation entry in the object file.
354
355 @cindex fix_new
356 @cindex fix_new_exp
357 A fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both
358 take a frag (@pxref{Frags}), a position within the frag, a size, an indication
359 of whether the fixup is PC relative, and a type. In a @code{BFD_ASSEMBLER}
360 GAS, the type is nominally a @code{bfd_reloc_code_real_type}, but several
361 targets use other type codes to represent fixups that can not be described as
362 relocations.
363
364 The @code{fixS} structure has a number of fields, several of which are obsolete
365 or are only used by a particular target. The important fields are:
366
367 @table @code
368 @item fx_frag
369 The frag (@pxref{Frags}) this fixup is in.
370
371 @item fx_where
372 The location within the frag where the fixup occurs.
373
374 @item fx_addsy
375 The symbol this fixup is against. Typically, the value of this symbol is added
376 into the object contents. This may be NULL.
377
378 @item fx_subsy
379 The value of this symbol is subtracted from the object contents. This is
380 normally NULL.
381
382 @item fx_offset
383 A number which is added into the fixup.
384
385 @item fx_addnumber
386 Some CPU backends use this field to convey information between
387 @code{md_apply_fix} and @code{tc_gen_reloc}. The machine independent code does
388 not use it.
389
390 @item fx_next
391 The next fixup in the section.
392
393 @item fx_r_type
394 The type of the fixup. This field is only defined if @code{BFD_ASSEMBLER}, or
395 if the target defines @code{NEED_FX_R_TYPE}.
396
397 @item fx_size
398 The size of the fixup. This is mostly used for error checking.
399
400 @item fx_pcrel
401 Whether the fixup is PC relative.
402
403 @item fx_done
404 Non-zero if the fixup has been applied, and no relocation entry needs to be
405 generated.
406
407 @item fx_file
408 @itemx fx_line
409 The file and line where the fixup was created.
410
411 @item tc_fix_data
412 This has the type @code{TC_FIX_TYPE}, and is only defined if the target defines
413 that macro.
414 @end table
415
416 @node Frags
417 @subsection Frags
418 @cindex internals, frags
419 @cindex frags
420 @cindex fragS structure.
421
422 The @code{fragS} structure is defined in @file{as.h}. Each frag represents a
423 portion of the final object file. As GAS reads the source file, it creates
424 frags to hold the data that it reads. At the end of the assembly the frags and
425 fixups are processed to produce the final contents.
426
427 @table @code
428 @item fr_address
429 The address of the frag. This is not set until the assembler rescans the list
430 of all frags after the entire input file is parsed. The function
431 @code{relax_segment} fills in this field.
432
433 @item fr_next
434 Pointer to the next frag in this (sub)section.
435
436 @item fr_fix
437 Fixed number of characters we know we're going to emit to the output file. May
438 be zero.
439
440 @item fr_var
441 Variable number of characters we may output, after the initial @code{fr_fix}
442 characters. May be zero.
443
444 @item fr_offset
445 The interpretation of this field is controlled by @code{fr_type}. Generally,
446 if @code{fr_var} is non-zero, this is a repeat count: the @code{fr_var}
447 characters are output @code{fr_offset} times.
448
449 @item line
450 Holds line number info when an assembler listing was requested.
451
452 @item fr_type
453 Relaxation state. This field indicates the interpretation of @code{fr_offset},
454 @code{fr_symbol} and the variable-length tail of the frag, as well as the
455 treatment it gets in various phases of processing. It does not affect the
456 initial @code{fr_fix} characters; they are always supposed to be output
457 verbatim (fixups aside). See below for specific values this field can have.
458
459 @item fr_subtype
460 Relaxation substate. If the macro @code{md_relax_frag} isn't defined, this is
461 assumed to be an index into @code{TC_GENERIC_RELAX_TABLE} for the generic
462 relaxation code to process (@pxref{Relaxation}). If @code{md_relax_frag} is
463 defined, this field is available for any use by the CPU-specific code.
464
465 @item fr_symbol
466 This normally indicates the symbol to use when relaxing the frag according to
467 @code{fr_type}.
468
469 @item fr_opcode
470 Points to the lowest-addressed byte of the opcode, for use in relaxation.
471
472 @item tc_frag_data
473 Target specific fragment data of type TC_FRAG_TYPE.
474 Only present if @code{TC_FRAG_TYPE} is defined.
475
476 @item fr_file
477 @itemx fr_line
478 The file and line where this frag was last modified.
479
480 @item fr_literal
481 Declared as a one-character array, this last field grows arbitrarily large to
482 hold the actual contents of the frag.
483 @end table
484
485 These are the possible relaxation states, provided in the enumeration type
486 @code{relax_stateT}, and the interpretations they represent for the other
487 fields:
488
489 @table @code
490 @item rs_align
491 @itemx rs_align_code
492 The start of the following frag should be aligned on some boundary. In this
493 frag, @code{fr_offset} is the logarithm (base 2) of the alignment in bytes.
494 (For example, if alignment on an 8-byte boundary were desired, @code{fr_offset}
495 would have a value of 3.) The variable characters indicate the fill pattern to
496 be used. The @code{fr_subtype} field holds the maximum number of bytes to skip
497 when doing this alignment. If more bytes are needed, the alignment is not
498 done. An @code{fr_subtype} value of 0 means no maximum, which is the normal
499 case. Target backends can use @code{rs_align_code} to handle certain types of
500 alignment differently.
501
502 @item rs_broken_word
503 This indicates that ``broken word'' processing should be done (@pxref{Broken
504 words}). If broken word processing is not necessary on the target machine,
505 this enumerator value will not be defined.
506
507 @item rs_cfa
508 This state is used to implement exception frame optimizations. The
509 @code{fr_symbol} is an expression symbol for the subtraction which may be
510 relaxed. The @code{fr_opcode} field holds the frag for the preceding command
511 byte. The @code{fr_offset} field holds the offset within that frag. The
512 @code{fr_subtype} field is used during relaxation to hold the current size of
513 the frag.
514
515 @item rs_fill
516 The variable characters are to be repeated @code{fr_offset} times. If
517 @code{fr_offset} is 0, this frag has a length of @code{fr_fix}. Most frags
518 have this type.
519
520 @item rs_leb128
521 This state is used to implement the DWARF ``little endian base 128''
522 variable length number format. The @code{fr_symbol} is always an expression
523 symbol, as constant expressions are emitted directly. The @code{fr_offset}
524 field is used during relaxation to hold the previous size of the number so
525 that we can determine if the fragment changed size.
526
527 @item rs_machine_dependent
528 Displacement relaxation is to be done on this frag. The target is indicated by
529 @code{fr_symbol} and @code{fr_offset}, and @code{fr_subtype} indicates the
530 particular machine-specific addressing mode desired. @xref{Relaxation}.
531
532 @item rs_org
533 The start of the following frag should be pushed back to some specific offset
534 within the section. (Some assemblers use the value as an absolute address; GAS
535 does not handle final absolute addresses, but rather requires that the linker
536 set them.) The offset is given by @code{fr_symbol} and @code{fr_offset}; one
537 character from the variable-length tail is used as the fill character.
538 @end table
539
540 @cindex frchainS structure
541 A chain of frags is built up for each subsection. The data structure
542 describing a chain is called a @code{frchainS}, and contains the following
543 fields:
544
545 @table @code
546 @item frch_root
547 Points to the first frag in the chain. May be NULL if there are no frags in
548 this chain.
549 @item frch_last
550 Points to the last frag in the chain, or NULL if there are none.
551 @item frch_next
552 Next in the list of @code{frchainS} structures.
553 @item frch_seg
554 Indicates the section this frag chain belongs to.
555 @item frch_subseg
556 Subsection (subsegment) number of this frag chain.
557 @item fix_root, fix_tail
558 (Defined only if @code{BFD_ASSEMBLER} is defined). Point to first and last
559 @code{fixS} structures associated with this subsection.
560 @item frch_obstack
561 Not currently used. Intended to be used for frag allocation for this
562 subsection. This should reduce frag generation caused by switching sections.
563 @item frch_frag_now
564 The current frag for this subsegment.
565 @end table
566
567 A @code{frchainS} corresponds to a subsection; each section has a list of
568 @code{frchainS} records associated with it. In most cases, only one subsection
569 of each section is used, so the list will only be one element long, but any
570 processing of frag chains should be prepared to deal with multiple chains per
571 section.
572
573 After the input files have been completely processed, and no more frags are to
574 be generated, the frag chains are joined into one per section for further
575 processing. After this point, it is safe to operate on one chain per section.
576
577 The assembler always has a current frag, named @code{frag_now}. More space is
578 allocated for the current frag using the @code{frag_more} function; this
579 returns a pointer to the amount of requested space. Relaxing is done using
580 variant frags allocated by @code{frag_var} or @code{frag_variant}
581 (@pxref{Relaxation}).
582
583 @node GAS processing
584 @section What GAS does when it runs
585 @cindex internals, overview
586
587 This is a quick look at what an assembler run looks like.
588
589 @itemize @bullet
590 @item
591 The assembler initializes itself by calling various init routines.
592
593 @item
594 For each source file, the @code{read_a_source_file} function reads in the file
595 and parses it. The global variable @code{input_line_pointer} points to the
596 current text; it is guaranteed to be correct up to the end of the line, but not
597 farther.
598
599 @item
600 For each line, the assembler passes labels to the @code{colon} function, and
601 isolates the first word. If it looks like a pseudo-op, the word is looked up
602 in the pseudo-op hash table @code{po_hash} and dispatched to a pseudo-op
603 routine. Otherwise, the target dependent @code{md_assemble} routine is called
604 to parse the instruction.
605
606 @item
607 When pseudo-ops or instructions output data, they add it to a frag, calling
608 @code{frag_more} to get space to store it in.
609
610 @item
611 Pseudo-ops and instructions can also output fixups created by @code{fix_new} or
612 @code{fix_new_exp}.
613
614 @item
615 For certain targets, instructions can create variant frags which are used to
616 store relaxation information (@pxref{Relaxation}).
617
618 @item
619 When the input file is finished, the @code{write_object_file} routine is
620 called. It assigns addresses to all the frags (@code{relax_segment}), resolves
621 all the fixups (@code{fixup_segment}), resolves all the symbol values (using
622 @code{resolve_symbol_value}), and finally writes out the file (in the
623 @code{BFD_ASSEMBLER} case, this is done by simply calling @code{bfd_close}).
624 @end itemize
625
626 @node Porting GAS
627 @section Porting GAS
628 @cindex porting
629
630 Each GAS target specifies two main things: the CPU file and the object format
631 file. Two main switches in the @file{configure.in} file handle this. The
632 first switches on CPU type to set the shell variable @code{cpu_type}. The
633 second switches on the entire target to set the shell variable @code{fmt}.
634
635 The configure script uses the value of @code{cpu_type} to select two files in
636 the @file{config} directory: @file{tc-@var{CPU}.c} and @file{tc-@var{CPU}.h}.
637 The configuration process will create a file named @file{targ-cpu.h} in the
638 build directory which includes @file{tc-@var{CPU}.h}.
639
640 The configure script also uses the value of @code{fmt} to select two files:
641 @file{obj-@var{fmt}.c} and @file{obj-@var{fmt}.h}. The configuration process
642 will create a file named @file{obj-format.h} in the build directory which
643 includes @file{obj-@var{fmt}.h}.
644
645 You can also set the emulation in the configure script by setting the @code{em}
646 variable. Normally the default value of @samp{generic} is fine. The
647 configuration process will create a file named @file{targ-env.h} in the build
648 directory which includes @file{te-@var{em}.h}.
649
650 Porting GAS to a new CPU requires writing the @file{tc-@var{CPU}} files.
651 Porting GAS to a new object file format requires writing the
652 @file{obj-@var{fmt}} files. There is sometimes some interaction between these
653 two files, but it is normally minimal.
654
655 The best approach is, of course, to copy existing files. The documentation
656 below assumes that you are looking at existing files to see usage details.
657
658 These interfaces have grown over time, and have never been carefully thought
659 out or designed. Nothing about the interfaces described here is cast in stone.
660 It is possible that they will change from one version of the assembler to the
661 next. Also, new macros are added all the time as they are needed.
662
663 @menu
664 * CPU backend:: Writing a CPU backend
665 * Object format backend:: Writing an object format backend
666 * Emulations:: Writing emulation files
667 @end menu
668
669 @node CPU backend
670 @subsection Writing a CPU backend
671 @cindex CPU backend
672 @cindex @file{tc-@var{CPU}}
673
674 The CPU backend files are the heart of the assembler. They are the only parts
675 of the assembler which actually know anything about the instruction set of the
676 processor.
677
678 You must define a reasonably small list of macros and functions in the CPU
679 backend files. You may define a large number of additional macros in the CPU
680 backend files, not all of which are documented here. You must, of course,
681 define macros in the @file{.h} file, which is included by every assembler
682 source file. You may define the functions as macros in the @file{.h} file, or
683 as functions in the @file{.c} file.
684
685 @table @code
686 @item TC_@var{CPU}
687 @cindex TC_@var{CPU}
688 By convention, you should define this macro in the @file{.h} file. For
689 example, @file{tc-m68k.h} defines @code{TC_M68K}. You might have to use this
690 if it is necessary to add CPU specific code to the object format file.
691
692 @item TARGET_FORMAT
693 This macro is the BFD target name to use when creating the output file. This
694 will normally depend upon the @code{OBJ_@var{FMT}} macro.
695
696 @item TARGET_ARCH
697 This macro is the BFD architecture to pass to @code{bfd_set_arch_mach}.
698
699 @item TARGET_MACH
700 This macro is the BFD machine number to pass to @code{bfd_set_arch_mach}. If
701 it is not defined, GAS will use 0.
702
703 @item TARGET_BYTES_BIG_ENDIAN
704 You should define this macro to be non-zero if the target is big endian, and
705 zero if the target is little endian.
706
707 @item md_shortopts
708 @itemx md_longopts
709 @itemx md_longopts_size
710 @itemx md_parse_option
711 @itemx md_show_usage
712 @cindex md_shortopts
713 @cindex md_longopts
714 @cindex md_longopts_size
715 @cindex md_parse_option
716 @cindex md_show_usage
717 GAS uses these variables and functions during option processing.
718 @code{md_shortopts} is a @code{const char *} which GAS adds to the machine
719 independent string passed to @code{getopt}. @code{md_longopts} is a
720 @code{struct option []} which GAS adds to the machine independent long options
721 passed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in
722 @file{as.h}, as the start of a set of long option indices, if necessary.
723 @code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}.
724 GAS will call @code{md_parse_option} whenever @code{getopt} returns an
725 unrecognized code, presumably indicating a special code value which appears in
726 @code{md_longopts}. GAS will call @code{md_show_usage} when a usage message is
727 printed; it should print a description of the machine specific options.
728
729 @item md_begin
730 @cindex md_begin
731 GAS will call this function at the start of the assembly, after the command
732 line arguments have been parsed and all the machine independent initializations
733 have been completed.
734
735 @item md_cleanup
736 @cindex md_cleanup
737 If you define this macro, GAS will call it at the end of each input file.
738
739 @item md_assemble
740 @cindex md_assemble
741 GAS will call this function for each input line which does not contain a
742 pseudo-op. The argument is a null terminated string. The function should
743 assemble the string as an instruction with operands. Normally
744 @code{md_assemble} will do this by calling @code{frag_more} and writing out
745 some bytes (@pxref{Frags}). @code{md_assemble} will call @code{fix_new} to
746 create fixups as needed (@pxref{Fixups}). Targets which need to do special
747 purpose relaxation will call @code{frag_var}.
748
749 @item md_pseudo_table
750 @cindex md_pseudo_table
751 This is a const array of type @code{pseudo_typeS}. It is a mapping from
752 pseudo-op names to functions. You should use this table to implement
753 pseudo-ops which are specific to the CPU.
754
755 @item tc_conditional_pseudoop
756 @cindex tc_conditional_pseudoop
757 If this macro is defined, GAS will call it with a @code{pseudo_typeS} argument.
758 It should return non-zero if the pseudo-op is a conditional which controls
759 whether code is assembled, such as @samp{.if}. GAS knows about the normal
760 conditional pseudo-ops,and you should normally not have to define this macro.
761
762 @item comment_chars
763 @cindex comment_chars
764 This is a null terminated @code{const char} array of characters which start a
765 comment.
766
767 @item tc_comment_chars
768 @cindex tc_comment_chars
769 If this macro is defined, GAS will use it instead of @code{comment_chars}.
770
771 @item tc_symbol_chars
772 @cindex tc_symbol_chars
773 If this macro is defined, it is a pointer to a null terminated list of
774 characters which may appear in an operand. GAS already assumes that all
775 alphanumberic characters, and @samp{$}, @samp{.}, and @samp{_} may appear in an
776 operand (see @samp{symbol_chars} in @file{app.c}). This macro may be defined
777 to treat additional characters as appearing in an operand. This affects the
778 way in which GAS removes whitespace before passing the string to
779 @samp{md_assemble}.
780
781 @item line_comment_chars
782 @cindex line_comment_chars
783 This is a null terminated @code{const char} array of characters which start a
784 comment when they appear at the start of a line.
785
786 @item line_separator_chars
787 @cindex line_separator_chars
788 This is a null terminated @code{const char} array of characters which separate
789 lines (semicolon and newline are such characters by default, and need not be
790 listed in this array).
791
792 @item EXP_CHARS
793 @cindex EXP_CHARS
794 This is a null terminated @code{const char} array of characters which may be
795 used as the exponent character in a floating point number. This is normally
796 @code{"eE"}.
797
798 @item FLT_CHARS
799 @cindex FLT_CHARS
800 This is a null terminated @code{const char} array of characters which may be
801 used to indicate a floating point constant. A zero followed by one of these
802 characters is assumed to be followed by a floating point number; thus they
803 operate the way that @code{0x} is used to indicate a hexadecimal constant.
804 Usually this includes @samp{r} and @samp{f}.
805
806 @item LEX_AT
807 @cindex LEX_AT
808 You may define this macro to the lexical type of the @kbd{@}} character. The
809 default is zero.
810
811 Lexical types are a combination of @code{LEX_NAME} and @code{LEX_BEGIN_NAME},
812 both defined in @file{read.h}. @code{LEX_NAME} indicates that the character
813 may appear in a name. @code{LEX_BEGIN_NAME} indicates that the character may
814 appear at the beginning of a nem.
815
816 @item LEX_BR
817 @cindex LEX_BR
818 You may define this macro to the lexical type of the brace characters @kbd{@{},
819 @kbd{@}}, @kbd{[}, and @kbd{]}. The default value is zero.
820
821 @item LEX_PCT
822 @cindex LEX_PCT
823 You may define this macro to the lexical type of the @kbd{%} character. The
824 default value is zero.
825
826 @item LEX_QM
827 @cindex LEX_QM
828 You may define this macro to the lexical type of the @kbd{?} character. The
829 default value it zero.
830
831 @item LEX_DOLLAR
832 @cindex LEX_DOLLAR
833 You may define this macro to the lexical type of the @kbd{$} character. The
834 default value is @code{LEX_NAME | LEX_BEGIN_NAME}.
835
836 @item SINGLE_QUOTE_STRINGS
837 @cindex SINGLE_QUOTE_STRINGS
838 If you define this macro, GAS will treat single quotes as string delimiters.
839 Normally only double quotes are accepted as string delimiters.
840
841 @item NO_STRING_ESCAPES
842 @cindex NO_STRING_ESCAPES
843 If you define this macro, GAS will not permit escape sequences in a string.
844
845 @item ONLY_STANDARD_ESCAPES
846 @cindex ONLY_STANDARD_ESCAPES
847 If you define this macro, GAS will warn about the use of nonstandard escape
848 sequences in a string.
849
850 @item md_start_line_hook
851 @cindex md_start_line_hook
852 If you define this macro, GAS will call it at the start of each line.
853
854 @item LABELS_WITHOUT_COLONS
855 @cindex LABELS_WITHOUT_COLONS
856 If you define this macro, GAS will assume that any text at the start of a line
857 is a label, even if it does not have a colon.
858
859 @item TC_START_LABEL
860 @cindex TC_START_LABEL
861 You may define this macro to control what GAS considers to be a label. The
862 default definition is to accept any name followed by a colon character.
863
864 @item NO_PSEUDO_DOT
865 @cindex NO_PSEUDO_DOT
866 If you define this macro, GAS will not require pseudo-ops to start with a
867 @kbd{.} character.
868
869 @item TC_EQUAL_IN_INSN
870 @cindex TC_EQUAL_IN_INSN
871 If you define this macro, it should return nonzero if the instruction is
872 permitted to contain an @kbd{=} character. GAS will use this to decide if a
873 @kbd{=} is an assignment or an instruction.
874
875 @item TC_EOL_IN_INSN
876 @cindex TC_EOL_IN_INSN
877 If you define this macro, it should return nonzero if the current input line
878 pointer should be treated as the end of a line.
879
880 @item md_parse_name
881 @cindex md_parse_name
882 If this macro is defined, GAS will call it for any symbol found in an
883 expression. You can define this to handle special symbols in a special way.
884 If a symbol always has a certain value, you should normally enter it in the
885 symbol table, perhaps using @code{reg_section}.
886
887 @item md_undefined_symbol
888 @cindex md_undefined_symbol
889 GAS will call this function when a symbol table lookup fails, before it
890 creates a new symbol. Typically this would be used to supply symbols whose
891 name or value changes dynamically, possibly in a context sensitive way.
892 Predefined symbols with fixed values, such as register names or condition
893 codes, are typically entered directly into the symbol table when @code{md_begin}
894 is called.
895
896 @item md_operand
897 @cindex md_operand
898 GAS will call this function for any expression that can not be recognized.
899 When the function is called, @code{input_line_pointer} will point to the start
900 of the expression.
901
902 @item tc_unrecognized_line
903 @cindex tc_unrecognized_line
904 If you define this macro, GAS will call it when it finds a line that it can not
905 parse.
906
907 @item md_do_align
908 @cindex md_do_align
909 You may define this macro to handle an alignment directive. GAS will call it
910 when the directive is seen in the input file. For example, the i386 backend
911 uses this to generate efficient nop instructions of varying lengths, depending
912 upon the number of bytes that the alignment will skip.
913
914 @item HANDLE_ALIGN
915 @cindex HANDLE_ALIGN
916 You may define this macro to do special handling for an alignment directive.
917 GAS will call it at the end of the assembly.
918
919 @item md_flush_pending_output
920 @cindex md_flush_pending_output
921 If you define this macro, GAS will call it each time it skips any space because of a
922 space filling or alignment or data allocation pseudo-op.
923
924 @item TC_PARSE_CONS_EXPRESSION
925 @cindex TC_PARSE_CONS_EXPRESSION
926 You may define this macro to parse an expression used in a data allocation
927 pseudo-op such as @code{.word}. You can use this to recognize relocation
928 directives that may appear in such directives.
929
930 @item BITFIELD_CONS_EXPRESSION
931 @cindex BITFIELD_CONS_EXPRESSION
932 If you define this macro, GAS will recognize bitfield instructions in data
933 allocation pseudo-ops, as used on the i960.
934
935 @item REPEAT_CONS_EXPRESSION
936 @cindex REPEAT_CONS_EXPRESSION
937 If you define this macro, GAS will recognize repeat counts in data allocation
938 pseudo-ops, as used on the MIPS.
939
940 @item md_cons_align
941 @cindex md_cons_align
942 You may define this macro to do any special alignment before a data allocation
943 pseudo-op.
944
945 @item TC_CONS_FIX_NEW
946 @cindex TC_CONS_FIX_NEW
947 You may define this macro to generate a fixup for a data allocation pseudo-op.
948
949 @item TC_INIT_FIX_DATA (@var{fixp})
950 @cindex TC_INIT_FIX_DATA
951 A C statement to initialize the target specific fields of fixup @var{fixp}.
952 These fields are defined with the @code{TC_FIX_TYPE} macro.
953
954 @item TC_FIX_DATA_PRINT (@var{stream}, @var{fixp})
955 @cindex TC_FIX_DATA_PRINT
956 A C statement to output target specific debugging information for
957 fixup @var{fixp} to @var{stream}. This macro is called by @code{print_fixup}.
958
959 @item TC_FRAG_INIT (@var{fragp})
960 @cindex TC_FRAG_INIT
961 A C statement to initialize the target specific fields of frag @var{fragp}.
962 These fields are defined with the @code{TC_FRAG_TYPE} macro.
963
964 @item md_number_to_chars
965 @cindex md_number_to_chars
966 This should just call either @code{number_to_chars_bigendian} or
967 @code{number_to_chars_littleendian}, whichever is appropriate. On targets like
968 the MIPS which support options to change the endianness, which function to call
969 is a runtime decision. On other targets, @code{md_number_to_chars} can be a
970 simple macro.
971
972 @item md_reloc_size
973 @cindex md_reloc_size
974 This variable is only used in the original version of gas (not
975 @code{BFD_ASSEMBLER} and not @code{MANY_SEGMENTS}). It holds the size of a
976 relocation entry.
977
978 @item WORKING_DOT_WORD
979 @itemx md_short_jump_size
980 @itemx md_long_jump_size
981 @itemx md_create_short_jump
982 @itemx md_create_long_jump
983 @cindex WORKING_DOT_WORD
984 @cindex md_short_jump_size
985 @cindex md_long_jump_size
986 @cindex md_create_short_jump
987 @cindex md_create_long_jump
988 If @code{WORKING_DOT_WORD} is defined, GAS will not do broken word processing
989 (@pxref{Broken words}). Otherwise, you should set @code{md_short_jump_size} to
990 the size of a short jump (a jump that is just long enough to jump around a long
991 jmp) and @code{md_long_jump_size} to the size of a long jump (a jump that can
992 go anywhere in the function), You should define @code{md_create_short_jump} to
993 create a short jump around a long jump, and define @code{md_create_long_jump}
994 to create a long jump.
995
996 @item md_estimate_size_before_relax
997 @cindex md_estimate_size_before_relax
998 This function returns an estimate of the size of a @code{rs_machine_dependent}
999 frag before any relaxing is done. It may also create any necessary
1000 relocations.
1001
1002 @item md_relax_frag
1003 @cindex md_relax_frag
1004 This macro may be defined to relax a frag. GAS will call this with the frag
1005 and the change in size of all previous frags; @code{md_relax_frag} should
1006 return the change in size of the frag. @xref{Relaxation}.
1007
1008 @item TC_GENERIC_RELAX_TABLE
1009 @cindex TC_GENERIC_RELAX_TABLE
1010 If you do not define @code{md_relax_frag}, you may define
1011 @code{TC_GENERIC_RELAX_TABLE} as a table of @code{relax_typeS} structures. The
1012 machine independent code knows how to use such a table to relax PC relative
1013 references. See @file{tc-m68k.c} for an example. @xref{Relaxation}.
1014
1015 @item md_prepare_relax_scan
1016 @cindex md_prepare_relax_scan
1017 If defined, it is a C statement that is invoked prior to scanning
1018 the relax table.
1019
1020 @item LINKER_RELAXING_SHRINKS_ONLY
1021 @cindex LINKER_RELAXING_SHRINKS_ONLY
1022 If you define this macro, and the global variable @samp{linkrelax} is set
1023 (because of a command line option, or unconditionally in @code{md_begin}), a
1024 @samp{.align} directive will cause extra space to be allocated. The linker can
1025 then discard this space when relaxing the section.
1026
1027 @item md_convert_frag
1028 @cindex md_convert_frag
1029 GAS will call this for each rs_machine_dependent fragment.
1030 The instruction is completed using the data from the relaxation pass.
1031 It may also create any necessary relocations.
1032 @xref{Relaxation}.
1033
1034 @item md_apply_fix
1035 @cindex md_apply_fix
1036 GAS will call this for each fixup. It should store the correct value in the
1037 object file. @code{fixup_segment} performs a generic overflow check on the
1038 @code{valueT *val} argument after @code{md_apply_fix} returns. If the overflow
1039 check is relevant for the target machine, then @code{md_apply_fix} should
1040 modify @code{valueT *val}, typically to the value stored in the object file.
1041
1042 @item TC_HANDLES_FX_DONE
1043 @cindex TC_HANDLES_FX_DONE
1044 If this macro is defined, it means that @code{md_apply_fix} correctly sets the
1045 @code{fx_done} field in the fixup.
1046
1047 @item tc_gen_reloc
1048 @cindex tc_gen_reloc
1049 A @code{BFD_ASSEMBLER} GAS will call this to generate a reloc. GAS will pass
1050 the resulting reloc to @code{bfd_install_relocation}. This currently works
1051 poorly, as @code{bfd_install_relocation} often does the wrong thing, and
1052 instances of @code{tc_gen_reloc} have been written to work around the problems,
1053 which in turns makes it difficult to fix @code{bfd_install_relocation}.
1054
1055 @item RELOC_EXPANSION_POSSIBLE
1056 @cindex RELOC_EXPANSION_POSSIBLE
1057 If you define this macro, it means that @code{tc_gen_reloc} may return multiple
1058 relocation entries for a single fixup. In this case, the return value of
1059 @code{tc_gen_reloc} is a pointer to a null terminated array.
1060
1061 @item MAX_RELOC_EXPANSION
1062 @cindex MAX_RELOC_EXPANSION
1063 You must define this if @code{RELOC_EXPANSION_POSSIBLE} is defined; it
1064 indicates the largest number of relocs which @code{tc_gen_reloc} may return for
1065 a single fixup.
1066
1067 @item tc_fix_adjustable
1068 @cindex tc_fix_adjustable
1069 You may define this macro to indicate whether a fixup against a locally defined
1070 symbol should be adjusted to be against the section symbol. It should return a
1071 non-zero value if the adjustment is acceptable.
1072
1073 @item MD_PCREL_FROM_SECTION
1074 @cindex MD_PCREL_FROM_SECTION
1075 If you define this macro, it should return the offset between the address of a
1076 PC relative fixup and the position from which the PC relative adjustment should
1077 be made. On many processors, the base of a PC relative instruction is the next
1078 instruction, so this macro would return the length of an instruction.
1079
1080 @item md_pcrel_from
1081 @cindex md_pcrel_from
1082 This is the default value of @code{MD_PCREL_FROM_SECTION}. The difference is
1083 that @code{md_pcrel_from} does not take a section argument.
1084
1085 @item tc_frob_label
1086 @cindex tc_frob_label
1087 If you define this macro, GAS will call it each time a label is defined.
1088
1089 @item md_section_align
1090 @cindex md_section_align
1091 GAS will call this function for each section at the end of the assembly, to
1092 permit the CPU backend to adjust the alignment of a section.
1093
1094 @item tc_frob_section
1095 @cindex tc_frob_section
1096 If you define this macro, a @code{BFD_ASSEMBLER} GAS will call it for each
1097 section at the end of the assembly.
1098
1099 @item tc_frob_file_before_adjust
1100 @cindex tc_frob_file_before_adjust
1101 If you define this macro, GAS will call it after the symbol values are
1102 resolved, but before the fixups have been changed from local symbols to section
1103 symbols.
1104
1105 @item tc_frob_symbol
1106 @cindex tc_frob_symbol
1107 If you define this macro, GAS will call it for each symbol. You can indicate
1108 that the symbol should not be included in the object file by definining this
1109 macro to set its second argument to a non-zero value.
1110
1111 @item tc_frob_file
1112 @cindex tc_frob_file
1113 If you define this macro, GAS will call it after the symbol table has been
1114 completed, but before the relocations have been generated.
1115
1116 @item tc_frob_file_after_relocs
1117 If you define this macro, GAS will call it after the relocs have been
1118 generated.
1119
1120 @item LISTING_HEADER
1121 A string to use on the header line of a listing. The default value is simply
1122 @code{"GAS LISTING"}.
1123
1124 @item LISTING_WORD_SIZE
1125 The number of bytes to put into a word in a listing. This affects the way the
1126 bytes are clumped together in the listing. For example, a value of 2 might
1127 print @samp{1234 5678} where a value of 1 would print @samp{12 34 56 78}. The
1128 default value is 4.
1129
1130 @item LISTING_LHS_WIDTH
1131 The number of words of data to print on the first line of a listing for a
1132 particular source line, where each word is @code{LISTING_WORD_SIZE} bytes. The
1133 default value is 1.
1134
1135 @item LISTING_LHS_WIDTH_SECOND
1136 Like @code{LISTING_LHS_WIDTH}, but applying to the second and subsequent line
1137 of the data printed for a particular source line. The default value is 1.
1138
1139 @item LISTING_LHS_CONT_LINES
1140 The maximum number of continuation lines to print in a listing for a particular
1141 source line. The default value is 4.
1142
1143 @item LISTING_RHS_WIDTH
1144 The maximum number of characters to print from one line of the input file. The
1145 default value is 100.
1146 @end table
1147
1148 @node Object format backend
1149 @subsection Writing an object format backend
1150 @cindex object format backend
1151 @cindex @file{obj-@var{fmt}}
1152
1153 As with the CPU backend, the object format backend must define a few things,
1154 and may define some other things. The interface to the object format backend
1155 is generally simpler; most of the support for an object file format consists of
1156 defining a number of pseudo-ops.
1157
1158 The object format @file{.h} file must include @file{targ-cpu.h}.
1159
1160 This section will only define the @code{BFD_ASSEMBLER} version of GAS. It is
1161 impossible to support a new object file format using any other version anyhow,
1162 as the original GAS version only supports a.out, and the @code{MANY_SEGMENTS}
1163 GAS version only supports COFF.
1164
1165 @table @code
1166 @item OBJ_@var{format}
1167 @cindex OBJ_@var{format}
1168 By convention, you should define this macro in the @file{.h} file. For
1169 example, @file{obj-elf.h} defines @code{OBJ_ELF}. You might have to use this
1170 if it is necessary to add object file format specific code to the CPU file.
1171
1172 @item obj_begin
1173 If you define this macro, GAS will call it at the start of the assembly, after
1174 the command line arguments have been parsed and all the machine independent
1175 initializations have been completed.
1176
1177 @item obj_app_file
1178 @cindex obj_app_file
1179 If you define this macro, GAS will invoke it when it sees a @code{.file}
1180 pseudo-op or a @samp{#} line as used by the C preprocessor.
1181
1182 @item OBJ_COPY_SYMBOL_ATTRIBUTES
1183 @cindex OBJ_COPY_SYMBOL_ATTRIBUTES
1184 You should define this macro to copy object format specific information from
1185 one symbol to another. GAS will call it when one symbol is equated to
1186 another.
1187
1188 @item obj_fix_adjustable
1189 @cindex obj_fix_adjustable
1190 You may define this macro to indicate whether a fixup against a locally defined
1191 symbol should be adjusted to be against the section symbol. It should return a
1192 non-zero value if the adjustment is acceptable.
1193
1194 @item obj_sec_sym_ok_for_reloc
1195 @cindex obj_sec_sym_ok_for_reloc
1196 You may define this macro to indicate that it is OK to use a section symbol in
1197 a relocateion entry. If it is not, GAS will define a new symbol at the start
1198 of a section.
1199
1200 @item EMIT_SECTION_SYMBOLS
1201 @cindex EMIT_SECTION_SYMBOLS
1202 You should define this macro with a zero value if you do not want to include
1203 section symbols in the output symbol table. The default value for this macro
1204 is one.
1205
1206 @item obj_adjust_symtab
1207 @cindex obj_adjust_symtab
1208 If you define this macro, GAS will invoke it just before setting the symbol
1209 table of the output BFD. For example, the COFF support uses this macro to
1210 generate a @code{.file} symbol if none was generated previously.
1211
1212 @item SEPARATE_STAB_SECTIONS
1213 @cindex SEPARATE_STAB_SECTIONS
1214 You may define this macro to indicate that stabs should be placed in separate
1215 sections, as in ELF.
1216
1217 @item INIT_STAB_SECTION
1218 @cindex INIT_STAB_SECTION
1219 You may define this macro to initialize the stabs section in the output file.
1220
1221 @item OBJ_PROCESS_STAB
1222 @cindex OBJ_PROCESS_STAB
1223 You may define this macro to do specific processing on a stabs entry.
1224
1225 @item obj_frob_section
1226 @cindex obj_frob_section
1227 If you define this macro, GAS will call it for each section at the end of the
1228 assembly.
1229
1230 @item obj_frob_file_before_adjust
1231 @cindex obj_frob_file_before_adjust
1232 If you define this macro, GAS will call it after the symbol values are
1233 resolved, but before the fixups have been changed from local symbols to section
1234 symbols.
1235
1236 @item obj_frob_symbol
1237 @cindex obj_frob_symbol
1238 If you define this macro, GAS will call it for each symbol. You can indicate
1239 that the symbol should not be included in the object file by definining this
1240 macro to set its second argument to a non-zero value.
1241
1242 @item obj_frob_file
1243 @cindex obj_frob_file
1244 If you define this macro, GAS will call it after the symbol table has been
1245 completed, but before the relocations have been generated.
1246
1247 @item obj_frob_file_after_relocs
1248 If you define this macro, GAS will call it after the relocs have been
1249 generated.
1250 @end table
1251
1252 @node Emulations
1253 @subsection Writing emulation files
1254
1255 Normally you do not have to write an emulation file. You can just use
1256 @file{te-generic.h}.
1257
1258 If you do write your own emulation file, it must include @file{obj-format.h}.
1259
1260 An emulation file will often define @code{TE_@var{EM}}; this may then be used
1261 in other files to change the output.
1262
1263 @node Relaxation
1264 @section Relaxation
1265 @cindex relaxation
1266
1267 @dfn{Relaxation} is a generic term used when the size of some instruction or
1268 data depends upon the value of some symbol or other data.
1269
1270 GAS knows to relax a particular type of PC relative relocation using a table.
1271 You can also define arbitrarily complex forms of relaxation yourself.
1272
1273 @menu
1274 * Relaxing with a table:: Relaxing with a table
1275 * General relaxing:: General relaxing
1276 @end menu
1277
1278 @node Relaxing with a table
1279 @subsection Relaxing with a table
1280
1281 If you do not define @code{md_relax_frag}, and you do define
1282 @code{TC_GENERIC_RELAX_TABLE}, GAS will relax @code{rs_machine_dependent} frags
1283 based on the frag subtype and the displacement to some specified target
1284 address. The basic idea is that several machines have different addressing
1285 modes for instructions that can specify different ranges of values, with
1286 successive modes able to access wider ranges, including the entirety of the
1287 previous range. Smaller ranges are assumed to be more desirable (perhaps the
1288 instruction requires one word instead of two or three); if this is not the
1289 case, don't describe the smaller-range, inferior mode.
1290
1291 The @code{fr_subtype} field of a frag is an index into a CPU-specific
1292 relaxation table. That table entry indicates the range of values that can be
1293 stored, the number of bytes that will have to be added to the frag to
1294 accomodate the addressing mode, and the index of the next entry to examine if
1295 the value to be stored is outside the range accessible by the current
1296 addressing mode. The @code{fr_symbol} field of the frag indicates what symbol
1297 is to be accessed; the @code{fr_offset} field is added in.
1298
1299 If the @code{TC_PCREL_ADJUST} macro is defined, which currently should only happen
1300 for the NS32k family, the @code{TC_PCREL_ADJUST} macro is called on the frag to
1301 compute an adjustment to be made to the displacement.
1302
1303 The value fitted by the relaxation code is always assumed to be a displacement
1304 from the current frag. (More specifically, from @code{fr_fix} bytes into the
1305 frag.)
1306 @ignore
1307 This seems kinda silly. What about fitting small absolute values? I suppose
1308 @code{md_assemble} is supposed to take care of that, but if the operand is a
1309 difference between symbols, it might not be able to, if the difference was not
1310 computable yet.
1311 @end ignore
1312
1313 The end of the relaxation sequence is indicated by a ``next'' value of 0. This
1314 means that the first entry in the table can't be used.
1315
1316 For some configurations, the linker can do relaxing within a section of an
1317 object file. If call instructions of various sizes exist, the linker can
1318 determine which should be used in each instance, when a symbol's value is
1319 resolved. In order for the linker to avoid wasting space and having to insert
1320 no-op instructions, it must be able to expand or shrink the section contents
1321 while still preserving intra-section references and meeting alignment
1322 requirements.
1323
1324 For the i960 using b.out format, no expansion is done; instead, each
1325 @samp{.align} directive causes extra space to be allocated, enough that when
1326 the linker is relaxing a section and removing unneeded space, it can discard
1327 some or all of this extra padding and cause the following data to be correctly
1328 aligned.
1329
1330 For the H8/300, I think the linker expands calls that can't reach, and doesn't
1331 worry about alignment issues; the cpu probably never needs any significant
1332 alignment beyond the instruction size.
1333
1334 The relaxation table type contains these fields:
1335
1336 @table @code
1337 @item long rlx_forward
1338 Forward reach, must be non-negative.
1339 @item long rlx_backward
1340 Backward reach, must be zero or negative.
1341 @item rlx_length
1342 Length in bytes of this addressing mode.
1343 @item rlx_more
1344 Index of the next-longer relax state, or zero if there is no next relax state.
1345 @end table
1346
1347 The relaxation is done in @code{relax_segment} in @file{write.c}. The
1348 difference in the length fields between the original mode and the one finally
1349 chosen by the relaxing code is taken as the size by which the current frag will
1350 be increased in size. For example, if the initial relaxing mode has a length
1351 of 2 bytes, and because of the size of the displacement, it gets upgraded to a
1352 mode with a size of 6 bytes, it is assumed that the frag will grow by 4 bytes.
1353 (The initial two bytes should have been part of the fixed portion of the frag,
1354 since it is already known that they will be output.) This growth must be
1355 effected by @code{md_convert_frag}; it should increase the @code{fr_fix} field
1356 by the appropriate size, and fill in the appropriate bytes of the frag.
1357 (Enough space for the maximum growth should have been allocated in the call to
1358 frag_var as the second argument.)
1359
1360 If relocation records are needed, they should be emitted by
1361 @code{md_estimate_size_before_relax}. This function should examine the target
1362 symbol of the supplied frag and correct the @code{fr_subtype} of the frag if
1363 needed. When this function is called, if the symbol has not yet been defined,
1364 it will not become defined later; however, its value may still change if the
1365 section it is in gets relaxed.
1366
1367 Usually, if the symbol is in the same section as the frag (given by the
1368 @var{sec} argument), the narrowest likely relaxation mode is stored in
1369 @code{fr_subtype}, and that's that.
1370
1371 If the symbol is undefined, or in a different section (and therefore moveable
1372 to an arbitrarily large distance), the largest available relaxation mode is
1373 specified, @code{fix_new} is called to produce the relocation record,
1374 @code{fr_fix} is increased to include the relocated field (remember, this
1375 storage was allocated when @code{frag_var} was called), and @code{frag_wane} is
1376 called to convert the frag to an @code{rs_fill} frag with no variant part.
1377 Sometimes changing addressing modes may also require rewriting the instruction.
1378 It can be accessed via @code{fr_opcode} or @code{fr_fix}.
1379
1380 Sometimes @code{fr_var} is increased instead, and @code{frag_wane} is not
1381 called. I'm not sure, but I think this is to keep @code{fr_fix} referring to
1382 an earlier byte, and @code{fr_subtype} set to @code{rs_machine_dependent} so
1383 that @code{md_convert_frag} will get called.
1384
1385 @node General relaxing
1386 @subsection General relaxing
1387
1388 If using a simple table is not suitable, you may implement arbitrarily complex
1389 relaxation semantics yourself. For example, the MIPS backend uses this to emit
1390 different instruction sequences depending upon the size of the symbol being
1391 accessed.
1392
1393 When you assemble an instruction that may need relaxation, you should allocate
1394 a frag using @code{frag_var} or @code{frag_variant} with a type of
1395 @code{rs_machine_dependent}. You should store some sort of information in the
1396 @code{fr_subtype} field so that you can figure out what to do with the frag
1397 later.
1398
1399 When GAS reaches the end of the input file, it will look through the frags and
1400 work out their final sizes.
1401
1402 GAS will first call @code{md_estimate_size_before_relax} on each
1403 @code{rs_machine_dependent} frag. This function must return an estimated size
1404 for the frag.
1405
1406 GAS will then loop over the frags, calling @code{md_relax_frag} on each
1407 @code{rs_machine_dependent} frag. This function should return the change in
1408 size of the frag. GAS will keep looping over the frags until none of the frags
1409 changes size.
1410
1411 @node Broken words
1412 @section Broken words
1413 @cindex internals, broken words
1414 @cindex broken words
1415
1416 Some compilers, including GCC, will sometimes emit switch tables specifying
1417 16-bit @code{.word} displacements to branch targets, and branch instructions
1418 that load entries from that table to compute the target address. If this is
1419 done on a 32-bit machine, there is a chance (at least with really large
1420 functions) that the displacement will not fit in 16 bits. The assembler
1421 handles this using a concept called @dfn{broken words}. This idea is well
1422 named, since there is an implied promise that the 16-bit field will in fact
1423 hold the specified displacement.
1424
1425 If broken word processing is enabled, and a situation like this is encountered,
1426 the assembler will insert a jump instruction into the instruction stream, close
1427 enough to be reached with the 16-bit displacement. This jump instruction will
1428 transfer to the real desired target address. Thus, as long as the @code{.word}
1429 value really is used as a displacement to compute an address to jump to, the
1430 net effect will be correct (minus a very small efficiency cost). If
1431 @code{.word} directives with label differences for values are used for other
1432 purposes, however, things may not work properly. For targets which use broken
1433 words, the @samp{-K} option will warn when a broken word is discovered.
1434
1435 The broken word code is turned off by the @code{WORKING_DOT_WORD} macro. It
1436 isn't needed if @code{.word} emits a value large enough to contain an address
1437 (or, more correctly, any possible difference between two addresses).
1438
1439 @node Internal functions
1440 @section Internal functions
1441
1442 This section describes basic internal functions used by GAS.
1443
1444 @menu
1445 * Warning and error messages:: Warning and error messages
1446 * Hash tables:: Hash tables
1447 @end menu
1448
1449 @node Warning and error messages
1450 @subsection Warning and error messages
1451
1452 @deftypefun @{@} int had_warnings (void)
1453 @deftypefunx @{@} int had_errors (void)
1454 Returns non-zero if any warnings or errors, respectively, have been printed
1455 during this invocation.
1456 @end deftypefun
1457
1458 @deftypefun @{@} void as_perror (const char *@var{gripe}, const char *@var{filename})
1459 Displays a BFD or system error, then clears the error status.
1460 @end deftypefun
1461
1462 @deftypefun @{@} void as_tsktsk (const char *@var{format}, ...)
1463 @deftypefunx @{@} void as_warn (const char *@var{format}, ...)
1464 @deftypefunx @{@} void as_bad (const char *@var{format}, ...)
1465 @deftypefunx @{@} void as_fatal (const char *@var{format}, ...)
1466 These functions display messages about something amiss with the input file, or
1467 internal problems in the assembler itself. The current file name and line
1468 number are printed, followed by the supplied message, formatted using
1469 @code{vfprintf}, and a final newline.
1470
1471 An error indicated by @code{as_bad} will result in a non-zero exit status when
1472 the assembler has finished. Calling @code{as_fatal} will result in immediate
1473 termination of the assembler process.
1474 @end deftypefun
1475
1476 @deftypefun @{@} void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
1477 @deftypefunx @{@} void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
1478 These variants permit specification of the file name and line number, and are
1479 used when problems are detected when reprocessing information saved away when
1480 processing some earlier part of the file. For example, fixups are processed
1481 after all input has been read, but messages about fixups should refer to the
1482 original filename and line number that they are applicable to.
1483 @end deftypefun
1484
1485 @deftypefun @{@} void fprint_value (FILE *@var{file}, valueT @var{val})
1486 @deftypefunx @{@} void sprint_value (char *@var{buf}, valueT @var{val})
1487 These functions are helpful for converting a @code{valueT} value into printable
1488 format, in case it's wider than modes that @code{*printf} can handle. If the
1489 type is narrow enough, a decimal number will be produced; otherwise, it will be
1490 in hexadecimal. The value itself is not examined to make this determination.
1491 @end deftypefun
1492
1493 @node Hash tables
1494 @subsection Hash tables
1495 @cindex hash tables
1496
1497 @deftypefun @{@} @{struct hash_control *@} hash_new (void)
1498 Creates the hash table control structure.
1499 @end deftypefun
1500
1501 @deftypefun @{@} void hash_die (struct hash_control *)
1502 Destroy a hash table.
1503 @end deftypefun
1504
1505 @deftypefun @{@} PTR hash_delete (struct hash_control *, const char *)
1506 Deletes entry from the hash table, returns the value it had.
1507 @end deftypefun
1508
1509 @deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR)
1510 Updates the value for an entry already in the table, returning the old value.
1511 If no entry was found, just returns NULL.
1512 @end deftypefun
1513
1514 @deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR)
1515 Inserting a value already in the table is an error.
1516 Returns an error message or NULL.
1517 @end deftypefun
1518
1519 @deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR)
1520 Inserts if the value isn't already present, updates it if it is.
1521 @end deftypefun
1522
1523 @node Test suite
1524 @section Test suite
1525 @cindex test suite
1526
1527 The test suite is kind of lame for most processors. Often it only checks to
1528 see if a couple of files can be assembled without the assembler reporting any
1529 errors. For more complete testing, write a test which either examines the
1530 assembler listing, or runs @code{objdump} and examines its output. For the
1531 latter, the TCL procedure @code{run_dump_test} may come in handy. It takes the
1532 base name of a file, and looks for @file{@var{file}.d}. This file should
1533 contain as its initial lines a set of variable settings in @samp{#} comments,
1534 in the form:
1535
1536 @example
1537 #@var{varname}: @var{value}
1538 @end example
1539
1540 The @var{varname} may be @code{objdump}, @code{nm}, or @code{as}, in which case
1541 it specifies the options to be passed to the specified programs. Exactly one
1542 of @code{objdump} or @code{nm} must be specified, as that also specifies which
1543 program to run after the assembler has finished. If @var{varname} is
1544 @code{source}, it specifies the name of the source file; otherwise,
1545 @file{@var{file}.s} is used. If @var{varname} is @code{name}, it specifies the
1546 name of the test to be used in the @code{pass} or @code{fail} messages.
1547
1548 The non-commented parts of the file are interpreted as regular expressions, one
1549 per line. Blank lines in the @code{objdump} or @code{nm} output are skipped,
1550 as are blank lines in the @code{.d} file; the other lines are tested to see if
1551 the regular expression matches the program output. If it does not, the test
1552 fails.
1553
1554 Note that this means the tests must be modified if the @code{objdump} output
1555 style is changed.
1556
1557 @bye
1558 @c Local Variables:
1559 @c fill-column: 79
1560 @c End:
This page took 0.059814 seconds and 3 git commands to generate.