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 Whether the symbol is a @code{weakref} alias to another symbol.
100 Whether the symbol is or was referenced by one or more @code{weakref} aliases,
101 and has not had any direct references.
104 This points to the BFD @code{asymbol} that
105 will be used in writing the object file.
108 This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by
109 that name is defined in @file{obj-format.h}, this field is not defined.
112 This processor-specific data is of type @code{TC_SYMFIELD_TYPE}. If no macro
113 by that name is defined in @file{targ-cpu.h}, this field is not defined.
117 Here is a description of the accessor functions. These should be used rather
118 than referring to the fields of @code{symbolS} directly.
123 Set the symbol's value.
127 Get the symbol's value. This will cause @code{resolve_symbol_value} to be
131 @cindex S_SET_SEGMENT
132 Set the section of the symbol.
135 @cindex S_GET_SEGMENT
136 Get the symbol's section.
140 Get the name of the symbol.
144 Set the name of the symbol.
147 @cindex S_IS_EXTERNAL
148 Return non-zero if the symbol is externally visible.
152 A synonym for @code{S_IS_EXTERNAL}. Don't use it.
156 Return non-zero if the symbol is weak, or if it is a @code{weakref} alias or
157 symbol that has not been strongly referenced.
160 @cindex S_IS_WEAKREFR
161 Return non-zero if the symbol is a @code{weakref} alias.
164 @cindex S_IS_WEAKREFD
165 Return non-zero if the symbol was aliased by a @code{weakref} alias and has not
166 had any strong references.
170 Return non-zero if this is a common symbol. Common symbols are sometimes
171 represented as undefined symbols with a value, in which case this function will
176 Return non-zero if this symbol is defined. This function is not reliable when
177 called on a common symbol.
181 Return non-zero if this is a debugging symbol.
185 Return non-zero if this is a local assembler symbol which should not be
186 included in the final symbol table. Note that this is not the opposite of
187 @code{S_IS_EXTERNAL}. The @samp{-L} assembler option affects the return value
191 @cindex S_SET_EXTERNAL
192 Mark the symbol as externally visible.
194 @item S_CLEAR_EXTERNAL
195 @cindex S_CLEAR_EXTERNAL
196 Mark the symbol as not externally visible.
200 Mark the symbol as weak.
203 @cindex S_SET_WEAKREFR
204 Mark the symbol as the referrer in a @code{weakref} directive. The symbol it
205 aliases must have been set to the value expression before this point. If the
206 alias has already been used, the symbol is marked as used too.
208 @item S_CLEAR_WEAKREFR
209 @cindex S_CLEAR_WEAKREFR
210 Clear the @code{weakref} alias status of a symbol. This is implicitly called
211 whenever a symbol is defined or set to a new expression.
214 @cindex S_SET_WEAKREFD
215 Mark the symbol as the referred symbol in a @code{weakref} directive.
216 Implicitly marks the symbol as weak, but see below. It should only be called
217 if the referenced symbol has just been added to the symbol table.
220 @cindex S_SET_WEAKREFD
221 Clear the @code{weakref} aliased status of a symbol. This is implicitly called
222 whenever the symbol is looked up, as part of a direct reference or a
223 definition, but not as part of a @code{weakref} directive.
231 Get the @code{type}, @code{desc}, and @code{other} fields of the symbol. These
232 are only defined for object file formats for which they make sense (primarily
241 Set the @code{type}, @code{desc}, and @code{other} fields of the symbol. These
242 are only defined for object file formats for which they make sense (primarily
247 Get the size of a symbol. This is only defined for object file formats for
248 which it makes sense (primarily ELF).
252 Set the size of a symbol. This is only defined for object file formats for
253 which it makes sense (primarily ELF).
255 @item symbol_get_value_expression
256 @cindex symbol_get_value_expression
257 Get a pointer to an @code{expressionS} structure which represents the value of
258 the symbol as an expression.
260 @item symbol_set_value_expression
261 @cindex symbol_set_value_expression
262 Set the value of a symbol to an expression.
264 @item symbol_set_frag
265 @cindex symbol_set_frag
266 Set the frag where a symbol is defined.
268 @item symbol_get_frag
269 @cindex symbol_get_frag
270 Get the frag where a symbol is defined.
272 @item symbol_mark_used
273 @cindex symbol_mark_used
274 Mark a symbol as having been used in an expression.
276 @item symbol_clear_used
277 @cindex symbol_clear_used
278 Clear the mark indicating that a symbol was used in an expression.
281 @cindex symbol_used_p
282 Return whether a symbol was used in an expression.
284 @item symbol_mark_used_in_reloc
285 @cindex symbol_mark_used_in_reloc
286 Mark a symbol as having been used by a relocation.
288 @item symbol_clear_used_in_reloc
289 @cindex symbol_clear_used_in_reloc
290 Clear the mark indicating that a symbol was used in a relocation.
292 @item symbol_used_in_reloc_p
293 @cindex symbol_used_in_reloc_p
294 Return whether a symbol was used in a relocation.
296 @item symbol_mark_mri_common
297 @cindex symbol_mark_mri_common
298 Mark a symbol as an MRI common symbol.
300 @item symbol_clear_mri_common
301 @cindex symbol_clear_mri_common
302 Clear the mark indicating that a symbol is an MRI common symbol.
304 @item symbol_mri_common_p
305 @cindex symbol_mri_common_p
306 Return whether a symbol is an MRI common symbol.
308 @item symbol_mark_written
309 @cindex symbol_mark_written
310 Mark a symbol as having been written.
312 @item symbol_clear_written
313 @cindex symbol_clear_written
314 Clear the mark indicating that a symbol was written.
316 @item symbol_written_p
317 @cindex symbol_written_p
318 Return whether a symbol was written.
320 @item symbol_mark_resolved
321 @cindex symbol_mark_resolved
322 Mark a symbol as having been resolved.
324 @item symbol_resolved_p
325 @cindex symbol_resolved_p
326 Return whether a symbol has been resolved.
328 @item symbol_section_p
329 @cindex symbol_section_p
330 Return whether a symbol is a section symbol.
332 @item symbol_equated_p
333 @cindex symbol_equated_p
334 Return whether a symbol is equated to another symbol.
336 @item symbol_constant_p
337 @cindex symbol_constant_p
338 Return whether a symbol has a constant value, including being an offset within
341 @item symbol_get_bfdsym
342 @cindex symbol_get_bfdsym
343 Return the BFD symbol associated with a symbol.
345 @item symbol_set_bfdsym
346 @cindex symbol_set_bfdsym
347 Set the BFD symbol associated with a symbol.
350 @cindex symbol_get_obj
351 Return a pointer to the @code{OBJ_SYMFIELD_TYPE} field of a symbol.
354 @cindex symbol_set_obj
355 Set the @code{OBJ_SYMFIELD_TYPE} field of a symbol.
358 @cindex symbol_get_tc
359 Return a pointer to the @code{TC_SYMFIELD_TYPE} field of a symbol.
362 @cindex symbol_set_tc
363 Set the @code{TC_SYMFIELD_TYPE} field of a symbol.
367 GAS attempts to store local
368 symbols--symbols which will not be written to the output file--using a
369 different structure, @code{struct local_symbol}. This structure can only
370 represent symbols whose value is an offset within a frag.
372 Code outside of the symbol handler will always deal with @code{symbolS}
373 structures and use the accessor functions. The accessor functions correctly
374 deal with local symbols. @code{struct local_symbol} is much smaller than
375 @code{symbolS} (which also automatically creates a bfd @code{asymbol}
376 structure), so this saves space when assembling large files.
378 The first field of @code{symbolS} is @code{bsym}, the pointer to the BFD
379 symbol. The first field of @code{struct local_symbol} is a pointer which is
380 always set to NULL. This is how the symbol accessor functions can distinguish
381 local symbols from ordinary symbols. The symbol accessor functions
382 automatically convert a local symbol into an ordinary symbol when necessary.
385 @subsection Expressions
386 @cindex internals, expressions
387 @cindex expressions, internal
388 @cindex expressionS structure
390 Expressions are stored in an @code{expressionS} structure. The structure is
391 defined in @file{expr.h}.
394 The macro @code{expression} will create an @code{expressionS} structure based
395 on the text found at the global variable @code{input_line_pointer}.
397 @cindex make_expr_symbol
398 @cindex expr_symbol_where
399 A single @code{expressionS} structure can represent a single operation.
400 Complex expressions are formed by creating @dfn{expression symbols} and
401 combining them in @code{expressionS} structures. An expression symbol is
402 created by calling @code{make_expr_symbol}. An expression symbol should
403 naturally never appear in a symbol table, and the implementation of
404 @code{S_IS_LOCAL} (@pxref{Symbols}) reflects that. The function
405 @code{expr_symbol_where} returns non-zero if a symbol is an expression symbol,
406 and also returns the file and line for the expression which caused it to be
409 The @code{expressionS} structure has two symbol fields, a number field, an
410 operator field, and a field indicating whether the number is unsigned.
412 The operator field is of type @code{operatorT}, and describes how to interpret
413 the other fields; see the definition in @file{expr.h} for the possibilities.
415 An @code{operatorT} value of @code{O_big} indicates either a floating point
416 number, stored in the global variable @code{generic_floating_point_number}, or
417 an integer too large to store in an @code{offsetT} type, stored in the global
418 array @code{generic_bignum}. This rather inflexible approach makes it
419 impossible to use floating point numbers or large expressions in complex
424 @cindex internals, fixups
426 @cindex fixS structure
428 A @dfn{fixup} is basically anything which can not be resolved in the first
429 pass. Sometimes a fixup can be resolved by the end of the assembly; if not,
430 the fixup becomes a relocation entry in the object file.
434 A fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both
435 take a frag (@pxref{Frags}), a position within the frag, a size, an indication
436 of whether the fixup is PC relative, and a type.
437 The type is nominally a @code{bfd_reloc_code_real_type}, but several
438 targets use other type codes to represent fixups that can not be described as
441 The @code{fixS} structure has a number of fields, several of which are obsolete
442 or are only used by a particular target. The important fields are:
446 The frag (@pxref{Frags}) this fixup is in.
449 The location within the frag where the fixup occurs.
452 The symbol this fixup is against. Typically, the value of this symbol is added
453 into the object contents. This may be NULL.
456 The value of this symbol is subtracted from the object contents. This is
460 A number which is added into the fixup.
463 Some CPU backends use this field to convey information between
464 @code{md_apply_fix} and @code{tc_gen_reloc}. The machine independent code does
468 The next fixup in the section.
471 The type of the fixup.
474 The size of the fixup. This is mostly used for error checking.
477 Whether the fixup is PC relative.
480 Non-zero if the fixup has been applied, and no relocation entry needs to be
485 The file and line where the fixup was created.
488 This has the type @code{TC_FIX_TYPE}, and is only defined if the target defines
494 @cindex internals, frags
496 @cindex fragS structure.
498 The @code{fragS} structure is defined in @file{as.h}. Each frag represents a
499 portion of the final object file. As GAS reads the source file, it creates
500 frags to hold the data that it reads. At the end of the assembly the frags and
501 fixups are processed to produce the final contents.
505 The address of the frag. This is not set until the assembler rescans the list
506 of all frags after the entire input file is parsed. The function
507 @code{relax_segment} fills in this field.
510 Pointer to the next frag in this (sub)section.
513 Fixed number of characters we know we're going to emit to the output file. May
517 Variable number of characters we may output, after the initial @code{fr_fix}
518 characters. May be zero.
521 The interpretation of this field is controlled by @code{fr_type}. Generally,
522 if @code{fr_var} is non-zero, this is a repeat count: the @code{fr_var}
523 characters are output @code{fr_offset} times.
526 Holds line number info when an assembler listing was requested.
529 Relaxation state. This field indicates the interpretation of @code{fr_offset},
530 @code{fr_symbol} and the variable-length tail of the frag, as well as the
531 treatment it gets in various phases of processing. It does not affect the
532 initial @code{fr_fix} characters; they are always supposed to be output
533 verbatim (fixups aside). See below for specific values this field can have.
536 Relaxation substate. If the macro @code{md_relax_frag} isn't defined, this is
537 assumed to be an index into @code{TC_GENERIC_RELAX_TABLE} for the generic
538 relaxation code to process (@pxref{Relaxation}). If @code{md_relax_frag} is
539 defined, this field is available for any use by the CPU-specific code.
542 This normally indicates the symbol to use when relaxing the frag according to
546 Points to the lowest-addressed byte of the opcode, for use in relaxation.
549 Target specific fragment data of type TC_FRAG_TYPE.
550 Only present if @code{TC_FRAG_TYPE} is defined.
554 The file and line where this frag was last modified.
557 Declared as a one-character array, this last field grows arbitrarily large to
558 hold the actual contents of the frag.
561 These are the possible relaxation states, provided in the enumeration type
562 @code{relax_stateT}, and the interpretations they represent for the other
568 The start of the following frag should be aligned on some boundary. In this
569 frag, @code{fr_offset} is the logarithm (base 2) of the alignment in bytes.
570 (For example, if alignment on an 8-byte boundary were desired, @code{fr_offset}
571 would have a value of 3.) The variable characters indicate the fill pattern to
572 be used. The @code{fr_subtype} field holds the maximum number of bytes to skip
573 when doing this alignment. If more bytes are needed, the alignment is not
574 done. An @code{fr_subtype} value of 0 means no maximum, which is the normal
575 case. Target backends can use @code{rs_align_code} to handle certain types of
576 alignment differently.
579 This indicates that ``broken word'' processing should be done (@pxref{Broken
580 words}). If broken word processing is not necessary on the target machine,
581 this enumerator value will not be defined.
584 This state is used to implement exception frame optimizations. The
585 @code{fr_symbol} is an expression symbol for the subtraction which may be
586 relaxed. The @code{fr_opcode} field holds the frag for the preceding command
587 byte. The @code{fr_offset} field holds the offset within that frag. The
588 @code{fr_subtype} field is used during relaxation to hold the current size of
592 The variable characters are to be repeated @code{fr_offset} times. If
593 @code{fr_offset} is 0, this frag has a length of @code{fr_fix}. Most frags
597 This state is used to implement the DWARF ``little endian base 128''
598 variable length number format. The @code{fr_symbol} is always an expression
599 symbol, as constant expressions are emitted directly. The @code{fr_offset}
600 field is used during relaxation to hold the previous size of the number so
601 that we can determine if the fragment changed size.
603 @item rs_machine_dependent
604 Displacement relaxation is to be done on this frag. The target is indicated by
605 @code{fr_symbol} and @code{fr_offset}, and @code{fr_subtype} indicates the
606 particular machine-specific addressing mode desired. @xref{Relaxation}.
609 The start of the following frag should be pushed back to some specific offset
610 within the section. (Some assemblers use the value as an absolute address; GAS
611 does not handle final absolute addresses, but rather requires that the linker
612 set them.) The offset is given by @code{fr_symbol} and @code{fr_offset}; one
613 character from the variable-length tail is used as the fill character.
616 @cindex frchainS structure
617 A chain of frags is built up for each subsection. The data structure
618 describing a chain is called a @code{frchainS}, and contains the following
623 Points to the first frag in the chain. May be NULL if there are no frags in
626 Points to the last frag in the chain, or NULL if there are none.
628 Next in the list of @code{frchainS} structures.
630 Indicates the section this frag chain belongs to.
632 Subsection (subsegment) number of this frag chain.
633 @item fix_root, fix_tail
634 Point to first and last @code{fixS} structures associated with this subsection.
636 Not currently used. Intended to be used for frag allocation for this
637 subsection. This should reduce frag generation caused by switching sections.
639 The current frag for this subsegment.
642 A @code{frchainS} corresponds to a subsection; each section has a list of
643 @code{frchainS} records associated with it. In most cases, only one subsection
644 of each section is used, so the list will only be one element long, but any
645 processing of frag chains should be prepared to deal with multiple chains per
648 After the input files have been completely processed, and no more frags are to
649 be generated, the frag chains are joined into one per section for further
650 processing. After this point, it is safe to operate on one chain per section.
652 The assembler always has a current frag, named @code{frag_now}. More space is
653 allocated for the current frag using the @code{frag_more} function; this
654 returns a pointer to the amount of requested space. The function
655 @code{frag_room} says by how much the current frag can be extended.
656 Relaxing is done using variant frags allocated by @code{frag_var}
657 or @code{frag_variant} (@pxref{Relaxation}).
660 @section What GAS does when it runs
661 @cindex internals, overview
663 This is a quick look at what an assembler run looks like.
667 The assembler initializes itself by calling various init routines.
670 For each source file, the @code{read_a_source_file} function reads in the file
671 and parses it. The global variable @code{input_line_pointer} points to the
672 current text; it is guaranteed to be correct up to the end of the line, but not
676 For each line, the assembler passes labels to the @code{colon} function, and
677 isolates the first word. If it looks like a pseudo-op, the word is looked up
678 in the pseudo-op hash table @code{po_hash} and dispatched to a pseudo-op
679 routine. Otherwise, the target dependent @code{md_assemble} routine is called
680 to parse the instruction.
683 When pseudo-ops or instructions output data, they add it to a frag, calling
684 @code{frag_more} to get space to store it in.
687 Pseudo-ops and instructions can also output fixups created by @code{fix_new} or
691 For certain targets, instructions can create variant frags which are used to
692 store relaxation information (@pxref{Relaxation}).
695 When the input file is finished, the @code{write_object_file} routine is
696 called. It assigns addresses to all the frags (@code{relax_segment}), resolves
697 all the fixups (@code{fixup_segment}), resolves all the symbol values (using
698 @code{resolve_symbol_value}), and finally writes out the file.
705 Each GAS target specifies two main things: the CPU file and the object format
706 file. Two main switches in the @file{configure.in} file handle this. The
707 first switches on CPU type to set the shell variable @code{cpu_type}. The
708 second switches on the entire target to set the shell variable @code{fmt}.
710 The configure script uses the value of @code{cpu_type} to select two files in
711 the @file{config} directory: @file{tc-@var{CPU}.c} and @file{tc-@var{CPU}.h}.
712 The configuration process will create a file named @file{targ-cpu.h} in the
713 build directory which includes @file{tc-@var{CPU}.h}.
715 The configure script also uses the value of @code{fmt} to select two files:
716 @file{obj-@var{fmt}.c} and @file{obj-@var{fmt}.h}. The configuration process
717 will create a file named @file{obj-format.h} in the build directory which
718 includes @file{obj-@var{fmt}.h}.
720 You can also set the emulation in the configure script by setting the @code{em}
721 variable. Normally the default value of @samp{generic} is fine. The
722 configuration process will create a file named @file{targ-env.h} in the build
723 directory which includes @file{te-@var{em}.h}.
725 There is a special case for COFF. For historical reason, the GNU COFF
726 assembler doesn't follow the documented behavior on certain debug symbols for
727 the compatibility with other COFF assemblers. A port can define
728 @code{STRICTCOFF} in the configure script to make the GNU COFF assembler
729 to follow the documented behavior.
731 Porting GAS to a new CPU requires writing the @file{tc-@var{CPU}} files.
732 Porting GAS to a new object file format requires writing the
733 @file{obj-@var{fmt}} files. There is sometimes some interaction between these
734 two files, but it is normally minimal.
736 The best approach is, of course, to copy existing files. The documentation
737 below assumes that you are looking at existing files to see usage details.
739 These interfaces have grown over time, and have never been carefully thought
740 out or designed. Nothing about the interfaces described here is cast in stone.
741 It is possible that they will change from one version of the assembler to the
742 next. Also, new macros are added all the time as they are needed.
745 * CPU backend:: Writing a CPU backend
746 * Object format backend:: Writing an object format backend
747 * Emulations:: Writing emulation files
751 @subsection Writing a CPU backend
753 @cindex @file{tc-@var{CPU}}
755 The CPU backend files are the heart of the assembler. They are the only parts
756 of the assembler which actually know anything about the instruction set of the
759 You must define a reasonably small list of macros and functions in the CPU
760 backend files. You may define a large number of additional macros in the CPU
761 backend files, not all of which are documented here. You must, of course,
762 define macros in the @file{.h} file, which is included by every assembler
763 source file. You may define the functions as macros in the @file{.h} file, or
764 as functions in the @file{.c} file.
769 By convention, you should define this macro in the @file{.h} file. For
770 example, @file{tc-m68k.h} defines @code{TC_M68K}. You might have to use this
771 if it is necessary to add CPU specific code to the object format file.
774 This macro is the BFD target name to use when creating the output file. This
775 will normally depend upon the @code{OBJ_@var{FMT}} macro.
778 This macro is the BFD architecture to pass to @code{bfd_set_arch_mach}.
781 This macro is the BFD machine number to pass to @code{bfd_set_arch_mach}. If
782 it is not defined, GAS will use 0.
784 @item TARGET_BYTES_BIG_ENDIAN
785 You should define this macro to be non-zero if the target is big endian, and
786 zero if the target is little endian.
790 @itemx md_longopts_size
791 @itemx md_parse_option
793 @itemx md_after_parse_args
796 @cindex md_longopts_size
797 @cindex md_parse_option
798 @cindex md_show_usage
799 @cindex md_after_parse_args
800 GAS uses these variables and functions during option processing.
801 @code{md_shortopts} is a @code{const char *} which GAS adds to the machine
802 independent string passed to @code{getopt}. @code{md_longopts} is a
803 @code{struct option []} which GAS adds to the machine independent long options
804 passed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in
805 @file{as.h}, as the start of a set of long option indices, if necessary.
806 @code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}.
808 GAS will call @code{md_parse_option} whenever @code{getopt} returns an
809 unrecognized code, presumably indicating a special code value which appears in
810 @code{md_longopts}. This function should return non-zero if it handled the
811 option and zero otherwise. There is no need to print a message about an option
812 not being recognised. This will be handled by the generic code.
814 GAS will call @code{md_show_usage} when a usage message is printed; it should
815 print a description of the machine specific options. @code{md_after_pase_args},
816 if defined, is called after all options are processed, to let the backend
817 override settings done by the generic option parsing.
821 GAS will call this function at the start of the assembly, after the command
822 line arguments have been parsed and all the machine independent initializations
827 If you define this macro, GAS will call it at the end of each input file.
831 GAS will call this function for each input line which does not contain a
832 pseudo-op. The argument is a null terminated string. The function should
833 assemble the string as an instruction with operands. Normally
834 @code{md_assemble} will do this by calling @code{frag_more} and writing out
835 some bytes (@pxref{Frags}). @code{md_assemble} will call @code{fix_new} to
836 create fixups as needed (@pxref{Fixups}). Targets which need to do special
837 purpose relaxation will call @code{frag_var}.
839 @item md_pseudo_table
840 @cindex md_pseudo_table
841 This is a const array of type @code{pseudo_typeS}. It is a mapping from
842 pseudo-op names to functions. You should use this table to implement
843 pseudo-ops which are specific to the CPU.
845 @item tc_conditional_pseudoop
846 @cindex tc_conditional_pseudoop
847 If this macro is defined, GAS will call it with a @code{pseudo_typeS} argument.
848 It should return non-zero if the pseudo-op is a conditional which controls
849 whether code is assembled, such as @samp{.if}. GAS knows about the normal
850 conditional pseudo-ops, and you should normally not have to define this macro.
853 @cindex comment_chars
854 This is a null terminated @code{const char} array of characters which start a
857 @item tc_comment_chars
858 @cindex tc_comment_chars
859 If this macro is defined, GAS will use it instead of @code{comment_chars}.
861 @item tc_symbol_chars
862 @cindex tc_symbol_chars
863 If this macro is defined, it is a pointer to a null terminated list of
864 characters which may appear in an operand. GAS already assumes that all
865 alphanumberic characters, and @samp{$}, @samp{.}, and @samp{_} may appear in an
866 operand (see @samp{symbol_chars} in @file{app.c}). This macro may be defined
867 to treat additional characters as appearing in an operand. This affects the
868 way in which GAS removes whitespace before passing the string to
871 @item line_comment_chars
872 @cindex line_comment_chars
873 This is a null terminated @code{const char} array of characters which start a
874 comment when they appear at the start of a line.
876 @item line_separator_chars
877 @cindex line_separator_chars
878 This is a null terminated @code{const char} array of characters which separate
879 lines (null and newline are such characters by default, and need not be
880 listed in this array). Note that line_separator_chars do not separate lines
881 if found in a comment, such as after a character in line_comment_chars or
886 This is a null terminated @code{const char} array of characters which may be
887 used as the exponent character in a floating point number. This is normally
892 This is a null terminated @code{const char} array of characters which may be
893 used to indicate a floating point constant. A zero followed by one of these
894 characters is assumed to be followed by a floating point number; thus they
895 operate the way that @code{0x} is used to indicate a hexadecimal constant.
896 Usually this includes @samp{r} and @samp{f}.
900 You may define this macro to the lexical type of the @kbd{@@} character. The
903 Lexical types are a combination of @code{LEX_NAME} and @code{LEX_BEGIN_NAME},
904 both defined in @file{read.h}. @code{LEX_NAME} indicates that the character
905 may appear in a name. @code{LEX_BEGIN_NAME} indicates that the character may
906 appear at the beginning of a name.
910 You may define this macro to the lexical type of the brace characters @kbd{@{},
911 @kbd{@}}, @kbd{[}, and @kbd{]}. The default value is zero.
915 You may define this macro to the lexical type of the @kbd{%} character. The
916 default value is zero.
920 You may define this macro to the lexical type of the @kbd{?} character. The
921 default value it zero.
925 You may define this macro to the lexical type of the @kbd{$} character. The
926 default value is @code{LEX_NAME | LEX_BEGIN_NAME}.
928 @item NUMBERS_WITH_SUFFIX
929 @cindex NUMBERS_WITH_SUFFIX
930 When this macro is defined to be non-zero, the parser allows the radix of a
931 constant to be indicated with a suffix. Valid suffixes are binary (B),
932 octal (Q), and hexadecimal (H). Case is not significant.
934 @item SINGLE_QUOTE_STRINGS
935 @cindex SINGLE_QUOTE_STRINGS
936 If you define this macro, GAS will treat single quotes as string delimiters.
937 Normally only double quotes are accepted as string delimiters.
939 @item NO_STRING_ESCAPES
940 @cindex NO_STRING_ESCAPES
941 If you define this macro, GAS will not permit escape sequences in a string.
943 @item ONLY_STANDARD_ESCAPES
944 @cindex ONLY_STANDARD_ESCAPES
945 If you define this macro, GAS will warn about the use of nonstandard escape
946 sequences in a string.
948 @item md_start_line_hook
949 @cindex md_start_line_hook
950 If you define this macro, GAS will call it at the start of each line.
952 @item LABELS_WITHOUT_COLONS
953 @cindex LABELS_WITHOUT_COLONS
954 If you define this macro, GAS will assume that any text at the start of a line
955 is a label, even if it does not have a colon.
958 @itemx TC_START_LABEL_WITHOUT_COLON
959 @cindex TC_START_LABEL
960 You may define this macro to control what GAS considers to be a label. The
961 default definition is to accept any name followed by a colon character.
963 @item TC_START_LABEL_WITHOUT_COLON
964 @cindex TC_START_LABEL_WITHOUT_COLON
965 Same as TC_START_LABEL, but should be used instead of TC_START_LABEL when
966 LABELS_WITHOUT_COLONS is defined.
969 @cindex TC_FAKE_LABEL
970 You may define this macro to control what GAS considers to be a fake
971 label. The default fake label is FAKE_LABEL_NAME.
974 @cindex NO_PSEUDO_DOT
975 If you define this macro, GAS will not require pseudo-ops to start with a
978 @item TC_EQUAL_IN_INSN
979 @cindex TC_EQUAL_IN_INSN
980 If you define this macro, it should return nonzero if the instruction is
981 permitted to contain an @kbd{=} character. GAS will call it with two
982 arguments, the character before the @kbd{=} character, and the value of
983 the string preceding the equal sign. GAS uses this macro to decide if a
984 @kbd{=} is an assignment or an instruction.
987 @cindex TC_EOL_IN_INSN
988 If you define this macro, it should return nonzero if the current input line
989 pointer should be treated as the end of a line.
991 @item TC_CASE_SENSITIVE
992 @cindex TC_CASE_SENSITIVE
993 Define this macro if instruction mnemonics and pseudos are case sensitive.
994 The default is to have it undefined giving case insensitive names.
997 @cindex md_parse_name
998 If this macro is defined, GAS will call it for any symbol found in an
999 expression. You can define this to handle special symbols in a special way.
1000 If a symbol always has a certain value, you should normally enter it in the
1001 symbol table, perhaps using @code{reg_section}.
1003 @item md_undefined_symbol
1004 @cindex md_undefined_symbol
1005 GAS will call this function when a symbol table lookup fails, before it
1006 creates a new symbol. Typically this would be used to supply symbols whose
1007 name or value changes dynamically, possibly in a context sensitive way.
1008 Predefined symbols with fixed values, such as register names or condition
1009 codes, are typically entered directly into the symbol table when @code{md_begin}
1010 is called. One argument is passed, a @code{char *} for the symbol.
1014 GAS will call this function with one argument, an @code{expressionS}
1015 pointer, for any expression that can not be recognized. When the function
1016 is called, @code{input_line_pointer} will point to the start of the
1019 @item tc_unrecognized_line
1020 @cindex tc_unrecognized_line
1021 If you define this macro, GAS will call it when it finds a line that it can not
1026 You may define this macro to handle an alignment directive. GAS will call it
1027 when the directive is seen in the input file. For example, the i386 backend
1028 uses this to generate efficient nop instructions of varying lengths, depending
1029 upon the number of bytes that the alignment will skip.
1032 @cindex HANDLE_ALIGN
1033 You may define this macro to do special handling for an alignment directive.
1034 GAS will call it at the end of the assembly.
1036 @item TC_IMPLICIT_LCOMM_ALIGNMENT (@var{size}, @var{p2var})
1037 @cindex TC_IMPLICIT_LCOMM_ALIGNMENT
1038 An @code{.lcomm} directive with no explicit alignment parameter will use this
1039 macro to set @var{p2var} to the alignment that a request for @var{size} bytes
1040 will have. The alignment is expressed as a power of two. If no alignment
1041 should take place, the macro definition should do nothing. Some targets define
1042 a @code{.bss} directive that is also affected by this macro. The default
1043 definition will set @var{p2var} to the truncated power of two of sizes up to
1046 @item md_flush_pending_output
1047 @cindex md_flush_pending_output
1048 If you define this macro, GAS will call it each time it skips any space because of a
1049 space filling or alignment or data allocation pseudo-op.
1051 @item TC_PARSE_CONS_EXPRESSION
1052 @cindex TC_PARSE_CONS_EXPRESSION
1053 You may define this macro to parse an expression used in a data allocation
1054 pseudo-op such as @code{.word}. You can use this to recognize relocation
1055 directives that may appear in such directives.
1057 @item BITFIELD_CONS_EXPRESSION
1058 @cindex BITFIELD_CONS_EXPRESSION
1059 If you define this macro, GAS will recognize bitfield instructions in data
1060 allocation pseudo-ops, as used on the i960.
1062 @item REPEAT_CONS_EXPRESSION
1063 @cindex REPEAT_CONS_EXPRESSION
1064 If you define this macro, GAS will recognize repeat counts in data allocation
1065 pseudo-ops, as used on the MIPS.
1068 @cindex md_cons_align
1069 You may define this macro to do any special alignment before a data allocation
1072 @item TC_CONS_FIX_NEW
1073 @cindex TC_CONS_FIX_NEW
1074 You may define this macro to generate a fixup for a data allocation pseudo-op.
1076 @item TC_ADDRESS_BYTES
1077 @cindex TC_ADDRESS_BYTES
1078 Define this macro to specify the number of bytes used to store an address.
1079 Used to implement @code{dc.a}. The target must have a reloc for this size.
1081 @item TC_INIT_FIX_DATA (@var{fixp})
1082 @cindex TC_INIT_FIX_DATA
1083 A C statement to initialize the target specific fields of fixup @var{fixp}.
1084 These fields are defined with the @code{TC_FIX_TYPE} macro.
1086 @item TC_FIX_DATA_PRINT (@var{stream}, @var{fixp})
1087 @cindex TC_FIX_DATA_PRINT
1088 A C statement to output target specific debugging information for
1089 fixup @var{fixp} to @var{stream}. This macro is called by @code{print_fixup}.
1091 @item TC_FRAG_INIT (@var{fragp})
1092 @cindex TC_FRAG_INIT
1093 A C statement to initialize the target specific fields of frag @var{fragp}.
1094 These fields are defined with the @code{TC_FRAG_TYPE} macro.
1096 @item md_number_to_chars
1097 @cindex md_number_to_chars
1098 This should just call either @code{number_to_chars_bigendian} or
1099 @code{number_to_chars_littleendian}, whichever is appropriate. On targets like
1100 the MIPS which support options to change the endianness, which function to call
1101 is a runtime decision. On other targets, @code{md_number_to_chars} can be a
1104 @item md_atof (@var{type},@var{litP},@var{sizeP})
1106 This function is called to convert an ASCII string into a floating point value
1107 in format used by the CPU. It takes three arguments. The first is @var{type}
1108 which is a byte describing the type of floating point number to be created.
1109 Possible values are @var{'f'} or @var{'s'} for single precision, @var{'d'} or
1110 @var{'r'} for double precision and @var{'x'} or @var{'p'} for extended
1111 precision. Either lower or upper case versions of these letters can be used.
1113 The second parameter is @var{litP} which is a pointer to a byte array where the
1114 converted value should be stored. The third argument is @var{sizeP}, which is
1115 a pointer to a integer that should be filled in with the number of
1116 @var{LITTLENUM}s emitted into the byte array. (@var{LITTLENUM} is defined in
1117 gas/bignum.h). The function should return NULL upon success or an error string
1120 @item TC_LARGEST_EXPONENT_IS_NORMAL
1121 @cindex TC_LARGEST_EXPONENT_IS_NORMAL (@var{precision})
1122 This macro is used only by @file{atof-ieee.c}. It should evaluate to true
1123 if floats of the given precision use the largest exponent for normal numbers
1124 instead of NaNs and infinities. @var{precision} is @samp{F_PRECISION} for
1125 single precision, @samp{D_PRECISION} for double precision, or
1126 @samp{X_PRECISION} for extended double precision.
1128 The macro has a default definition which returns 0 for all cases.
1130 @item WORKING_DOT_WORD
1131 @itemx md_short_jump_size
1132 @itemx md_long_jump_size
1133 @itemx md_create_short_jump
1134 @itemx md_create_long_jump
1135 @itemx TC_CHECK_ADJUSTED_BROKEN_DOT_WORD
1136 @cindex WORKING_DOT_WORD
1137 @cindex md_short_jump_size
1138 @cindex md_long_jump_size
1139 @cindex md_create_short_jump
1140 @cindex md_create_long_jump
1141 @cindex TC_CHECK_ADJUSTED_BROKEN_DOT_WORD
1142 If @code{WORKING_DOT_WORD} is defined, GAS will not do broken word processing
1143 (@pxref{Broken words}). Otherwise, you should set @code{md_short_jump_size} to
1144 the size of a short jump (a jump that is just long enough to jump around a
1145 number of long jumps) and @code{md_long_jump_size} to the size of a long jump
1146 (a jump that can go anywhere in the function). You should define
1147 @code{md_create_short_jump} to create a short jump around a number of long
1148 jumps, and define @code{md_create_long_jump} to create a long jump.
1149 If defined, the macro TC_CHECK_ADJUSTED_BROKEN_DOT_WORD will be called for each
1150 adjusted word just before the word is output. The macro takes two arguments,
1151 an @code{addressT} with the adjusted word and a pointer to the current
1152 @code{struct broken_word}.
1154 @item md_estimate_size_before_relax
1155 @cindex md_estimate_size_before_relax
1156 This function returns an estimate of the size of a @code{rs_machine_dependent}
1157 frag before any relaxing is done. It may also create any necessary
1161 @cindex md_relax_frag
1162 This macro may be defined to relax a frag. GAS will call this with the
1163 segment, the frag, and the change in size of all previous frags;
1164 @code{md_relax_frag} should return the change in size of the frag.
1167 @item TC_GENERIC_RELAX_TABLE
1168 @cindex TC_GENERIC_RELAX_TABLE
1169 If you do not define @code{md_relax_frag}, you may define
1170 @code{TC_GENERIC_RELAX_TABLE} as a table of @code{relax_typeS} structures. The
1171 machine independent code knows how to use such a table to relax PC relative
1172 references. See @file{tc-m68k.c} for an example. @xref{Relaxation}.
1174 @item md_prepare_relax_scan
1175 @cindex md_prepare_relax_scan
1176 If defined, it is a C statement that is invoked prior to scanning
1179 @item LINKER_RELAXING_SHRINKS_ONLY
1180 @cindex LINKER_RELAXING_SHRINKS_ONLY
1181 If you define this macro, and the global variable @samp{linkrelax} is set
1182 (because of a command line option, or unconditionally in @code{md_begin}), a
1183 @samp{.align} directive will cause extra space to be allocated. The linker can
1184 then discard this space when relaxing the section.
1186 @item TC_LINKRELAX_FIXUP (@var{segT})
1187 @cindex TC_LINKRELAX_FIXUP
1188 If defined, this macro allows control over whether fixups for a
1189 given section will be processed when the @var{linkrelax} variable is
1190 set. The macro is given the N_TYPE bits for the section in its
1191 @var{segT} argument. If the macro evaluates to a non-zero value
1192 then the fixups will be converted into relocs, otherwise they will
1193 be passed to @var{md_apply_fix} as normal.
1195 @item md_convert_frag
1196 @cindex md_convert_frag
1197 GAS will call this for each rs_machine_dependent fragment.
1198 The instruction is completed using the data from the relaxation pass.
1199 It may also create any necessary relocations.
1202 @item TC_FINALIZE_SYMS_BEFORE_SIZE_SEG
1203 @cindex TC_FINALIZE_SYMS_BEFORE_SIZE_SEG
1204 Specifies the value to be assigned to @code{finalize_syms} before the function
1205 @code{size_segs} is called. Since @code{size_segs} calls @code{cvt_frag_to_fill}
1206 which can call @code{md_convert_frag}, this constant governs whether the symbols
1207 accessed in @code{md_convert_frag} will be fully resolved. In particular it
1208 governs whether local symbols will have been resolved, and had their frag
1209 information removed. Depending upon the processing performed by
1210 @code{md_convert_frag} the frag information may or may not be necessary, as may
1211 the resolved values of the symbols. The default value is 1.
1213 @item TC_VALIDATE_FIX (@var{fixP}, @var{seg}, @var{skip})
1214 @cindex TC_VALIDATE_FIX
1215 This macro is evaluated for each fixup (when @var{linkrelax} is not set).
1216 It may be used to change the fixup in @code{struct fix *@var{fixP}} before
1217 the generic code sees it, or to fully process the fixup. In the latter case,
1218 a @code{goto @var{skip}} will bypass the generic code.
1220 @item md_apply_fix (@var{fixP}, @var{valP}, @var{seg})
1221 @cindex md_apply_fix
1222 GAS will call this for each fixup that passes the @code{TC_VALIDATE_FIX} test
1223 when @var{linkrelax} is not set. It should store the correct value in the
1224 object file. @code{struct fix *@var{fixP}} is the fixup @code{md_apply_fix}
1225 is operating on. @code{valueT *@var{valP}} is the value to store into the
1226 object files, or at least is the generic code's best guess. Specifically,
1227 *@var{valP} is the value of the fixup symbol, perhaps modified by
1228 @code{MD_APPLY_SYM_VALUE}, plus @code{@var{fixP}->fx_offset} (symbol addend),
1229 less @code{MD_PCREL_FROM_SECTION} for pc-relative fixups.
1230 @code{segT @var{seg}} is the section the fix is in.
1231 @code{fixup_segment} performs a generic overflow check on *@var{valP} after
1232 @code{md_apply_fix} returns. If the overflow check is relevant for the target
1233 machine, then @code{md_apply_fix} should modify *@var{valP}, typically to the
1234 value stored in the object file.
1236 @item TC_FORCE_RELOCATION (@var{fix})
1237 @cindex TC_FORCE_RELOCATION
1238 If this macro returns non-zero, it guarantees that a relocation will be emitted
1239 even when the value can be resolved locally, as @code{fixup_segment} tries to
1240 reduce the number of relocations emitted. For example, a fixup expression
1241 against an absolute symbol will normally not require a reloc. If undefined,
1242 a default of @w{@code{(S_FORCE_RELOC ((@var{fix})->fx_addsy))}} is used.
1244 @item TC_FORCE_RELOCATION_ABS (@var{fix})
1245 @cindex TC_FORCE_RELOCATION_ABS
1246 Like @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against an
1247 absolute symbol. If undefined, @code{TC_FORCE_RELOCATION} will be used.
1249 @item TC_FORCE_RELOCATION_LOCAL (@var{fix})
1250 @cindex TC_FORCE_RELOCATION_LOCAL
1251 Like @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against a
1252 symbol in the current section. If undefined, fixups that are not
1253 @code{fx_pcrel} or @code{fx_plt} or for which @code{TC_FORCE_RELOCATION}
1254 returns non-zero, will emit relocs.
1256 @item TC_FORCE_RELOCATION_SUB_SAME (@var{fix}, @var{seg})
1257 @cindex TC_FORCE_RELOCATION_SUB_SAME
1258 This macro controls resolution of fixup expressions involving the
1259 difference of two symbols in the same section. If this macro returns zero,
1260 the subtrahend will be resolved and @code{fx_subsy} set to @code{NULL} for
1261 @code{md_apply_fix}. If undefined, the default of
1262 @w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will
1265 @item TC_FORCE_RELOCATION_SUB_ABS (@var{fix})
1266 @cindex TC_FORCE_RELOCATION_SUB_ABS
1267 Like @code{TC_FORCE_RELOCATION_SUB_SAME}, but used when the subtrahend is an
1268 absolute symbol. If the macro is undefined a default of @code{0} is used.
1270 @item TC_FORCE_RELOCATION_SUB_LOCAL (@var{fix})
1271 @cindex TC_FORCE_RELOCATION_SUB_LOCAL
1272 Like @code{TC_FORCE_RELOCATION_SUB_ABS}, but the subtrahend is a symbol in the
1273 same section as the fixup.
1275 @item TC_VALIDATE_FIX_SUB (@var{fix})
1276 @cindex TC_VALIDATE_FIX_SUB
1277 This macro is evaluated for any fixup with a @code{fx_subsy} that
1278 @code{fixup_segment} cannot reduce to a number. If the macro returns
1279 @code{false} an error will be reported.
1281 @item MD_APPLY_SYM_VALUE (@var{fix})
1282 @cindex MD_APPLY_SYM_VALUE
1283 This macro controls whether the symbol value becomes part of the value passed
1284 to @code{md_apply_fix}. If the macro is undefined, or returns non-zero, the
1285 symbol value will be included. For ELF, a suitable definition might simply be
1286 @code{0}, because ELF relocations don't include the symbol value in the addend.
1288 @item S_FORCE_RELOC (@var{sym}, @var{strict})
1289 @cindex S_FORCE_RELOC
1290 This function returns true for symbols
1291 that should not be reduced to section symbols or eliminated from expressions,
1292 because they may be overridden by the linker. ie. for symbols that are
1293 undefined or common, and when @var{strict} is set, weak, or global (for ELF
1294 assemblers that support ELF shared library linking semantics).
1296 @item EXTERN_FORCE_RELOC
1297 @cindex EXTERN_FORCE_RELOC
1298 This macro controls whether @code{S_FORCE_RELOC} returns true for global
1299 symbols. If undefined, the default is @code{true} for ELF assemblers, and
1300 @code{false} for non-ELF.
1303 @cindex tc_gen_reloc
1304 GAS will call this to generate a reloc. GAS will pass
1305 the resulting reloc to @code{bfd_install_relocation}. This currently works
1306 poorly, as @code{bfd_install_relocation} often does the wrong thing, and
1307 instances of @code{tc_gen_reloc} have been written to work around the problems,
1308 which in turns makes it difficult to fix @code{bfd_install_relocation}.
1310 @item RELOC_EXPANSION_POSSIBLE
1311 @cindex RELOC_EXPANSION_POSSIBLE
1312 If you define this macro, it means that @code{tc_gen_reloc} may return multiple
1313 relocation entries for a single fixup. In this case, the return value of
1314 @code{tc_gen_reloc} is a pointer to a null terminated array.
1316 @item MAX_RELOC_EXPANSION
1317 @cindex MAX_RELOC_EXPANSION
1318 You must define this if @code{RELOC_EXPANSION_POSSIBLE} is defined; it
1319 indicates the largest number of relocs which @code{tc_gen_reloc} may return for
1322 @item tc_fix_adjustable
1323 @cindex tc_fix_adjustable
1324 You may define this macro to indicate whether a fixup against a locally defined
1325 symbol should be adjusted to be against the section symbol. It should return a
1326 non-zero value if the adjustment is acceptable.
1328 @item MD_PCREL_FROM_SECTION (@var{fixp}, @var{section})
1329 @cindex MD_PCREL_FROM_SECTION
1330 If you define this macro, it should return the position from which the PC
1331 relative adjustment for a PC relative fixup should be made. On many
1332 processors, the base of a PC relative instruction is the next instruction,
1333 so this macro would return the length of an instruction, plus the address of
1334 the PC relative fixup. The latter can be calculated as
1335 @var{fixp}->fx_where + @var{fixp}->fx_frag->fr_address .
1338 @cindex md_pcrel_from
1339 This is the default value of @code{MD_PCREL_FROM_SECTION}. The difference is
1340 that @code{md_pcrel_from} does not take a section argument.
1343 @cindex tc_frob_label
1344 If you define this macro, GAS will call it each time a label is defined.
1346 @item md_section_align
1347 @cindex md_section_align
1348 GAS will call this function for each section at the end of the assembly, to
1349 permit the CPU backend to adjust the alignment of a section. The function
1350 must take two arguments, a @code{segT} for the section and a @code{valueT}
1351 for the size of the section, and return a @code{valueT} for the rounded
1354 @item md_macro_start
1355 @cindex md_macro_start
1356 If defined, GAS will call this macro when it starts to include a macro
1357 expansion. @code{macro_nest} indicates the current macro nesting level, which
1358 includes the one being expanded.
1361 @cindex md_macro_info
1362 If defined, GAS will call this macro after the macro expansion has been
1363 included in the input and after parsing the macro arguments. The single
1364 argument is a pointer to the macro processing's internal representation of the
1365 macro (macro_entry *), which includes expansion of the formal arguments.
1368 @cindex md_macro_end
1369 Complement to md_macro_start. If defined, it is called when finished
1370 processing an inserted macro expansion, just before decrementing macro_nest.
1372 @item DOUBLEBAR_PARALLEL
1373 @cindex DOUBLEBAR_PARALLEL
1374 Affects the preprocessor so that lines containing '||' don't have their
1375 whitespace stripped following the double bar. This is useful for targets that
1376 implement parallel instructions.
1378 @item KEEP_WHITE_AROUND_COLON
1379 @cindex KEEP_WHITE_AROUND_COLON
1380 Normally, whitespace is compressed and removed when, in the presence of the
1381 colon, the adjoining tokens can be distinguished. This option affects the
1382 preprocessor so that whitespace around colons is preserved. This is useful
1383 when colons might be removed from the input after preprocessing but before
1384 assembling, so that adjoining tokens can still be distinguished if there is
1385 whitespace, or concatenated if there is not.
1387 @item tc_frob_section
1388 @cindex tc_frob_section
1389 If you define this macro, GAS will call it for each
1390 section at the end of the assembly.
1392 @item tc_frob_file_before_adjust
1393 @cindex tc_frob_file_before_adjust
1394 If you define this macro, GAS will call it after the symbol values are
1395 resolved, but before the fixups have been changed from local symbols to section
1398 @item tc_frob_symbol
1399 @cindex tc_frob_symbol
1400 If you define this macro, GAS will call it for each symbol. You can indicate
1401 that the symbol should not be included in the object file by defining this
1402 macro to set its second argument to a non-zero value.
1405 @cindex tc_frob_file
1406 If you define this macro, GAS will call it after the symbol table has been
1407 completed, but before the relocations have been generated.
1409 @item tc_frob_file_after_relocs
1410 If you define this macro, GAS will call it after the relocs have been
1413 @item md_post_relax_hook
1414 If you define this macro, GAS will call it after relaxing and sizing the
1417 @item LISTING_HEADER
1418 A string to use on the header line of a listing. The default value is simply
1419 @code{"GAS LISTING"}.
1421 @item LISTING_WORD_SIZE
1422 The number of bytes to put into a word in a listing. This affects the way the
1423 bytes are clumped together in the listing. For example, a value of 2 might
1424 print @samp{1234 5678} where a value of 1 would print @samp{12 34 56 78}. The
1427 @item LISTING_LHS_WIDTH
1428 The number of words of data to print on the first line of a listing for a
1429 particular source line, where each word is @code{LISTING_WORD_SIZE} bytes. The
1432 @item LISTING_LHS_WIDTH_SECOND
1433 Like @code{LISTING_LHS_WIDTH}, but applying to the second and subsequent line
1434 of the data printed for a particular source line. The default value is 1.
1436 @item LISTING_LHS_CONT_LINES
1437 The maximum number of continuation lines to print in a listing for a particular
1438 source line. The default value is 4.
1440 @item LISTING_RHS_WIDTH
1441 The maximum number of characters to print from one line of the input file. The
1442 default value is 100.
1444 @item TC_COFF_SECTION_DEFAULT_ATTRIBUTES
1445 @cindex TC_COFF_SECTION_DEFAULT_ATTRIBUTES
1446 The COFF @code{.section} directive will use the value of this macro to set
1447 a new section's attributes when a directive has no valid flags or when the
1448 flag is @code{w}. The default value of the macro is @code{SEC_LOAD | SEC_DATA}.
1450 @item DWARF2_FORMAT ()
1451 @cindex DWARF2_FORMAT
1452 If you define this, it should return one of @code{dwarf2_format_32bit},
1453 @code{dwarf2_format_64bit}, or @code{dwarf2_format_64bit_irix} to indicate
1454 the size of internal DWARF section offsets and the format of the DWARF initial
1455 length fields. When @code{dwarf2_format_32bit} is returned, the initial
1456 length field will be 4 bytes long and section offsets are 32 bits in size.
1457 For @code{dwarf2_format_64bit} and @code{dwarf2_format_64bit_irix}, section
1458 offsets are 64 bits in size, but the initial length field differs. An 8 byte
1459 initial length is indicated by @code{dwarf2_format_64bit_irix} and
1460 @code{dwarf2_format_64bit} indicates a 12 byte initial length field in
1461 which the first four bytes are 0xffffffff and the next 8 bytes are
1462 the section's length.
1464 If you don't define this, @code{dwarf2_format_32bit} will be used as
1467 This define only affects @code{.debug_info} and @code{.debug_line}
1468 sections generated by the assembler. DWARF 2 sections generated by
1469 other tools will be unaffected by this setting.
1471 @item DWARF2_ADDR_SIZE (@var{bfd})
1472 @cindex DWARF2_ADDR_SIZE
1473 It should return the size of an address, as it should be represented in
1474 debugging info. If you don't define this macro, the default definition uses
1475 the number of bits per address, as defined in @var{bfd}, divided by 8.
1477 @item MD_DEBUG_FORMAT_SELECTOR
1478 @cindex MD_DEBUG_FORMAT_SELECTOR
1479 If defined this macro is the name of a function to be called when the
1480 @samp{--gen-debug} switch is detected on the assembler's command line. The
1481 prototype for the function looks like this:
1484 enum debug_info_type MD_DEBUG_FORMAT_SELECTOR (int * use_gnu_extensions)
1487 The function should return the debug format that is preferred by the CPU
1488 backend. This format will be used when generating assembler specific debug
1493 @node Object format backend
1494 @subsection Writing an object format backend
1495 @cindex object format backend
1496 @cindex @file{obj-@var{fmt}}
1498 As with the CPU backend, the object format backend must define a few things,
1499 and may define some other things. The interface to the object format backend
1500 is generally simpler; most of the support for an object file format consists of
1501 defining a number of pseudo-ops.
1503 The object format @file{.h} file must include @file{targ-cpu.h}.
1506 @item OBJ_@var{format}
1507 @cindex OBJ_@var{format}
1508 By convention, you should define this macro in the @file{.h} file. For
1509 example, @file{obj-elf.h} defines @code{OBJ_ELF}. You might have to use this
1510 if it is necessary to add object file format specific code to the CPU file.
1513 If you define this macro, GAS will call it at the start of the assembly, after
1514 the command line arguments have been parsed and all the machine independent
1515 initializations have been completed.
1518 @cindex obj_app_file
1519 If you define this macro, GAS will invoke it when it sees a @code{.file}
1520 pseudo-op or a @samp{#} line as used by the C preprocessor.
1522 @item OBJ_COPY_SYMBOL_ATTRIBUTES
1523 @cindex OBJ_COPY_SYMBOL_ATTRIBUTES
1524 You should define this macro to copy object format specific information from
1525 one symbol to another. GAS will call it when one symbol is equated to
1528 @item obj_sec_sym_ok_for_reloc
1529 @cindex obj_sec_sym_ok_for_reloc
1530 You may define this macro to indicate that it is OK to use a section symbol in
1531 a relocation entry. If it is not, GAS will define a new symbol at the start
1534 @item EMIT_SECTION_SYMBOLS
1535 @cindex EMIT_SECTION_SYMBOLS
1536 You should define this macro with a zero value if you do not want to include
1537 section symbols in the output symbol table. The default value for this macro
1540 @item obj_adjust_symtab
1541 @cindex obj_adjust_symtab
1542 If you define this macro, GAS will invoke it just before setting the symbol
1543 table of the output BFD. For example, the COFF support uses this macro to
1544 generate a @code{.file} symbol if none was generated previously.
1546 @item SEPARATE_STAB_SECTIONS
1547 @cindex SEPARATE_STAB_SECTIONS
1548 You may define this macro to a nonzero value to indicate that stabs should be
1549 placed in separate sections, as in ELF.
1551 @item INIT_STAB_SECTION
1552 @cindex INIT_STAB_SECTION
1553 You may define this macro to initialize the stabs section in the output file.
1555 @item OBJ_PROCESS_STAB
1556 @cindex OBJ_PROCESS_STAB
1557 You may define this macro to do specific processing on a stabs entry.
1559 @item obj_frob_section
1560 @cindex obj_frob_section
1561 If you define this macro, GAS will call it for each section at the end of the
1564 @item obj_frob_file_before_adjust
1565 @cindex obj_frob_file_before_adjust
1566 If you define this macro, GAS will call it after the symbol values are
1567 resolved, but before the fixups have been changed from local symbols to section
1570 @item obj_frob_symbol
1571 @cindex obj_frob_symbol
1572 If you define this macro, GAS will call it for each symbol. You can indicate
1573 that the symbol should not be included in the object file by defining this
1574 macro to set its second argument to a non-zero value.
1576 @item obj_set_weak_hook
1577 @cindex obj_set_weak_hook
1578 If you define this macro, @code{S_SET_WEAK} will call it before modifying the
1581 @item obj_clear_weak_hook
1582 @cindex obj_clear_weak_hook
1583 If you define this macro, @code{S_CLEAR_WEAKREFD} will call it after clearning
1584 the @code{weakrefd} flag, but before modifying any other flags.
1587 @cindex obj_frob_file
1588 If you define this macro, GAS will call it after the symbol table has been
1589 completed, but before the relocations have been generated.
1591 @item obj_frob_file_after_relocs
1592 If you define this macro, GAS will call it after the relocs have been
1595 @item SET_SECTION_RELOCS (@var{sec}, @var{relocs}, @var{n})
1596 @cindex SET_SECTION_RELOCS
1597 If you define this, it will be called after the relocations have been set for
1598 the section @var{sec}. The list of relocations is in @var{relocs}, and the
1599 number of relocations is in @var{n}.
1603 @subsection Writing emulation files
1605 Normally you do not have to write an emulation file. You can just use
1606 @file{te-generic.h}.
1608 If you do write your own emulation file, it must include @file{obj-format.h}.
1610 An emulation file will often define @code{TE_@var{EM}}; this may then be used
1611 in other files to change the output.
1617 @dfn{Relaxation} is a generic term used when the size of some instruction or
1618 data depends upon the value of some symbol or other data.
1620 GAS knows to relax a particular type of PC relative relocation using a table.
1621 You can also define arbitrarily complex forms of relaxation yourself.
1624 * Relaxing with a table:: Relaxing with a table
1625 * General relaxing:: General relaxing
1628 @node Relaxing with a table
1629 @subsection Relaxing with a table
1631 If you do not define @code{md_relax_frag}, and you do define
1632 @code{TC_GENERIC_RELAX_TABLE}, GAS will relax @code{rs_machine_dependent} frags
1633 based on the frag subtype and the displacement to some specified target
1634 address. The basic idea is that several machines have different addressing
1635 modes for instructions that can specify different ranges of values, with
1636 successive modes able to access wider ranges, including the entirety of the
1637 previous range. Smaller ranges are assumed to be more desirable (perhaps the
1638 instruction requires one word instead of two or three); if this is not the
1639 case, don't describe the smaller-range, inferior mode.
1641 The @code{fr_subtype} field of a frag is an index into a CPU-specific
1642 relaxation table. That table entry indicates the range of values that can be
1643 stored, the number of bytes that will have to be added to the frag to
1644 accommodate the addressing mode, and the index of the next entry to examine if
1645 the value to be stored is outside the range accessible by the current
1646 addressing mode. The @code{fr_symbol} field of the frag indicates what symbol
1647 is to be accessed; the @code{fr_offset} field is added in.
1649 If the @code{TC_PCREL_ADJUST} macro is defined, which currently should only happen
1650 for the NS32k family, the @code{TC_PCREL_ADJUST} macro is called on the frag to
1651 compute an adjustment to be made to the displacement.
1653 The value fitted by the relaxation code is always assumed to be a displacement
1654 from the current frag. (More specifically, from @code{fr_fix} bytes into the
1657 This seems kinda silly. What about fitting small absolute values? I suppose
1658 @code{md_assemble} is supposed to take care of that, but if the operand is a
1659 difference between symbols, it might not be able to, if the difference was not
1663 The end of the relaxation sequence is indicated by a ``next'' value of 0. This
1664 means that the first entry in the table can't be used.
1666 For some configurations, the linker can do relaxing within a section of an
1667 object file. If call instructions of various sizes exist, the linker can
1668 determine which should be used in each instance, when a symbol's value is
1669 resolved. In order for the linker to avoid wasting space and having to insert
1670 no-op instructions, it must be able to expand or shrink the section contents
1671 while still preserving intra-section references and meeting alignment
1674 For the i960 using b.out format, no expansion is done; instead, each
1675 @samp{.align} directive causes extra space to be allocated, enough that when
1676 the linker is relaxing a section and removing unneeded space, it can discard
1677 some or all of this extra padding and cause the following data to be correctly
1680 For the H8/300, I think the linker expands calls that can't reach, and doesn't
1681 worry about alignment issues; the cpu probably never needs any significant
1682 alignment beyond the instruction size.
1684 The relaxation table type contains these fields:
1687 @item long rlx_forward
1688 Forward reach, must be non-negative.
1689 @item long rlx_backward
1690 Backward reach, must be zero or negative.
1692 Length in bytes of this addressing mode.
1694 Index of the next-longer relax state, or zero if there is no next relax state.
1697 The relaxation is done in @code{relax_segment} in @file{write.c}. The
1698 difference in the length fields between the original mode and the one finally
1699 chosen by the relaxing code is taken as the size by which the current frag will
1700 be increased in size. For example, if the initial relaxing mode has a length
1701 of 2 bytes, and because of the size of the displacement, it gets upgraded to a
1702 mode with a size of 6 bytes, it is assumed that the frag will grow by 4 bytes.
1703 (The initial two bytes should have been part of the fixed portion of the frag,
1704 since it is already known that they will be output.) This growth must be
1705 effected by @code{md_convert_frag}; it should increase the @code{fr_fix} field
1706 by the appropriate size, and fill in the appropriate bytes of the frag.
1707 (Enough space for the maximum growth should have been allocated in the call to
1708 frag_var as the second argument.)
1710 If relocation records are needed, they should be emitted by
1711 @code{md_estimate_size_before_relax}. This function should examine the target
1712 symbol of the supplied frag and correct the @code{fr_subtype} of the frag if
1713 needed. When this function is called, if the symbol has not yet been defined,
1714 it will not become defined later; however, its value may still change if the
1715 section it is in gets relaxed.
1717 Usually, if the symbol is in the same section as the frag (given by the
1718 @var{sec} argument), the narrowest likely relaxation mode is stored in
1719 @code{fr_subtype}, and that's that.
1721 If the symbol is undefined, or in a different section (and therefore movable
1722 to an arbitrarily large distance), the largest available relaxation mode is
1723 specified, @code{fix_new} is called to produce the relocation record,
1724 @code{fr_fix} is increased to include the relocated field (remember, this
1725 storage was allocated when @code{frag_var} was called), and @code{frag_wane} is
1726 called to convert the frag to an @code{rs_fill} frag with no variant part.
1727 Sometimes changing addressing modes may also require rewriting the instruction.
1728 It can be accessed via @code{fr_opcode} or @code{fr_fix}.
1730 If you generate frags separately for the basic insn opcode and any relaxable
1731 operands, do not call @code{fix_new} thinking you can emit fixups for the
1732 opcode field from the relaxable frag. It is not guaranteed to be the same frag.
1733 If you need to emit fixups for the opcode field from inspection of the
1734 relaxable frag, then you need to generate a common frag for both the basic
1735 opcode and relaxable fields, or you need to provide the frag for the opcode to
1736 pass to @code{fix_new}. The latter can be done for example by defining
1737 @code{TC_FRAG_TYPE} to include a pointer to it and defining @code{TC_FRAG_INIT}
1740 Sometimes @code{fr_var} is increased instead, and @code{frag_wane} is not
1741 called. I'm not sure, but I think this is to keep @code{fr_fix} referring to
1742 an earlier byte, and @code{fr_subtype} set to @code{rs_machine_dependent} so
1743 that @code{md_convert_frag} will get called.
1745 @node General relaxing
1746 @subsection General relaxing
1748 If using a simple table is not suitable, you may implement arbitrarily complex
1749 relaxation semantics yourself. For example, the MIPS backend uses this to emit
1750 different instruction sequences depending upon the size of the symbol being
1753 When you assemble an instruction that may need relaxation, you should allocate
1754 a frag using @code{frag_var} or @code{frag_variant} with a type of
1755 @code{rs_machine_dependent}. You should store some sort of information in the
1756 @code{fr_subtype} field so that you can figure out what to do with the frag
1759 When GAS reaches the end of the input file, it will look through the frags and
1760 work out their final sizes.
1762 GAS will first call @code{md_estimate_size_before_relax} on each
1763 @code{rs_machine_dependent} frag. This function must return an estimated size
1766 GAS will then loop over the frags, calling @code{md_relax_frag} on each
1767 @code{rs_machine_dependent} frag. This function should return the change in
1768 size of the frag. GAS will keep looping over the frags until none of the frags
1772 @section Broken words
1773 @cindex internals, broken words
1774 @cindex broken words
1776 Some compilers, including GCC, will sometimes emit switch tables specifying
1777 16-bit @code{.word} displacements to branch targets, and branch instructions
1778 that load entries from that table to compute the target address. If this is
1779 done on a 32-bit machine, there is a chance (at least with really large
1780 functions) that the displacement will not fit in 16 bits. The assembler
1781 handles this using a concept called @dfn{broken words}. This idea is well
1782 named, since there is an implied promise that the 16-bit field will in fact
1783 hold the specified displacement.
1785 If broken word processing is enabled, and a situation like this is encountered,
1786 the assembler will insert a jump instruction into the instruction stream, close
1787 enough to be reached with the 16-bit displacement. This jump instruction will
1788 transfer to the real desired target address. Thus, as long as the @code{.word}
1789 value really is used as a displacement to compute an address to jump to, the
1790 net effect will be correct (minus a very small efficiency cost). If
1791 @code{.word} directives with label differences for values are used for other
1792 purposes, however, things may not work properly. For targets which use broken
1793 words, the @samp{-K} option will warn when a broken word is discovered.
1795 The broken word code is turned off by the @code{WORKING_DOT_WORD} macro. It
1796 isn't needed if @code{.word} emits a value large enough to contain an address
1797 (or, more correctly, any possible difference between two addresses).
1799 @node Internal functions
1800 @section Internal functions
1802 This section describes basic internal functions used by GAS.
1805 * Warning and error messages:: Warning and error messages
1806 * Hash tables:: Hash tables
1809 @node Warning and error messages
1810 @subsection Warning and error messages
1812 @deftypefun @{@} int had_warnings (void)
1813 @deftypefunx @{@} int had_errors (void)
1814 Returns non-zero if any warnings or errors, respectively, have been printed
1815 during this invocation.
1818 @deftypefun @{@} void as_perror (const char *@var{gripe}, const char *@var{filename})
1819 Displays a BFD or system error, then clears the error status.
1822 @deftypefun @{@} void as_tsktsk (const char *@var{format}, ...)
1823 @deftypefunx @{@} void as_warn (const char *@var{format}, ...)
1824 @deftypefunx @{@} void as_bad (const char *@var{format}, ...)
1825 @deftypefunx @{@} void as_fatal (const char *@var{format}, ...)
1826 These functions display messages about something amiss with the input file, or
1827 internal problems in the assembler itself. The current file name and line
1828 number are printed, followed by the supplied message, formatted using
1829 @code{vfprintf}, and a final newline.
1831 An error indicated by @code{as_bad} will result in a non-zero exit status when
1832 the assembler has finished. Calling @code{as_fatal} will result in immediate
1833 termination of the assembler process.
1836 @deftypefun @{@} void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
1837 @deftypefunx @{@} void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
1838 These variants permit specification of the file name and line number, and are
1839 used when problems are detected when reprocessing information saved away when
1840 processing some earlier part of the file. For example, fixups are processed
1841 after all input has been read, but messages about fixups should refer to the
1842 original filename and line number that they are applicable to.
1845 @deftypefun @{@} void sprint_value (char *@var{buf}, valueT @var{val})
1846 This function is helpful for converting a @code{valueT} value into printable
1847 format, in case it's wider than modes that @code{*printf} can handle. If the
1848 type is narrow enough, a decimal number will be produced; otherwise, it will be
1849 in hexadecimal. The value itself is not examined to make this determination.
1853 @subsection Hash tables
1856 @deftypefun @{@} @{struct hash_control *@} hash_new (void)
1857 Creates the hash table control structure.
1860 @deftypefun @{@} void hash_die (struct hash_control *)
1861 Destroy a hash table.
1864 @deftypefun @{@} PTR hash_delete (struct hash_control *, const char *)
1865 Deletes entry from the hash table, returns the value it had.
1868 @deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR)
1869 Updates the value for an entry already in the table, returning the old value.
1870 If no entry was found, just returns NULL.
1873 @deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR)
1874 Inserting a value already in the table is an error.
1875 Returns an error message or NULL.
1878 @deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR)
1879 Inserts if the value isn't already present, updates it if it is.
1886 The test suite is kind of lame for most processors. Often it only checks to
1887 see if a couple of files can be assembled without the assembler reporting any
1888 errors. For more complete testing, write a test which either examines the
1889 assembler listing, or runs @code{objdump} and examines its output. For the
1890 latter, the TCL procedure @code{run_dump_test} may come in handy. It takes the
1891 base name of a file, and looks for @file{@var{file}.d}. This file should
1892 contain as its initial lines a set of variable settings in @samp{#} comments,
1896 #@var{varname}: @var{value}
1899 The @var{varname} may be @code{objdump}, @code{nm}, or @code{as}, in which case
1900 it specifies the options to be passed to the specified programs. Exactly one
1901 of @code{objdump} or @code{nm} must be specified, as that also specifies which
1902 program to run after the assembler has finished. If @var{varname} is
1903 @code{source}, it specifies the name of the source file; otherwise,
1904 @file{@var{file}.s} is used. If @var{varname} is @code{name}, it specifies the
1905 name of the test to be used in the @code{pass} or @code{fail} messages.
1907 The non-commented parts of the file are interpreted as regular expressions, one
1908 per line. Blank lines in the @code{objdump} or @code{nm} output are skipped,
1909 as are blank lines in the @code{.d} file; the other lines are tested to see if
1910 the regular expression matches the program output. If it does not, the test
1913 Note that this means the tests must be modified if the @code{objdump} output