2 @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
3 @c 2001, 2002, 2003, 2004, 2005
4 @c Free Software Foundation, Inc.
5 @setfilename internals.info
7 @top Assembler Internals
11 This chapter describes the internals of the assembler. It is incomplete, but
14 This chapter is not updated regularly, and it may be out of date.
17 * Data types:: Data types
18 * GAS processing:: What GAS does when it runs
19 * Porting GAS:: Porting GAS
20 * Relaxation:: Relaxation
21 * Broken words:: Broken words
22 * Internal functions:: Internal functions
23 * Test suite:: Test suite
28 @cindex internals, data types
30 This section describes some fundamental GAS data types.
33 * Symbols:: The symbolS structure
34 * Expressions:: The expressionS structure
35 * Fixups:: The fixS structure
36 * Frags:: The fragS structure
41 @cindex internals, symbols
42 @cindex symbols, internal
43 @cindex symbolS structure
45 The definition for the symbol structure, @code{symbolS}, is located in
46 @file{struc-symbol.h}.
48 In general, the fields of this structure may not be referred to directly.
49 Instead, you must use one of the accessor functions defined in @file{symbol.h}.
50 These accessor functions should work for any GAS version.
52 Symbol structures contain the following fields:
56 This is an @code{expressionS} that describes the value of the symbol. It might
57 refer to one or more other symbols; if so, its true value may not be known
58 until @code{resolve_symbol_value} is called with @var{finalize_syms} non-zero
59 in @code{write_object_file}.
61 The expression is often simply a constant. Before @code{resolve_symbol_value}
62 is called with @var{finalize_syms} set, the value is the offset from the frag
63 (@pxref{Frags}). Afterward, the frag address has been added in.
66 This field is non-zero if the symbol's value has been completely resolved. It
67 is used during the final pass over the symbol table.
70 This field is used to detect loops while resolving the symbol's value.
72 @item sy_used_in_reloc
73 This field is non-zero if the symbol is used by a relocation entry. If a local
74 symbol is used in a relocation entry, it must be possible to redirect those
75 relocations to other symbols, or this symbol cannot be removed from the final
80 These pointers to other @code{symbolS} structures describe a doubly
81 linked list. These fields should be accessed with
82 the @code{symbol_next} and @code{symbol_previous} macros.
85 This points to the frag (@pxref{Frags}) that this symbol is attached to.
88 Whether the symbol is used as an operand or in an expression. Note: Not all of
89 the backends keep this information accurate; backends which use this bit are
90 responsible for setting it when a symbol is used in backend routines.
93 Whether the symbol is an MRI common symbol created by the @code{COMMON}
94 pseudo-op when assembling in MRI mode.
97 This points to the BFD @code{asymbol} that
98 will be used in writing the object file.
101 This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by
102 that name is defined in @file{obj-format.h}, this field is not defined.
105 This processor-specific data is of type @code{TC_SYMFIELD_TYPE}. If no macro
106 by that name is defined in @file{targ-cpu.h}, this field is not defined.
110 Here is a description of the accessor functions. These should be used rather
111 than referring to the fields of @code{symbolS} directly.
116 Set the symbol's value.
120 Get the symbol's value. This will cause @code{resolve_symbol_value} to be
124 @cindex S_SET_SEGMENT
125 Set the section of the symbol.
128 @cindex S_GET_SEGMENT
129 Get the symbol's section.
133 Get the name of the symbol.
137 Set the name of the symbol.
140 @cindex S_IS_EXTERNAL
141 Return non-zero if the symbol is externally visible.
145 A synonym for @code{S_IS_EXTERNAL}. Don't use it.
149 Return non-zero if the symbol is weak.
153 Return non-zero if this is a common symbol. Common symbols are sometimes
154 represented as undefined symbols with a value, in which case this function will
159 Return non-zero if this symbol is defined. This function is not reliable when
160 called on a common symbol.
164 Return non-zero if this is a debugging symbol.
168 Return non-zero if this is a local assembler symbol which should not be
169 included in the final symbol table. Note that this is not the opposite of
170 @code{S_IS_EXTERNAL}. The @samp{-L} assembler option affects the return value
174 @cindex S_SET_EXTERNAL
175 Mark the symbol as externally visible.
177 @item S_CLEAR_EXTERNAL
178 @cindex S_CLEAR_EXTERNAL
179 Mark the symbol as not externally visible.
183 Mark the symbol as weak.
191 Get the @code{type}, @code{desc}, and @code{other} fields of the symbol. These
192 are only defined for object file formats for which they make sense (primarily
201 Set the @code{type}, @code{desc}, and @code{other} fields of the symbol. These
202 are only defined for object file formats for which they make sense (primarily
207 Get the size of a symbol. This is only defined for object file formats for
208 which it makes sense (primarily ELF).
212 Set the size of a symbol. This is only defined for object file formats for
213 which it makes sense (primarily ELF).
215 @item symbol_get_value_expression
216 @cindex symbol_get_value_expression
217 Get a pointer to an @code{expressionS} structure which represents the value of
218 the symbol as an expression.
220 @item symbol_set_value_expression
221 @cindex symbol_set_value_expression
222 Set the value of a symbol to an expression.
224 @item symbol_set_frag
225 @cindex symbol_set_frag
226 Set the frag where a symbol is defined.
228 @item symbol_get_frag
229 @cindex symbol_get_frag
230 Get the frag where a symbol is defined.
232 @item symbol_mark_used
233 @cindex symbol_mark_used
234 Mark a symbol as having been used in an expression.
236 @item symbol_clear_used
237 @cindex symbol_clear_used
238 Clear the mark indicating that a symbol was used in an expression.
241 @cindex symbol_used_p
242 Return whether a symbol was used in an expression.
244 @item symbol_mark_used_in_reloc
245 @cindex symbol_mark_used_in_reloc
246 Mark a symbol as having been used by a relocation.
248 @item symbol_clear_used_in_reloc
249 @cindex symbol_clear_used_in_reloc
250 Clear the mark indicating that a symbol was used in a relocation.
252 @item symbol_used_in_reloc_p
253 @cindex symbol_used_in_reloc_p
254 Return whether a symbol was used in a relocation.
256 @item symbol_mark_mri_common
257 @cindex symbol_mark_mri_common
258 Mark a symbol as an MRI common symbol.
260 @item symbol_clear_mri_common
261 @cindex symbol_clear_mri_common
262 Clear the mark indicating that a symbol is an MRI common symbol.
264 @item symbol_mri_common_p
265 @cindex symbol_mri_common_p
266 Return whether a symbol is an MRI common symbol.
268 @item symbol_mark_written
269 @cindex symbol_mark_written
270 Mark a symbol as having been written.
272 @item symbol_clear_written
273 @cindex symbol_clear_written
274 Clear the mark indicating that a symbol was written.
276 @item symbol_written_p
277 @cindex symbol_written_p
278 Return whether a symbol was written.
280 @item symbol_mark_resolved
281 @cindex symbol_mark_resolved
282 Mark a symbol as having been resolved.
284 @item symbol_resolved_p
285 @cindex symbol_resolved_p
286 Return whether a symbol has been resolved.
288 @item symbol_section_p
289 @cindex symbol_section_p
290 Return whether a symbol is a section symbol.
292 @item symbol_equated_p
293 @cindex symbol_equated_p
294 Return whether a symbol is equated to another symbol.
296 @item symbol_constant_p
297 @cindex symbol_constant_p
298 Return whether a symbol has a constant value, including being an offset within
301 @item symbol_get_bfdsym
302 @cindex symbol_get_bfdsym
303 Return the BFD symbol associated with a symbol.
305 @item symbol_set_bfdsym
306 @cindex symbol_set_bfdsym
307 Set the BFD symbol associated with a symbol.
310 @cindex symbol_get_obj
311 Return a pointer to the @code{OBJ_SYMFIELD_TYPE} field of a symbol.
314 @cindex symbol_set_obj
315 Set the @code{OBJ_SYMFIELD_TYPE} field of a symbol.
318 @cindex symbol_get_tc
319 Return a pointer to the @code{TC_SYMFIELD_TYPE} field of a symbol.
322 @cindex symbol_set_tc
323 Set the @code{TC_SYMFIELD_TYPE} field of a symbol.
327 GAS attempts to store local
328 symbols--symbols which will not be written to the output file--using a
329 different structure, @code{struct local_symbol}. This structure can only
330 represent symbols whose value is an offset within a frag.
332 Code outside of the symbol handler will always deal with @code{symbolS}
333 structures and use the accessor functions. The accessor functions correctly
334 deal with local symbols. @code{struct local_symbol} is much smaller than
335 @code{symbolS} (which also automatically creates a bfd @code{asymbol}
336 structure), so this saves space when assembling large files.
338 The first field of @code{symbolS} is @code{bsym}, the pointer to the BFD
339 symbol. The first field of @code{struct local_symbol} is a pointer which is
340 always set to NULL. This is how the symbol accessor functions can distinguish
341 local symbols from ordinary symbols. The symbol accessor functions
342 automatically convert a local symbol into an ordinary symbol when necessary.
345 @subsection Expressions
346 @cindex internals, expressions
347 @cindex expressions, internal
348 @cindex expressionS structure
350 Expressions are stored in an @code{expressionS} structure. The structure is
351 defined in @file{expr.h}.
354 The macro @code{expression} will create an @code{expressionS} structure based
355 on the text found at the global variable @code{input_line_pointer}.
357 @cindex make_expr_symbol
358 @cindex expr_symbol_where
359 A single @code{expressionS} structure can represent a single operation.
360 Complex expressions are formed by creating @dfn{expression symbols} and
361 combining them in @code{expressionS} structures. An expression symbol is
362 created by calling @code{make_expr_symbol}. An expression symbol should
363 naturally never appear in a symbol table, and the implementation of
364 @code{S_IS_LOCAL} (@pxref{Symbols}) reflects that. The function
365 @code{expr_symbol_where} returns non-zero if a symbol is an expression symbol,
366 and also returns the file and line for the expression which caused it to be
369 The @code{expressionS} structure has two symbol fields, a number field, an
370 operator field, and a field indicating whether the number is unsigned.
372 The operator field is of type @code{operatorT}, and describes how to interpret
373 the other fields; see the definition in @file{expr.h} for the possibilities.
375 An @code{operatorT} value of @code{O_big} indicates either a floating point
376 number, stored in the global variable @code{generic_floating_point_number}, or
377 an integer too large to store in an @code{offsetT} type, stored in the global
378 array @code{generic_bignum}. This rather inflexible approach makes it
379 impossible to use floating point numbers or large expressions in complex
384 @cindex internals, fixups
386 @cindex fixS structure
388 A @dfn{fixup} is basically anything which can not be resolved in the first
389 pass. Sometimes a fixup can be resolved by the end of the assembly; if not,
390 the fixup becomes a relocation entry in the object file.
394 A fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both
395 take a frag (@pxref{Frags}), a position within the frag, a size, an indication
396 of whether the fixup is PC relative, and a type.
397 The type is nominally a @code{bfd_reloc_code_real_type}, but several
398 targets use other type codes to represent fixups that can not be described as
401 The @code{fixS} structure has a number of fields, several of which are obsolete
402 or are only used by a particular target. The important fields are:
406 The frag (@pxref{Frags}) this fixup is in.
409 The location within the frag where the fixup occurs.
412 The symbol this fixup is against. Typically, the value of this symbol is added
413 into the object contents. This may be NULL.
416 The value of this symbol is subtracted from the object contents. This is
420 A number which is added into the fixup.
423 Some CPU backends use this field to convey information between
424 @code{md_apply_fix} and @code{tc_gen_reloc}. The machine independent code does
428 The next fixup in the section.
431 The type of the fixup.
434 The size of the fixup. This is mostly used for error checking.
437 Whether the fixup is PC relative.
440 Non-zero if the fixup has been applied, and no relocation entry needs to be
445 The file and line where the fixup was created.
448 This has the type @code{TC_FIX_TYPE}, and is only defined if the target defines
454 @cindex internals, frags
456 @cindex fragS structure.
458 The @code{fragS} structure is defined in @file{as.h}. Each frag represents a
459 portion of the final object file. As GAS reads the source file, it creates
460 frags to hold the data that it reads. At the end of the assembly the frags and
461 fixups are processed to produce the final contents.
465 The address of the frag. This is not set until the assembler rescans the list
466 of all frags after the entire input file is parsed. The function
467 @code{relax_segment} fills in this field.
470 Pointer to the next frag in this (sub)section.
473 Fixed number of characters we know we're going to emit to the output file. May
477 Variable number of characters we may output, after the initial @code{fr_fix}
478 characters. May be zero.
481 The interpretation of this field is controlled by @code{fr_type}. Generally,
482 if @code{fr_var} is non-zero, this is a repeat count: the @code{fr_var}
483 characters are output @code{fr_offset} times.
486 Holds line number info when an assembler listing was requested.
489 Relaxation state. This field indicates the interpretation of @code{fr_offset},
490 @code{fr_symbol} and the variable-length tail of the frag, as well as the
491 treatment it gets in various phases of processing. It does not affect the
492 initial @code{fr_fix} characters; they are always supposed to be output
493 verbatim (fixups aside). See below for specific values this field can have.
496 Relaxation substate. If the macro @code{md_relax_frag} isn't defined, this is
497 assumed to be an index into @code{TC_GENERIC_RELAX_TABLE} for the generic
498 relaxation code to process (@pxref{Relaxation}). If @code{md_relax_frag} is
499 defined, this field is available for any use by the CPU-specific code.
502 This normally indicates the symbol to use when relaxing the frag according to
506 Points to the lowest-addressed byte of the opcode, for use in relaxation.
509 Target specific fragment data of type TC_FRAG_TYPE.
510 Only present if @code{TC_FRAG_TYPE} is defined.
514 The file and line where this frag was last modified.
517 Declared as a one-character array, this last field grows arbitrarily large to
518 hold the actual contents of the frag.
521 These are the possible relaxation states, provided in the enumeration type
522 @code{relax_stateT}, and the interpretations they represent for the other
528 The start of the following frag should be aligned on some boundary. In this
529 frag, @code{fr_offset} is the logarithm (base 2) of the alignment in bytes.
530 (For example, if alignment on an 8-byte boundary were desired, @code{fr_offset}
531 would have a value of 3.) The variable characters indicate the fill pattern to
532 be used. The @code{fr_subtype} field holds the maximum number of bytes to skip
533 when doing this alignment. If more bytes are needed, the alignment is not
534 done. An @code{fr_subtype} value of 0 means no maximum, which is the normal
535 case. Target backends can use @code{rs_align_code} to handle certain types of
536 alignment differently.
539 This indicates that ``broken word'' processing should be done (@pxref{Broken
540 words}). If broken word processing is not necessary on the target machine,
541 this enumerator value will not be defined.
544 This state is used to implement exception frame optimizations. The
545 @code{fr_symbol} is an expression symbol for the subtraction which may be
546 relaxed. The @code{fr_opcode} field holds the frag for the preceding command
547 byte. The @code{fr_offset} field holds the offset within that frag. The
548 @code{fr_subtype} field is used during relaxation to hold the current size of
552 The variable characters are to be repeated @code{fr_offset} times. If
553 @code{fr_offset} is 0, this frag has a length of @code{fr_fix}. Most frags
557 This state is used to implement the DWARF ``little endian base 128''
558 variable length number format. The @code{fr_symbol} is always an expression
559 symbol, as constant expressions are emitted directly. The @code{fr_offset}
560 field is used during relaxation to hold the previous size of the number so
561 that we can determine if the fragment changed size.
563 @item rs_machine_dependent
564 Displacement relaxation is to be done on this frag. The target is indicated by
565 @code{fr_symbol} and @code{fr_offset}, and @code{fr_subtype} indicates the
566 particular machine-specific addressing mode desired. @xref{Relaxation}.
569 The start of the following frag should be pushed back to some specific offset
570 within the section. (Some assemblers use the value as an absolute address; GAS
571 does not handle final absolute addresses, but rather requires that the linker
572 set them.) The offset is given by @code{fr_symbol} and @code{fr_offset}; one
573 character from the variable-length tail is used as the fill character.
576 @cindex frchainS structure
577 A chain of frags is built up for each subsection. The data structure
578 describing a chain is called a @code{frchainS}, and contains the following
583 Points to the first frag in the chain. May be NULL if there are no frags in
586 Points to the last frag in the chain, or NULL if there are none.
588 Next in the list of @code{frchainS} structures.
590 Indicates the section this frag chain belongs to.
592 Subsection (subsegment) number of this frag chain.
593 @item fix_root, fix_tail
594 Point to first and last @code{fixS} structures associated with this subsection.
596 Not currently used. Intended to be used for frag allocation for this
597 subsection. This should reduce frag generation caused by switching sections.
599 The current frag for this subsegment.
602 A @code{frchainS} corresponds to a subsection; each section has a list of
603 @code{frchainS} records associated with it. In most cases, only one subsection
604 of each section is used, so the list will only be one element long, but any
605 processing of frag chains should be prepared to deal with multiple chains per
608 After the input files have been completely processed, and no more frags are to
609 be generated, the frag chains are joined into one per section for further
610 processing. After this point, it is safe to operate on one chain per section.
612 The assembler always has a current frag, named @code{frag_now}. More space is
613 allocated for the current frag using the @code{frag_more} function; this
614 returns a pointer to the amount of requested space. The function
615 @code{frag_room} says by how much the current frag can be extended.
616 Relaxing is done using variant frags allocated by @code{frag_var}
617 or @code{frag_variant} (@pxref{Relaxation}).
620 @section What GAS does when it runs
621 @cindex internals, overview
623 This is a quick look at what an assembler run looks like.
627 The assembler initializes itself by calling various init routines.
630 For each source file, the @code{read_a_source_file} function reads in the file
631 and parses it. The global variable @code{input_line_pointer} points to the
632 current text; it is guaranteed to be correct up to the end of the line, but not
636 For each line, the assembler passes labels to the @code{colon} function, and
637 isolates the first word. If it looks like a pseudo-op, the word is looked up
638 in the pseudo-op hash table @code{po_hash} and dispatched to a pseudo-op
639 routine. Otherwise, the target dependent @code{md_assemble} routine is called
640 to parse the instruction.
643 When pseudo-ops or instructions output data, they add it to a frag, calling
644 @code{frag_more} to get space to store it in.
647 Pseudo-ops and instructions can also output fixups created by @code{fix_new} or
651 For certain targets, instructions can create variant frags which are used to
652 store relaxation information (@pxref{Relaxation}).
655 When the input file is finished, the @code{write_object_file} routine is
656 called. It assigns addresses to all the frags (@code{relax_segment}), resolves
657 all the fixups (@code{fixup_segment}), resolves all the symbol values (using
658 @code{resolve_symbol_value}), and finally writes out the file.
665 Each GAS target specifies two main things: the CPU file and the object format
666 file. Two main switches in the @file{configure.in} file handle this. The
667 first switches on CPU type to set the shell variable @code{cpu_type}. The
668 second switches on the entire target to set the shell variable @code{fmt}.
670 The configure script uses the value of @code{cpu_type} to select two files in
671 the @file{config} directory: @file{tc-@var{CPU}.c} and @file{tc-@var{CPU}.h}.
672 The configuration process will create a file named @file{targ-cpu.h} in the
673 build directory which includes @file{tc-@var{CPU}.h}.
675 The configure script also uses the value of @code{fmt} to select two files:
676 @file{obj-@var{fmt}.c} and @file{obj-@var{fmt}.h}. The configuration process
677 will create a file named @file{obj-format.h} in the build directory which
678 includes @file{obj-@var{fmt}.h}.
680 You can also set the emulation in the configure script by setting the @code{em}
681 variable. Normally the default value of @samp{generic} is fine. The
682 configuration process will create a file named @file{targ-env.h} in the build
683 directory which includes @file{te-@var{em}.h}.
685 There is a special case for COFF. For historical reason, the GNU COFF
686 assembler doesn't follow the documented behavior on certain debug symbols for
687 the compatibility with other COFF assemblers. A port can define
688 @code{STRICTCOFF} in the configure script to make the GNU COFF assembler
689 to follow the documented behavior.
691 Porting GAS to a new CPU requires writing the @file{tc-@var{CPU}} files.
692 Porting GAS to a new object file format requires writing the
693 @file{obj-@var{fmt}} files. There is sometimes some interaction between these
694 two files, but it is normally minimal.
696 The best approach is, of course, to copy existing files. The documentation
697 below assumes that you are looking at existing files to see usage details.
699 These interfaces have grown over time, and have never been carefully thought
700 out or designed. Nothing about the interfaces described here is cast in stone.
701 It is possible that they will change from one version of the assembler to the
702 next. Also, new macros are added all the time as they are needed.
705 * CPU backend:: Writing a CPU backend
706 * Object format backend:: Writing an object format backend
707 * Emulations:: Writing emulation files
711 @subsection Writing a CPU backend
713 @cindex @file{tc-@var{CPU}}
715 The CPU backend files are the heart of the assembler. They are the only parts
716 of the assembler which actually know anything about the instruction set of the
719 You must define a reasonably small list of macros and functions in the CPU
720 backend files. You may define a large number of additional macros in the CPU
721 backend files, not all of which are documented here. You must, of course,
722 define macros in the @file{.h} file, which is included by every assembler
723 source file. You may define the functions as macros in the @file{.h} file, or
724 as functions in the @file{.c} file.
729 By convention, you should define this macro in the @file{.h} file. For
730 example, @file{tc-m68k.h} defines @code{TC_M68K}. You might have to use this
731 if it is necessary to add CPU specific code to the object format file.
734 This macro is the BFD target name to use when creating the output file. This
735 will normally depend upon the @code{OBJ_@var{FMT}} macro.
738 This macro is the BFD architecture to pass to @code{bfd_set_arch_mach}.
741 This macro is the BFD machine number to pass to @code{bfd_set_arch_mach}. If
742 it is not defined, GAS will use 0.
744 @item TARGET_BYTES_BIG_ENDIAN
745 You should define this macro to be non-zero if the target is big endian, and
746 zero if the target is little endian.
750 @itemx md_longopts_size
751 @itemx md_parse_option
753 @itemx md_after_parse_args
756 @cindex md_longopts_size
757 @cindex md_parse_option
758 @cindex md_show_usage
759 @cindex md_after_parse_args
760 GAS uses these variables and functions during option processing.
761 @code{md_shortopts} is a @code{const char *} which GAS adds to the machine
762 independent string passed to @code{getopt}. @code{md_longopts} is a
763 @code{struct option []} which GAS adds to the machine independent long options
764 passed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in
765 @file{as.h}, as the start of a set of long option indices, if necessary.
766 @code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}.
768 GAS will call @code{md_parse_option} whenever @code{getopt} returns an
769 unrecognized code, presumably indicating a special code value which appears in
770 @code{md_longopts}. This function should return non-zero if it handled the
771 option and zero otherwise. There is no need to print a message about an option
772 not being recognised. This will be handled by the generic code.
774 GAS will call @code{md_show_usage} when a usage message is printed; it should
775 print a description of the machine specific options. @code{md_after_pase_args},
776 if defined, is called after all options are processed, to let the backend
777 override settings done by the generic option parsing.
781 GAS will call this function at the start of the assembly, after the command
782 line arguments have been parsed and all the machine independent initializations
787 If you define this macro, GAS will call it at the end of each input file.
791 GAS will call this function for each input line which does not contain a
792 pseudo-op. The argument is a null terminated string. The function should
793 assemble the string as an instruction with operands. Normally
794 @code{md_assemble} will do this by calling @code{frag_more} and writing out
795 some bytes (@pxref{Frags}). @code{md_assemble} will call @code{fix_new} to
796 create fixups as needed (@pxref{Fixups}). Targets which need to do special
797 purpose relaxation will call @code{frag_var}.
799 @item md_pseudo_table
800 @cindex md_pseudo_table
801 This is a const array of type @code{pseudo_typeS}. It is a mapping from
802 pseudo-op names to functions. You should use this table to implement
803 pseudo-ops which are specific to the CPU.
805 @item tc_conditional_pseudoop
806 @cindex tc_conditional_pseudoop
807 If this macro is defined, GAS will call it with a @code{pseudo_typeS} argument.
808 It should return non-zero if the pseudo-op is a conditional which controls
809 whether code is assembled, such as @samp{.if}. GAS knows about the normal
810 conditional pseudo-ops, and you should normally not have to define this macro.
813 @cindex comment_chars
814 This is a null terminated @code{const char} array of characters which start a
817 @item tc_comment_chars
818 @cindex tc_comment_chars
819 If this macro is defined, GAS will use it instead of @code{comment_chars}.
821 @item tc_symbol_chars
822 @cindex tc_symbol_chars
823 If this macro is defined, it is a pointer to a null terminated list of
824 characters which may appear in an operand. GAS already assumes that all
825 alphanumberic characters, and @samp{$}, @samp{.}, and @samp{_} may appear in an
826 operand (see @samp{symbol_chars} in @file{app.c}). This macro may be defined
827 to treat additional characters as appearing in an operand. This affects the
828 way in which GAS removes whitespace before passing the string to
831 @item line_comment_chars
832 @cindex line_comment_chars
833 This is a null terminated @code{const char} array of characters which start a
834 comment when they appear at the start of a line.
836 @item line_separator_chars
837 @cindex line_separator_chars
838 This is a null terminated @code{const char} array of characters which separate
839 lines (null and newline are such characters by default, and need not be
840 listed in this array). Note that line_separator_chars do not separate lines
841 if found in a comment, such as after a character in line_comment_chars or
846 This is a null terminated @code{const char} array of characters which may be
847 used as the exponent character in a floating point number. This is normally
852 This is a null terminated @code{const char} array of characters which may be
853 used to indicate a floating point constant. A zero followed by one of these
854 characters is assumed to be followed by a floating point number; thus they
855 operate the way that @code{0x} is used to indicate a hexadecimal constant.
856 Usually this includes @samp{r} and @samp{f}.
860 You may define this macro to the lexical type of the @kbd{@@} character. The
863 Lexical types are a combination of @code{LEX_NAME} and @code{LEX_BEGIN_NAME},
864 both defined in @file{read.h}. @code{LEX_NAME} indicates that the character
865 may appear in a name. @code{LEX_BEGIN_NAME} indicates that the character may
866 appear at the beginning of a name.
870 You may define this macro to the lexical type of the brace characters @kbd{@{},
871 @kbd{@}}, @kbd{[}, and @kbd{]}. The default value is zero.
875 You may define this macro to the lexical type of the @kbd{%} character. The
876 default value is zero.
880 You may define this macro to the lexical type of the @kbd{?} character. The
881 default value it zero.
885 You may define this macro to the lexical type of the @kbd{$} character. The
886 default value is @code{LEX_NAME | LEX_BEGIN_NAME}.
888 @item NUMBERS_WITH_SUFFIX
889 @cindex NUMBERS_WITH_SUFFIX
890 When this macro is defined to be non-zero, the parser allows the radix of a
891 constant to be indicated with a suffix. Valid suffixes are binary (B),
892 octal (Q), and hexadecimal (H). Case is not significant.
894 @item SINGLE_QUOTE_STRINGS
895 @cindex SINGLE_QUOTE_STRINGS
896 If you define this macro, GAS will treat single quotes as string delimiters.
897 Normally only double quotes are accepted as string delimiters.
899 @item NO_STRING_ESCAPES
900 @cindex NO_STRING_ESCAPES
901 If you define this macro, GAS will not permit escape sequences in a string.
903 @item ONLY_STANDARD_ESCAPES
904 @cindex ONLY_STANDARD_ESCAPES
905 If you define this macro, GAS will warn about the use of nonstandard escape
906 sequences in a string.
908 @item md_start_line_hook
909 @cindex md_start_line_hook
910 If you define this macro, GAS will call it at the start of each line.
912 @item LABELS_WITHOUT_COLONS
913 @cindex LABELS_WITHOUT_COLONS
914 If you define this macro, GAS will assume that any text at the start of a line
915 is a label, even if it does not have a colon.
918 @itemx TC_START_LABEL_WITHOUT_COLON
919 @cindex TC_START_LABEL
920 You may define this macro to control what GAS considers to be a label. The
921 default definition is to accept any name followed by a colon character.
923 @item TC_START_LABEL_WITHOUT_COLON
924 @cindex TC_START_LABEL_WITHOUT_COLON
925 Same as TC_START_LABEL, but should be used instead of TC_START_LABEL when
926 LABELS_WITHOUT_COLONS is defined.
929 @cindex TC_FAKE_LABEL
930 You may define this macro to control what GAS considers to be a fake
931 label. The default fake label is FAKE_LABEL_NAME.
934 @cindex NO_PSEUDO_DOT
935 If you define this macro, GAS will not require pseudo-ops to start with a
938 @item TC_EQUAL_IN_INSN
939 @cindex TC_EQUAL_IN_INSN
940 If you define this macro, it should return nonzero if the instruction is
941 permitted to contain an @kbd{=} character. GAS will call it with two
942 arguments, the character before the @kbd{=} character, and the value of
943 the string preceding the equal sign. GAS uses this macro to decide if a
944 @kbd{=} is an assignment or an instruction.
947 @cindex TC_EOL_IN_INSN
948 If you define this macro, it should return nonzero if the current input line
949 pointer should be treated as the end of a line.
951 @item TC_CASE_SENSITIVE
952 @cindex TC_CASE_SENSITIVE
953 Define this macro if instruction mnemonics and pseudos are case sensitive.
954 The default is to have it undefined giving case insensitive names.
957 @cindex md_parse_name
958 If this macro is defined, GAS will call it for any symbol found in an
959 expression. You can define this to handle special symbols in a special way.
960 If a symbol always has a certain value, you should normally enter it in the
961 symbol table, perhaps using @code{reg_section}.
963 @item md_undefined_symbol
964 @cindex md_undefined_symbol
965 GAS will call this function when a symbol table lookup fails, before it
966 creates a new symbol. Typically this would be used to supply symbols whose
967 name or value changes dynamically, possibly in a context sensitive way.
968 Predefined symbols with fixed values, such as register names or condition
969 codes, are typically entered directly into the symbol table when @code{md_begin}
970 is called. One argument is passed, a @code{char *} for the symbol.
974 GAS will call this function with one argument, an @code{expressionS}
975 pointer, for any expression that can not be recognized. When the function
976 is called, @code{input_line_pointer} will point to the start of the
979 @item tc_unrecognized_line
980 @cindex tc_unrecognized_line
981 If you define this macro, GAS will call it when it finds a line that it can not
986 You may define this macro to handle an alignment directive. GAS will call it
987 when the directive is seen in the input file. For example, the i386 backend
988 uses this to generate efficient nop instructions of varying lengths, depending
989 upon the number of bytes that the alignment will skip.
993 You may define this macro to do special handling for an alignment directive.
994 GAS will call it at the end of the assembly.
996 @item TC_IMPLICIT_LCOMM_ALIGNMENT (@var{size}, @var{p2var})
997 @cindex TC_IMPLICIT_LCOMM_ALIGNMENT
998 An @code{.lcomm} directive with no explicit alignment parameter will use this
999 macro to set @var{p2var} to the alignment that a request for @var{size} bytes
1000 will have. The alignment is expressed as a power of two. If no alignment
1001 should take place, the macro definition should do nothing. Some targets define
1002 a @code{.bss} directive that is also affected by this macro. The default
1003 definition will set @var{p2var} to the truncated power of two of sizes up to
1006 @item md_flush_pending_output
1007 @cindex md_flush_pending_output
1008 If you define this macro, GAS will call it each time it skips any space because of a
1009 space filling or alignment or data allocation pseudo-op.
1011 @item TC_PARSE_CONS_EXPRESSION
1012 @cindex TC_PARSE_CONS_EXPRESSION
1013 You may define this macro to parse an expression used in a data allocation
1014 pseudo-op such as @code{.word}. You can use this to recognize relocation
1015 directives that may appear in such directives.
1017 @item BITFIELD_CONS_EXPRESSION
1018 @cindex BITFIELD_CONS_EXPRESSION
1019 If you define this macro, GAS will recognize bitfield instructions in data
1020 allocation pseudo-ops, as used on the i960.
1022 @item REPEAT_CONS_EXPRESSION
1023 @cindex REPEAT_CONS_EXPRESSION
1024 If you define this macro, GAS will recognize repeat counts in data allocation
1025 pseudo-ops, as used on the MIPS.
1028 @cindex md_cons_align
1029 You may define this macro to do any special alignment before a data allocation
1032 @item TC_CONS_FIX_NEW
1033 @cindex TC_CONS_FIX_NEW
1034 You may define this macro to generate a fixup for a data allocation pseudo-op.
1036 @item TC_ADDRESS_BYTES
1037 @cindex TC_ADDRESS_BYTES
1038 Define this macro to specify the number of bytes used to store an address.
1039 Used to implement @code{dc.a}. The target must have a reloc for this size.
1041 @item TC_INIT_FIX_DATA (@var{fixp})
1042 @cindex TC_INIT_FIX_DATA
1043 A C statement to initialize the target specific fields of fixup @var{fixp}.
1044 These fields are defined with the @code{TC_FIX_TYPE} macro.
1046 @item TC_FIX_DATA_PRINT (@var{stream}, @var{fixp})
1047 @cindex TC_FIX_DATA_PRINT
1048 A C statement to output target specific debugging information for
1049 fixup @var{fixp} to @var{stream}. This macro is called by @code{print_fixup}.
1051 @item TC_FRAG_INIT (@var{fragp})
1052 @cindex TC_FRAG_INIT
1053 A C statement to initialize the target specific fields of frag @var{fragp}.
1054 These fields are defined with the @code{TC_FRAG_TYPE} macro.
1056 @item md_number_to_chars
1057 @cindex md_number_to_chars
1058 This should just call either @code{number_to_chars_bigendian} or
1059 @code{number_to_chars_littleendian}, whichever is appropriate. On targets like
1060 the MIPS which support options to change the endianness, which function to call
1061 is a runtime decision. On other targets, @code{md_number_to_chars} can be a
1064 @item md_atof (@var{type},@var{litP},@var{sizeP})
1066 This function is called to convert an ASCII string into a floating point value
1067 in format used by the CPU. It takes three arguments. The first is @var{type}
1068 which is a byte describing the type of floating point number to be created.
1069 Possible values are @var{'f'} or @var{'s'} for single precision, @var{'d'} or
1070 @var{'r'} for double precision and @var{'x'} or @var{'p'} for extended
1071 precision. Either lower or upper case versions of these letters can be used.
1073 The second parameter is @var{litP} which is a pointer to a byte array where the
1074 converted value should be stored. The third argument is @var{sizeP}, which is
1075 a pointer to a integer that should be filled in with the number of
1076 @var{LITTLENUM}s emitted into the byte array. (@var{LITTLENUM} is defined in
1077 gas/bignum.h). The function should return NULL upon success or an error string
1080 @item TC_LARGEST_EXPONENT_IS_NORMAL
1081 @cindex TC_LARGEST_EXPONENT_IS_NORMAL (@var{precision})
1082 This macro is used only by @file{atof-ieee.c}. It should evaluate to true
1083 if floats of the given precision use the largest exponent for normal numbers
1084 instead of NaNs and infinities. @var{precision} is @samp{F_PRECISION} for
1085 single precision, @samp{D_PRECISION} for double precision, or
1086 @samp{X_PRECISION} for extended double precision.
1088 The macro has a default definition which returns 0 for all cases.
1090 @item WORKING_DOT_WORD
1091 @itemx md_short_jump_size
1092 @itemx md_long_jump_size
1093 @itemx md_create_short_jump
1094 @itemx md_create_long_jump
1095 @itemx TC_CHECK_ADJUSTED_BROKEN_DOT_WORD
1096 @cindex WORKING_DOT_WORD
1097 @cindex md_short_jump_size
1098 @cindex md_long_jump_size
1099 @cindex md_create_short_jump
1100 @cindex md_create_long_jump
1101 @cindex TC_CHECK_ADJUSTED_BROKEN_DOT_WORD
1102 If @code{WORKING_DOT_WORD} is defined, GAS will not do broken word processing
1103 (@pxref{Broken words}). Otherwise, you should set @code{md_short_jump_size} to
1104 the size of a short jump (a jump that is just long enough to jump around a
1105 number of long jumps) and @code{md_long_jump_size} to the size of a long jump
1106 (a jump that can go anywhere in the function). You should define
1107 @code{md_create_short_jump} to create a short jump around a number of long
1108 jumps, and define @code{md_create_long_jump} to create a long jump.
1109 If defined, the macro TC_CHECK_ADJUSTED_BROKEN_DOT_WORD will be called for each
1110 adjusted word just before the word is output. The macro takes two arguments,
1111 an @code{addressT} with the adjusted word and a pointer to the current
1112 @code{struct broken_word}.
1114 @item md_estimate_size_before_relax
1115 @cindex md_estimate_size_before_relax
1116 This function returns an estimate of the size of a @code{rs_machine_dependent}
1117 frag before any relaxing is done. It may also create any necessary
1121 @cindex md_relax_frag
1122 This macro may be defined to relax a frag. GAS will call this with the
1123 segment, the frag, and the change in size of all previous frags;
1124 @code{md_relax_frag} should return the change in size of the frag.
1127 @item TC_GENERIC_RELAX_TABLE
1128 @cindex TC_GENERIC_RELAX_TABLE
1129 If you do not define @code{md_relax_frag}, you may define
1130 @code{TC_GENERIC_RELAX_TABLE} as a table of @code{relax_typeS} structures. The
1131 machine independent code knows how to use such a table to relax PC relative
1132 references. See @file{tc-m68k.c} for an example. @xref{Relaxation}.
1134 @item md_prepare_relax_scan
1135 @cindex md_prepare_relax_scan
1136 If defined, it is a C statement that is invoked prior to scanning
1139 @item LINKER_RELAXING_SHRINKS_ONLY
1140 @cindex LINKER_RELAXING_SHRINKS_ONLY
1141 If you define this macro, and the global variable @samp{linkrelax} is set
1142 (because of a command line option, or unconditionally in @code{md_begin}), a
1143 @samp{.align} directive will cause extra space to be allocated. The linker can
1144 then discard this space when relaxing the section.
1146 @item TC_LINKRELAX_FIXUP (@var{segT})
1147 @cindex TC_LINKRELAX_FIXUP
1148 If defined, this macro allows control over whether fixups for a
1149 given section will be processed when the @var{linkrelax} variable is
1150 set. The macro is given the N_TYPE bits for the section in its
1151 @var{segT} argument. If the macro evaluates to a non-zero value
1152 then the fixups will be converted into relocs, otherwise they will
1153 be passed to @var{md_apply_fix} as normal.
1155 @item md_convert_frag
1156 @cindex md_convert_frag
1157 GAS will call this for each rs_machine_dependent fragment.
1158 The instruction is completed using the data from the relaxation pass.
1159 It may also create any necessary relocations.
1162 @item TC_FINALIZE_SYMS_BEFORE_SIZE_SEG
1163 @cindex TC_FINALIZE_SYMS_BEFORE_SIZE_SEG
1164 Specifies the value to be assigned to @code{finalize_syms} before the function
1165 @code{size_segs} is called. Since @code{size_segs} calls @code{cvt_frag_to_fill}
1166 which can call @code{md_convert_frag}, this constant governs whether the symbols
1167 accessed in @code{md_convert_frag} will be fully resolved. In particular it
1168 governs whether local symbols will have been resolved, and had their frag
1169 information removed. Depending upon the processing performed by
1170 @code{md_convert_frag} the frag information may or may not be necessary, as may
1171 the resolved values of the symbols. The default value is 1.
1173 @item TC_VALIDATE_FIX (@var{fixP}, @var{seg}, @var{skip})
1174 @cindex TC_VALIDATE_FIX
1175 This macro is evaluated for each fixup (when @var{linkrelax} is not set).
1176 It may be used to change the fixup in @code{struct fix *@var{fixP}} before
1177 the generic code sees it, or to fully process the fixup. In the latter case,
1178 a @code{goto @var{skip}} will bypass the generic code.
1180 @item md_apply_fix (@var{fixP}, @var{valP}, @var{seg})
1181 @cindex md_apply_fix
1182 GAS will call this for each fixup that passes the @code{TC_VALIDATE_FIX} test
1183 when @var{linkrelax} is not set. It should store the correct value in the
1184 object file. @code{struct fix *@var{fixP}} is the fixup @code{md_apply_fix}
1185 is operating on. @code{valueT *@var{valP}} is the value to store into the
1186 object files, or at least is the generic code's best guess. Specifically,
1187 *@var{valP} is the value of the fixup symbol, perhaps modified by
1188 @code{MD_APPLY_SYM_VALUE}, plus @code{@var{fixP}->fx_offset} (symbol addend),
1189 less @code{MD_PCREL_FROM_SECTION} for pc-relative fixups.
1190 @code{segT @var{seg}} is the section the fix is in.
1191 @code{fixup_segment} performs a generic overflow check on *@var{valP} after
1192 @code{md_apply_fix} returns. If the overflow check is relevant for the target
1193 machine, then @code{md_apply_fix} should modify *@var{valP}, typically to the
1194 value stored in the object file.
1196 @item TC_FORCE_RELOCATION (@var{fix})
1197 @cindex TC_FORCE_RELOCATION
1198 If this macro returns non-zero, it guarantees that a relocation will be emitted
1199 even when the value can be resolved locally, as @code{fixup_segment} tries to
1200 reduce the number of relocations emitted. For example, a fixup expression
1201 against an absolute symbol will normally not require a reloc. If undefined,
1202 a default of @w{@code{(S_FORCE_RELOC ((@var{fix})->fx_addsy))}} is used.
1204 @item TC_FORCE_RELOCATION_ABS (@var{fix})
1205 @cindex TC_FORCE_RELOCATION_ABS
1206 Like @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against an
1207 absolute symbol. If undefined, @code{TC_FORCE_RELOCATION} will be used.
1209 @item TC_FORCE_RELOCATION_LOCAL (@var{fix})
1210 @cindex TC_FORCE_RELOCATION_LOCAL
1211 Like @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against a
1212 symbol in the current section. If undefined, fixups that are not
1213 @code{fx_pcrel} or @code{fx_plt} or for which @code{TC_FORCE_RELOCATION}
1214 returns non-zero, will emit relocs.
1216 @item TC_FORCE_RELOCATION_SUB_SAME (@var{fix}, @var{seg})
1217 @cindex TC_FORCE_RELOCATION_SUB_SAME
1218 This macro controls resolution of fixup expressions involving the
1219 difference of two symbols in the same section. If this macro returns zero,
1220 the subtrahend will be resolved and @code{fx_subsy} set to @code{NULL} for
1221 @code{md_apply_fix}. If undefined, the default of
1222 @w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will
1225 @item TC_FORCE_RELOCATION_SUB_ABS (@var{fix})
1226 @cindex TC_FORCE_RELOCATION_SUB_ABS
1227 Like @code{TC_FORCE_RELOCATION_SUB_SAME}, but used when the subtrahend is an
1228 absolute symbol. If the macro is undefined a default of @code{0} is used.
1230 @item TC_FORCE_RELOCATION_SUB_LOCAL (@var{fix})
1231 @cindex TC_FORCE_RELOCATION_SUB_LOCAL
1232 Like @code{TC_FORCE_RELOCATION_SUB_ABS}, but the subtrahend is a symbol in the
1233 same section as the fixup.
1235 @item TC_VALIDATE_FIX_SUB (@var{fix})
1236 @cindex TC_VALIDATE_FIX_SUB
1237 This macro is evaluated for any fixup with a @code{fx_subsy} that
1238 @code{fixup_segment} cannot reduce to a number. If the macro returns
1239 @code{false} an error will be reported.
1241 @item MD_APPLY_SYM_VALUE (@var{fix})
1242 @cindex MD_APPLY_SYM_VALUE
1243 This macro controls whether the symbol value becomes part of the value passed
1244 to @code{md_apply_fix}. If the macro is undefined, or returns non-zero, the
1245 symbol value will be included. For ELF, a suitable definition might simply be
1246 @code{0}, because ELF relocations don't include the symbol value in the addend.
1248 @item S_FORCE_RELOC (@var{sym}, @var{strict})
1249 @cindex S_FORCE_RELOC
1250 This function returns true for symbols
1251 that should not be reduced to section symbols or eliminated from expressions,
1252 because they may be overridden by the linker. ie. for symbols that are
1253 undefined or common, and when @var{strict} is set, weak, or global (for ELF
1254 assemblers that support ELF shared library linking semantics).
1256 @item EXTERN_FORCE_RELOC
1257 @cindex EXTERN_FORCE_RELOC
1258 This macro controls whether @code{S_FORCE_RELOC} returns true for global
1259 symbols. If undefined, the default is @code{true} for ELF assemblers, and
1260 @code{false} for non-ELF.
1263 @cindex tc_gen_reloc
1264 GAS will call this to generate a reloc. GAS will pass
1265 the resulting reloc to @code{bfd_install_relocation}. This currently works
1266 poorly, as @code{bfd_install_relocation} often does the wrong thing, and
1267 instances of @code{tc_gen_reloc} have been written to work around the problems,
1268 which in turns makes it difficult to fix @code{bfd_install_relocation}.
1270 @item RELOC_EXPANSION_POSSIBLE
1271 @cindex RELOC_EXPANSION_POSSIBLE
1272 If you define this macro, it means that @code{tc_gen_reloc} may return multiple
1273 relocation entries for a single fixup. In this case, the return value of
1274 @code{tc_gen_reloc} is a pointer to a null terminated array.
1276 @item MAX_RELOC_EXPANSION
1277 @cindex MAX_RELOC_EXPANSION
1278 You must define this if @code{RELOC_EXPANSION_POSSIBLE} is defined; it
1279 indicates the largest number of relocs which @code{tc_gen_reloc} may return for
1282 @item tc_fix_adjustable
1283 @cindex tc_fix_adjustable
1284 You may define this macro to indicate whether a fixup against a locally defined
1285 symbol should be adjusted to be against the section symbol. It should return a
1286 non-zero value if the adjustment is acceptable.
1288 @item MD_PCREL_FROM_SECTION (@var{fixp}, @var{section})
1289 @cindex MD_PCREL_FROM_SECTION
1290 If you define this macro, it should return the position from which the PC
1291 relative adjustment for a PC relative fixup should be made. On many
1292 processors, the base of a PC relative instruction is the next instruction,
1293 so this macro would return the length of an instruction, plus the address of
1294 the PC relative fixup. The latter can be calculated as
1295 @var{fixp}->fx_where + @var{fixp}->fx_frag->fr_address .
1298 @cindex md_pcrel_from
1299 This is the default value of @code{MD_PCREL_FROM_SECTION}. The difference is
1300 that @code{md_pcrel_from} does not take a section argument.
1303 @cindex tc_frob_label
1304 If you define this macro, GAS will call it each time a label is defined.
1306 @item md_section_align
1307 @cindex md_section_align
1308 GAS will call this function for each section at the end of the assembly, to
1309 permit the CPU backend to adjust the alignment of a section. The function
1310 must take two arguments, a @code{segT} for the section and a @code{valueT}
1311 for the size of the section, and return a @code{valueT} for the rounded
1314 @item md_macro_start
1315 @cindex md_macro_start
1316 If defined, GAS will call this macro when it starts to include a macro
1317 expansion. @code{macro_nest} indicates the current macro nesting level, which
1318 includes the one being expanded.
1321 @cindex md_macro_info
1322 If defined, GAS will call this macro after the macro expansion has been
1323 included in the input and after parsing the macro arguments. The single
1324 argument is a pointer to the macro processing's internal representation of the
1325 macro (macro_entry *), which includes expansion of the formal arguments.
1328 @cindex md_macro_end
1329 Complement to md_macro_start. If defined, it is called when finished
1330 processing an inserted macro expansion, just before decrementing macro_nest.
1332 @item DOUBLEBAR_PARALLEL
1333 @cindex DOUBLEBAR_PARALLEL
1334 Affects the preprocessor so that lines containing '||' don't have their
1335 whitespace stripped following the double bar. This is useful for targets that
1336 implement parallel instructions.
1338 @item KEEP_WHITE_AROUND_COLON
1339 @cindex KEEP_WHITE_AROUND_COLON
1340 Normally, whitespace is compressed and removed when, in the presence of the
1341 colon, the adjoining tokens can be distinguished. This option affects the
1342 preprocessor so that whitespace around colons is preserved. This is useful
1343 when colons might be removed from the input after preprocessing but before
1344 assembling, so that adjoining tokens can still be distinguished if there is
1345 whitespace, or concatenated if there is not.
1347 @item tc_frob_section
1348 @cindex tc_frob_section
1349 If you define this macro, GAS will call it for each
1350 section at the end of the assembly.
1352 @item tc_frob_file_before_adjust
1353 @cindex tc_frob_file_before_adjust
1354 If you define this macro, GAS will call it after the symbol values are
1355 resolved, but before the fixups have been changed from local symbols to section
1358 @item tc_frob_symbol
1359 @cindex tc_frob_symbol
1360 If you define this macro, GAS will call it for each symbol. You can indicate
1361 that the symbol should not be included in the object file by defining this
1362 macro to set its second argument to a non-zero value.
1365 @cindex tc_frob_file
1366 If you define this macro, GAS will call it after the symbol table has been
1367 completed, but before the relocations have been generated.
1369 @item tc_frob_file_after_relocs
1370 If you define this macro, GAS will call it after the relocs have been
1373 @item md_post_relax_hook
1374 If you define this macro, GAS will call it after relaxing and sizing the
1377 @item LISTING_HEADER
1378 A string to use on the header line of a listing. The default value is simply
1379 @code{"GAS LISTING"}.
1381 @item LISTING_WORD_SIZE
1382 The number of bytes to put into a word in a listing. This affects the way the
1383 bytes are clumped together in the listing. For example, a value of 2 might
1384 print @samp{1234 5678} where a value of 1 would print @samp{12 34 56 78}. The
1387 @item LISTING_LHS_WIDTH
1388 The number of words of data to print on the first line of a listing for a
1389 particular source line, where each word is @code{LISTING_WORD_SIZE} bytes. The
1392 @item LISTING_LHS_WIDTH_SECOND
1393 Like @code{LISTING_LHS_WIDTH}, but applying to the second and subsequent line
1394 of the data printed for a particular source line. The default value is 1.
1396 @item LISTING_LHS_CONT_LINES
1397 The maximum number of continuation lines to print in a listing for a particular
1398 source line. The default value is 4.
1400 @item LISTING_RHS_WIDTH
1401 The maximum number of characters to print from one line of the input file. The
1402 default value is 100.
1404 @item TC_COFF_SECTION_DEFAULT_ATTRIBUTES
1405 @cindex TC_COFF_SECTION_DEFAULT_ATTRIBUTES
1406 The COFF @code{.section} directive will use the value of this macro to set
1407 a new section's attributes when a directive has no valid flags or when the
1408 flag is @code{w}. The default value of the macro is @code{SEC_LOAD | SEC_DATA}.
1410 @item DWARF2_FORMAT ()
1411 @cindex DWARF2_FORMAT
1412 If you define this, it should return one of @code{dwarf2_format_32bit},
1413 @code{dwarf2_format_64bit}, or @code{dwarf2_format_64bit_irix} to indicate
1414 the size of internal DWARF section offsets and the format of the DWARF initial
1415 length fields. When @code{dwarf2_format_32bit} is returned, the initial
1416 length field will be 4 bytes long and section offsets are 32 bits in size.
1417 For @code{dwarf2_format_64bit} and @code{dwarf2_format_64bit_irix}, section
1418 offsets are 64 bits in size, but the initial length field differs. An 8 byte
1419 initial length is indicated by @code{dwarf2_format_64bit_irix} and
1420 @code{dwarf2_format_64bit} indicates a 12 byte initial length field in
1421 which the first four bytes are 0xffffffff and the next 8 bytes are
1422 the section's length.
1424 If you don't define this, @code{dwarf2_format_32bit} will be used as
1427 This define only affects @code{.debug_info} and @code{.debug_line}
1428 sections generated by the assembler. DWARF 2 sections generated by
1429 other tools will be unaffected by this setting.
1431 @item DWARF2_ADDR_SIZE (@var{bfd})
1432 @cindex DWARF2_ADDR_SIZE
1433 It should return the size of an address, as it should be represented in
1434 debugging info. If you don't define this macro, the default definition uses
1435 the number of bits per address, as defined in @var{bfd}, divided by 8.
1437 @item MD_DEBUG_FORMAT_SELECTOR
1438 @cindex MD_DEBUG_FORMAT_SELECTOR
1439 If defined this macro is the name of a function to be called when the
1440 @samp{--gen-debug} switch is detected on the assembler's command line. The
1441 prototype for the function looks like this:
1444 enum debug_info_type MD_DEBUG_FORMAT_SELECTOR (int * use_gnu_extensions)
1447 The function should return the debug format that is preferred by the CPU
1448 backend. This format will be used when generating assembler specific debug
1453 @node Object format backend
1454 @subsection Writing an object format backend
1455 @cindex object format backend
1456 @cindex @file{obj-@var{fmt}}
1458 As with the CPU backend, the object format backend must define a few things,
1459 and may define some other things. The interface to the object format backend
1460 is generally simpler; most of the support for an object file format consists of
1461 defining a number of pseudo-ops.
1463 The object format @file{.h} file must include @file{targ-cpu.h}.
1466 @item OBJ_@var{format}
1467 @cindex OBJ_@var{format}
1468 By convention, you should define this macro in the @file{.h} file. For
1469 example, @file{obj-elf.h} defines @code{OBJ_ELF}. You might have to use this
1470 if it is necessary to add object file format specific code to the CPU file.
1473 If you define this macro, GAS will call it at the start of the assembly, after
1474 the command line arguments have been parsed and all the machine independent
1475 initializations have been completed.
1478 @cindex obj_app_file
1479 If you define this macro, GAS will invoke it when it sees a @code{.file}
1480 pseudo-op or a @samp{#} line as used by the C preprocessor.
1482 @item OBJ_COPY_SYMBOL_ATTRIBUTES
1483 @cindex OBJ_COPY_SYMBOL_ATTRIBUTES
1484 You should define this macro to copy object format specific information from
1485 one symbol to another. GAS will call it when one symbol is equated to
1488 @item obj_sec_sym_ok_for_reloc
1489 @cindex obj_sec_sym_ok_for_reloc
1490 You may define this macro to indicate that it is OK to use a section symbol in
1491 a relocation entry. If it is not, GAS will define a new symbol at the start
1494 @item EMIT_SECTION_SYMBOLS
1495 @cindex EMIT_SECTION_SYMBOLS
1496 You should define this macro with a zero value if you do not want to include
1497 section symbols in the output symbol table. The default value for this macro
1500 @item obj_adjust_symtab
1501 @cindex obj_adjust_symtab
1502 If you define this macro, GAS will invoke it just before setting the symbol
1503 table of the output BFD. For example, the COFF support uses this macro to
1504 generate a @code{.file} symbol if none was generated previously.
1506 @item SEPARATE_STAB_SECTIONS
1507 @cindex SEPARATE_STAB_SECTIONS
1508 You may define this macro to a nonzero value to indicate that stabs should be
1509 placed in separate sections, as in ELF.
1511 @item INIT_STAB_SECTION
1512 @cindex INIT_STAB_SECTION
1513 You may define this macro to initialize the stabs section in the output file.
1515 @item OBJ_PROCESS_STAB
1516 @cindex OBJ_PROCESS_STAB
1517 You may define this macro to do specific processing on a stabs entry.
1519 @item obj_frob_section
1520 @cindex obj_frob_section
1521 If you define this macro, GAS will call it for each section at the end of the
1524 @item obj_frob_file_before_adjust
1525 @cindex obj_frob_file_before_adjust
1526 If you define this macro, GAS will call it after the symbol values are
1527 resolved, but before the fixups have been changed from local symbols to section
1530 @item obj_frob_symbol
1531 @cindex obj_frob_symbol
1532 If you define this macro, GAS will call it for each symbol. You can indicate
1533 that the symbol should not be included in the object file by defining this
1534 macro to set its second argument to a non-zero value.
1537 @cindex obj_frob_file
1538 If you define this macro, GAS will call it after the symbol table has been
1539 completed, but before the relocations have been generated.
1541 @item obj_frob_file_after_relocs
1542 If you define this macro, GAS will call it after the relocs have been
1545 @item SET_SECTION_RELOCS (@var{sec}, @var{relocs}, @var{n})
1546 @cindex SET_SECTION_RELOCS
1547 If you define this, it will be called after the relocations have been set for
1548 the section @var{sec}. The list of relocations is in @var{relocs}, and the
1549 number of relocations is in @var{n}.
1553 @subsection Writing emulation files
1555 Normally you do not have to write an emulation file. You can just use
1556 @file{te-generic.h}.
1558 If you do write your own emulation file, it must include @file{obj-format.h}.
1560 An emulation file will often define @code{TE_@var{EM}}; this may then be used
1561 in other files to change the output.
1567 @dfn{Relaxation} is a generic term used when the size of some instruction or
1568 data depends upon the value of some symbol or other data.
1570 GAS knows to relax a particular type of PC relative relocation using a table.
1571 You can also define arbitrarily complex forms of relaxation yourself.
1574 * Relaxing with a table:: Relaxing with a table
1575 * General relaxing:: General relaxing
1578 @node Relaxing with a table
1579 @subsection Relaxing with a table
1581 If you do not define @code{md_relax_frag}, and you do define
1582 @code{TC_GENERIC_RELAX_TABLE}, GAS will relax @code{rs_machine_dependent} frags
1583 based on the frag subtype and the displacement to some specified target
1584 address. The basic idea is that several machines have different addressing
1585 modes for instructions that can specify different ranges of values, with
1586 successive modes able to access wider ranges, including the entirety of the
1587 previous range. Smaller ranges are assumed to be more desirable (perhaps the
1588 instruction requires one word instead of two or three); if this is not the
1589 case, don't describe the smaller-range, inferior mode.
1591 The @code{fr_subtype} field of a frag is an index into a CPU-specific
1592 relaxation table. That table entry indicates the range of values that can be
1593 stored, the number of bytes that will have to be added to the frag to
1594 accommodate the addressing mode, and the index of the next entry to examine if
1595 the value to be stored is outside the range accessible by the current
1596 addressing mode. The @code{fr_symbol} field of the frag indicates what symbol
1597 is to be accessed; the @code{fr_offset} field is added in.
1599 If the @code{TC_PCREL_ADJUST} macro is defined, which currently should only happen
1600 for the NS32k family, the @code{TC_PCREL_ADJUST} macro is called on the frag to
1601 compute an adjustment to be made to the displacement.
1603 The value fitted by the relaxation code is always assumed to be a displacement
1604 from the current frag. (More specifically, from @code{fr_fix} bytes into the
1607 This seems kinda silly. What about fitting small absolute values? I suppose
1608 @code{md_assemble} is supposed to take care of that, but if the operand is a
1609 difference between symbols, it might not be able to, if the difference was not
1613 The end of the relaxation sequence is indicated by a ``next'' value of 0. This
1614 means that the first entry in the table can't be used.
1616 For some configurations, the linker can do relaxing within a section of an
1617 object file. If call instructions of various sizes exist, the linker can
1618 determine which should be used in each instance, when a symbol's value is
1619 resolved. In order for the linker to avoid wasting space and having to insert
1620 no-op instructions, it must be able to expand or shrink the section contents
1621 while still preserving intra-section references and meeting alignment
1624 For the i960 using b.out format, no expansion is done; instead, each
1625 @samp{.align} directive causes extra space to be allocated, enough that when
1626 the linker is relaxing a section and removing unneeded space, it can discard
1627 some or all of this extra padding and cause the following data to be correctly
1630 For the H8/300, I think the linker expands calls that can't reach, and doesn't
1631 worry about alignment issues; the cpu probably never needs any significant
1632 alignment beyond the instruction size.
1634 The relaxation table type contains these fields:
1637 @item long rlx_forward
1638 Forward reach, must be non-negative.
1639 @item long rlx_backward
1640 Backward reach, must be zero or negative.
1642 Length in bytes of this addressing mode.
1644 Index of the next-longer relax state, or zero if there is no next relax state.
1647 The relaxation is done in @code{relax_segment} in @file{write.c}. The
1648 difference in the length fields between the original mode and the one finally
1649 chosen by the relaxing code is taken as the size by which the current frag will
1650 be increased in size. For example, if the initial relaxing mode has a length
1651 of 2 bytes, and because of the size of the displacement, it gets upgraded to a
1652 mode with a size of 6 bytes, it is assumed that the frag will grow by 4 bytes.
1653 (The initial two bytes should have been part of the fixed portion of the frag,
1654 since it is already known that they will be output.) This growth must be
1655 effected by @code{md_convert_frag}; it should increase the @code{fr_fix} field
1656 by the appropriate size, and fill in the appropriate bytes of the frag.
1657 (Enough space for the maximum growth should have been allocated in the call to
1658 frag_var as the second argument.)
1660 If relocation records are needed, they should be emitted by
1661 @code{md_estimate_size_before_relax}. This function should examine the target
1662 symbol of the supplied frag and correct the @code{fr_subtype} of the frag if
1663 needed. When this function is called, if the symbol has not yet been defined,
1664 it will not become defined later; however, its value may still change if the
1665 section it is in gets relaxed.
1667 Usually, if the symbol is in the same section as the frag (given by the
1668 @var{sec} argument), the narrowest likely relaxation mode is stored in
1669 @code{fr_subtype}, and that's that.
1671 If the symbol is undefined, or in a different section (and therefore movable
1672 to an arbitrarily large distance), the largest available relaxation mode is
1673 specified, @code{fix_new} is called to produce the relocation record,
1674 @code{fr_fix} is increased to include the relocated field (remember, this
1675 storage was allocated when @code{frag_var} was called), and @code{frag_wane} is
1676 called to convert the frag to an @code{rs_fill} frag with no variant part.
1677 Sometimes changing addressing modes may also require rewriting the instruction.
1678 It can be accessed via @code{fr_opcode} or @code{fr_fix}.
1680 If you generate frags separately for the basic insn opcode and any relaxable
1681 operands, do not call @code{fix_new} thinking you can emit fixups for the
1682 opcode field from the relaxable frag. It is not guaranteed to be the same frag.
1683 If you need to emit fixups for the opcode field from inspection of the
1684 relaxable frag, then you need to generate a common frag for both the basic
1685 opcode and relaxable fields, or you need to provide the frag for the opcode to
1686 pass to @code{fix_new}. The latter can be done for example by defining
1687 @code{TC_FRAG_TYPE} to include a pointer to it and defining @code{TC_FRAG_INIT}
1690 Sometimes @code{fr_var} is increased instead, and @code{frag_wane} is not
1691 called. I'm not sure, but I think this is to keep @code{fr_fix} referring to
1692 an earlier byte, and @code{fr_subtype} set to @code{rs_machine_dependent} so
1693 that @code{md_convert_frag} will get called.
1695 @node General relaxing
1696 @subsection General relaxing
1698 If using a simple table is not suitable, you may implement arbitrarily complex
1699 relaxation semantics yourself. For example, the MIPS backend uses this to emit
1700 different instruction sequences depending upon the size of the symbol being
1703 When you assemble an instruction that may need relaxation, you should allocate
1704 a frag using @code{frag_var} or @code{frag_variant} with a type of
1705 @code{rs_machine_dependent}. You should store some sort of information in the
1706 @code{fr_subtype} field so that you can figure out what to do with the frag
1709 When GAS reaches the end of the input file, it will look through the frags and
1710 work out their final sizes.
1712 GAS will first call @code{md_estimate_size_before_relax} on each
1713 @code{rs_machine_dependent} frag. This function must return an estimated size
1716 GAS will then loop over the frags, calling @code{md_relax_frag} on each
1717 @code{rs_machine_dependent} frag. This function should return the change in
1718 size of the frag. GAS will keep looping over the frags until none of the frags
1722 @section Broken words
1723 @cindex internals, broken words
1724 @cindex broken words
1726 Some compilers, including GCC, will sometimes emit switch tables specifying
1727 16-bit @code{.word} displacements to branch targets, and branch instructions
1728 that load entries from that table to compute the target address. If this is
1729 done on a 32-bit machine, there is a chance (at least with really large
1730 functions) that the displacement will not fit in 16 bits. The assembler
1731 handles this using a concept called @dfn{broken words}. This idea is well
1732 named, since there is an implied promise that the 16-bit field will in fact
1733 hold the specified displacement.
1735 If broken word processing is enabled, and a situation like this is encountered,
1736 the assembler will insert a jump instruction into the instruction stream, close
1737 enough to be reached with the 16-bit displacement. This jump instruction will
1738 transfer to the real desired target address. Thus, as long as the @code{.word}
1739 value really is used as a displacement to compute an address to jump to, the
1740 net effect will be correct (minus a very small efficiency cost). If
1741 @code{.word} directives with label differences for values are used for other
1742 purposes, however, things may not work properly. For targets which use broken
1743 words, the @samp{-K} option will warn when a broken word is discovered.
1745 The broken word code is turned off by the @code{WORKING_DOT_WORD} macro. It
1746 isn't needed if @code{.word} emits a value large enough to contain an address
1747 (or, more correctly, any possible difference between two addresses).
1749 @node Internal functions
1750 @section Internal functions
1752 This section describes basic internal functions used by GAS.
1755 * Warning and error messages:: Warning and error messages
1756 * Hash tables:: Hash tables
1759 @node Warning and error messages
1760 @subsection Warning and error messages
1762 @deftypefun @{@} int had_warnings (void)
1763 @deftypefunx @{@} int had_errors (void)
1764 Returns non-zero if any warnings or errors, respectively, have been printed
1765 during this invocation.
1768 @deftypefun @{@} void as_perror (const char *@var{gripe}, const char *@var{filename})
1769 Displays a BFD or system error, then clears the error status.
1772 @deftypefun @{@} void as_tsktsk (const char *@var{format}, ...)
1773 @deftypefunx @{@} void as_warn (const char *@var{format}, ...)
1774 @deftypefunx @{@} void as_bad (const char *@var{format}, ...)
1775 @deftypefunx @{@} void as_fatal (const char *@var{format}, ...)
1776 These functions display messages about something amiss with the input file, or
1777 internal problems in the assembler itself. The current file name and line
1778 number are printed, followed by the supplied message, formatted using
1779 @code{vfprintf}, and a final newline.
1781 An error indicated by @code{as_bad} will result in a non-zero exit status when
1782 the assembler has finished. Calling @code{as_fatal} will result in immediate
1783 termination of the assembler process.
1786 @deftypefun @{@} void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
1787 @deftypefunx @{@} void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
1788 These variants permit specification of the file name and line number, and are
1789 used when problems are detected when reprocessing information saved away when
1790 processing some earlier part of the file. For example, fixups are processed
1791 after all input has been read, but messages about fixups should refer to the
1792 original filename and line number that they are applicable to.
1795 @deftypefun @{@} void sprint_value (char *@var{buf}, valueT @var{val})
1796 This function is helpful for converting a @code{valueT} value into printable
1797 format, in case it's wider than modes that @code{*printf} can handle. If the
1798 type is narrow enough, a decimal number will be produced; otherwise, it will be
1799 in hexadecimal. The value itself is not examined to make this determination.
1803 @subsection Hash tables
1806 @deftypefun @{@} @{struct hash_control *@} hash_new (void)
1807 Creates the hash table control structure.
1810 @deftypefun @{@} void hash_die (struct hash_control *)
1811 Destroy a hash table.
1814 @deftypefun @{@} PTR hash_delete (struct hash_control *, const char *)
1815 Deletes entry from the hash table, returns the value it had.
1818 @deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR)
1819 Updates the value for an entry already in the table, returning the old value.
1820 If no entry was found, just returns NULL.
1823 @deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR)
1824 Inserting a value already in the table is an error.
1825 Returns an error message or NULL.
1828 @deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR)
1829 Inserts if the value isn't already present, updates it if it is.
1836 The test suite is kind of lame for most processors. Often it only checks to
1837 see if a couple of files can be assembled without the assembler reporting any
1838 errors. For more complete testing, write a test which either examines the
1839 assembler listing, or runs @code{objdump} and examines its output. For the
1840 latter, the TCL procedure @code{run_dump_test} may come in handy. It takes the
1841 base name of a file, and looks for @file{@var{file}.d}. This file should
1842 contain as its initial lines a set of variable settings in @samp{#} comments,
1846 #@var{varname}: @var{value}
1849 The @var{varname} may be @code{objdump}, @code{nm}, or @code{as}, in which case
1850 it specifies the options to be passed to the specified programs. Exactly one
1851 of @code{objdump} or @code{nm} must be specified, as that also specifies which
1852 program to run after the assembler has finished. If @var{varname} is
1853 @code{source}, it specifies the name of the source file; otherwise,
1854 @file{@var{file}.s} is used. If @var{varname} is @code{name}, it specifies the
1855 name of the test to be used in the @code{pass} or @code{fail} messages.
1857 The non-commented parts of the file are interpreted as regular expressions, one
1858 per line. Blank lines in the @code{objdump} or @code{nm} output are skipped,
1859 as are blank lines in the @code{.d} file; the other lines are tested to see if
1860 the regular expression matches the program output. If it does not, the test
1863 Note that this means the tests must be modified if the @code{objdump} output