2 @setfilename internals.info
4 @top Assembler Internals
8 This chapter describes the internals of the assembler. It is incomplete, but
11 This chapter was last modified on $Date$. It is not updated regularly, and it
15 * GAS versions:: GAS versions
16 * Data types:: Data types
17 * GAS processing:: What GAS does when it runs
18 * Porting GAS:: Porting GAS
19 * Relaxation:: Relaxation
20 * Broken words:: Broken words
21 * Internal functions:: Internal functions
22 * Test suite:: Test suite
28 GAS has acquired layers of code over time. The original GAS only supported the
29 a.out object file format, with three sections. Support for multiple sections
30 has been added in two different ways.
32 The preferred approach is to use the version of GAS created when the symbol
33 @code{BFD_ASSEMBLER} is defined. The other versions of GAS are documented for
34 historical purposes, and to help anybody who has to debug code written for
37 The type @code{segT} is used to represent a section in code which must work
38 with all versions of GAS.
41 * Original GAS:: Original GAS version
42 * MANY_SEGMENTS:: MANY_SEGMENTS gas version
43 * BFD_ASSEMBLER:: BFD_ASSEMBLER gas version
47 @subsection Original GAS
49 The original GAS only supported the a.out object file format with three
50 sections: @samp{.text}, @samp{.data}, and @samp{.bss}. This is the version of
51 GAS that is compiled if neither @code{BFD_ASSEMBLER} nor @code{MANY_SEGMENTS}
52 is defined. This version of GAS is still used for the m68k-aout target, and
55 This version of GAS should not be used for any new development.
57 There is still code that is specific to this version of GAS, notably in
58 @file{write.c}. There is no way for this code to loop through all the
59 sections; it simply looks at global variables like @code{text_frag_root} and
60 @code{data_frag_root}.
62 The type @code{segT} is an enum.
65 @subsection MANY_SEGMENTS gas version
68 The @code{MANY_SEGMENTS} version of gas is only used for COFF. It uses the BFD
69 library, but it writes out all the data itself using @code{bfd_write}. This
70 version of gas supports up to 40 normal sections. The section names are stored
71 in the @code{seg_name} array. Other information is stored in the
72 @code{segment_info} array.
74 The type @code{segT} is an enum. Code that wants to examine all the sections
75 can use a @code{segT} variable as loop index from @code{SEG_E0} up to but not
76 including @code{SEG_UNKNOWN}.
78 Most of the code specific to this version of GAS is in the file
79 @file{config/obj-coff.c}, in the portion of that file that is compiled when
80 @code{BFD_ASSEMBLER} is not defined.
82 This version of GAS is still used for several COFF targets.
85 @subsection BFD_ASSEMBLER gas version
88 The preferred version of GAS is the @code{BFD_ASSEMBLER} version. In this
89 version of GAS, the output file is a normal BFD, and the BFD routines are used
90 to generate the output.
92 @code{BFD_ASSEMBLER} will automatically be used for certain targets, including
93 those that use the ELF, ECOFF, and SOM object file formats, and also all Alpha,
94 MIPS, PowerPC, and SPARC targets. You can force the use of
95 @code{BFD_ASSEMBLER} for other targets with the configure option
96 @samp{--enable-bfd-assembler}; however, it has not been tested for many
97 targets, and can not be assumed to work.
101 @cindex internals, data types
103 This section describes some fundamental GAS data types.
106 * Symbols:: The symbolS structure
107 * Expressions:: The expressionS structure
108 * Fixups:: The fixS structure
109 * Frags:: The fragS structure
114 @cindex internals, symbols
115 @cindex symbols, internal
116 @cindex symbolS structure
118 The definition for @code{struct symbol}, also known as @code{symbolS}, is
119 located in @file{struc-symbol.h}. Symbol structures contain the following
124 This is an @code{expressionS} that describes the value of the symbol. It might
125 refer to one or more other symbols; if so, its true value may not be known
126 until @code{resolve_symbol_value} is called in @code{write_object_file}.
128 The expression is often simply a constant. Before @code{resolve_symbol_value}
129 is called, the value is the offset from the frag (@pxref{Frags}). Afterward,
130 the frag address has been added in.
133 This field is non-zero if the symbol's value has been completely resolved. It
134 is used during the final pass over the symbol table.
137 This field is used to detect loops while resolving the symbol's value.
139 @item sy_used_in_reloc
140 This field is non-zero if the symbol is used by a relocation entry. If a local
141 symbol is used in a relocation entry, it must be possible to redirect those
142 relocations to other symbols, or this symbol cannot be removed from the final
147 These pointers to other @code{symbolS} structures describe a singly or doubly
148 linked list. (If @code{SYMBOLS_NEED_BACKPOINTERS} is not defined, the
149 @code{sy_previous} field will be omitted; @code{SYMBOLS_NEED_BACKPOINTERS} is
150 always defined if @code{BFD_ASSEMBLER}.) These fields should be accessed with
151 the @code{symbol_next} and @code{symbol_previous} macros.
154 This points to the frag (@pxref{Frags}) that this symbol is attached to.
157 Whether the symbol is used as an operand or in an expression. Note: Not all of
158 the backends keep this information accurate; backends which use this bit are
159 responsible for setting it when a symbol is used in backend routines.
162 Whether the symbol is an MRI common symbol created by the @code{COMMON}
163 pseudo-op when assembling in MRI mode.
166 If @code{BFD_ASSEMBLER} is defined, this points to the BFD @code{asymbol} that
167 will be used in writing the object file.
170 (Only used if @code{BFD_ASSEMBLER} is not defined.) This is the position of
171 the symbol's name in the string table of the object file. On some formats,
172 this will start at position 4, with position 0 reserved for unnamed symbols.
173 This field is not used until @code{write_object_file} is called.
176 (Only used if @code{BFD_ASSEMBLER} is not defined.) This is the
177 format-specific symbol structure, as it would be written into the object file.
180 (Only used if @code{BFD_ASSEMBLER} is not defined.) This is a 24-bit symbol
181 number, for use in constructing relocation table entries.
184 This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by
185 that name is defined in @file{obj-format.h}, this field is not defined.
188 This processor-specific data is of type @code{TC_SYMFIELD_TYPE}. If no macro
189 by that name is defined in @file{targ-cpu.h}, this field is not defined.
191 @item TARGET_SYMBOL_FIELDS
192 If this macro is defined, it defines additional fields in the symbol structure.
193 This macro is obsolete, and should be replaced when possible by uses of
194 @code{OBJ_SYMFIELD_TYPE} and @code{TC_SYMFIELD_TYPE}.
197 There are a number of access routines used to extract the fields of a
198 @code{symbolS} structure. When possible, these routines should be used rather
199 than referring to the fields directly. These routines will work for any GAS
205 Set the symbol's value.
209 Get the symbol's value. This will cause @code{resolve_symbol_value} to be
210 called if necessary, so @code{S_GET_VALUE} should only be called when it is
211 safe to resolve symbols (i.e., after the entire input file has been read and
212 all symbols have been defined).
215 @cindex S_SET_SEGMENT
216 Set the section of the symbol.
219 @cindex S_GET_SEGMENT
220 Get the symbol's section.
224 Get the name of the symbol.
228 Set the name of the symbol.
231 @cindex S_IS_EXTERNAL
232 Return non-zero if the symbol is externally visible.
236 A synonym for @code{S_IS_EXTERNAL}. Don't use it.
240 Return non-zero if the symbol is weak.
244 Return non-zero if this is a common symbol. Common symbols are sometimes
245 represented as undefined symbols with a value, in which case this function will
250 Return non-zero if this symbol is defined. This function is not reliable when
251 called on a common symbol.
255 Return non-zero if this is a debugging symbol.
259 Return non-zero if this is a local assembler symbol which should not be
260 included in the final symbol table. Note that this is not the opposite of
261 @code{S_IS_EXTERNAL}. The @samp{-L} assembler option affects the return value
265 @cindex S_SET_EXTERNAL
266 Mark the symbol as externally visible.
268 @item S_CLEAR_EXTERNAL
269 @cindex S_CLEAR_EXTERNAL
270 Mark the symbol as not externally visible.
274 Mark the symbol as weak.
282 Get the @code{type}, @code{desc}, and @code{other} fields of the symbol. These
283 are only defined for object file formats for which they make sense (primarily
292 Set the @code{type}, @code{desc}, and @code{other} fields of the symbol. These
293 are only defined for object file formats for which they make sense (primarily
298 Get the size of a symbol. This is only defined for object file formats for
299 which it makes sense (primarily ELF).
303 Set the size of a symbol. This is only defined for object file formats for
304 which it makes sense (primarily ELF).
308 @subsection Expressions
309 @cindex internals, expressions
310 @cindex expressions, internal
311 @cindex expressionS structure
313 Expressions are stored in an @code{expressionS} structure. The structure is
314 defined in @file{expr.h}.
317 The macro @code{expression} will create an @code{expressionS} structure based
318 on the text found at the global variable @code{input_line_pointer}.
320 @cindex make_expr_symbol
321 @cindex expr_symbol_where
322 A single @code{expressionS} structure can represent a single operation.
323 Complex expressions are formed by creating @dfn{expression symbols} and
324 combining them in @code{expressionS} structures. An expression symbol is
325 created by calling @code{make_expr_symbol}. An expression symbol should
326 naturally never appear in a symbol table, and the implementation of
327 @code{S_IS_LOCAL} (@pxref{Symbols}) reflects that. The function
328 @code{expr_symbol_where} returns non-zero if a symbol is an expression symbol,
329 and also returns the file and line for the expression which caused it to be
332 The @code{expressionS} structure has two symbol fields, a number field, an
333 operator field, and a field indicating whether the number is unsigned.
335 The operator field is of type @code{operatorT}, and describes how to interpret
336 the other fields; see the definition in @file{expr.h} for the possibilities.
338 An @code{operatorT} value of @code{O_big} indicates either a floating point
339 number, stored in the global variable @code{generic_floating_point_number}, or
340 an integer to large to store in an @code{offsetT} type, stored in the global
341 array @code{generic_bignum}. This rather inflexible approach makes it
342 impossible to use floating point numbers or large expressions in complex
347 @cindex internals, fixups
349 @cindex fixS structure
351 A @dfn{fixup} is basically anything which can not be resolved in the first
352 pass. Sometimes a fixup can be resolved by the end of the assembly; if not,
353 the fixup becomes a relocation entry in the object file.
357 A fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both
358 take a frag (@pxref{Frags}), a position within the frag, a size, an indication
359 of whether the fixup is PC relative, and a type. In a @code{BFD_ASSEMBLER}
360 GAS, the type is nominally a @code{bfd_reloc_code_real_type}, but several
361 targets use other type codes to represent fixups that can not be described as
364 The @code{fixS} structure has a number of fields, several of which are obsolete
365 or are only used by a particular target. The important fields are:
369 The frag (@pxref{Frags}) this fixup is in.
372 The location within the frag where the fixup occurs.
375 The symbol this fixup is against. Typically, the value of this symbol is added
376 into the object contents. This may be NULL.
379 The value of this symbol is subtracted from the object contents. This is
383 A number which is added into the fixup.
386 Some CPU backends use this field to convey information between
387 @code{md_apply_fix} and @code{tc_gen_reloc}. The machine independent code does
391 The next fixup in the section.
394 The type of the fixup. This field is only defined if @code{BFD_ASSEMBLER}, or
395 if the target defines @code{NEED_FX_R_TYPE}.
398 The size of the fixup. This is mostly used for error checking.
401 Whether the fixup is PC relative.
404 Non-zero if the fixup has been applied, and no relocation entry needs to be
409 The file and line where the fixup was created.
412 This has the type @code{TC_FIX_TYPE}, and is only defined if the target defines
418 @cindex internals, frags
420 @cindex fragS structure.
422 The @code{fragS} structure is defined in @file{as.h}. Each frag represents a
423 portion of the final object file. As GAS reads the source file, it creates
424 frags to hold the data that it reads. At the end of the assembly the frags and
425 fixups are processed to produce the final contents.
429 The address of the frag. This is not set until the assembler rescans the list
430 of all frags after the entire input file is parsed. The function
431 @code{relax_segment} fills in this field.
434 Pointer to the next frag in this (sub)section.
437 Fixed number of characters we know we're going to emit to the output file. May
441 Variable number of characters we may output, after the initial @code{fr_fix}
442 characters. May be zero.
445 The interpretation of this field is controlled by @code{fr_type}. Generally,
446 if @code{fr_var} is non-zero, this is a repeat count: the @code{fr_var}
447 characters are output @code{fr_offset} times.
450 Holds line number info when an assembler listing was requested.
453 Relaxation state. This field indicates the interpretation of @code{fr_offset},
454 @code{fr_symbol} and the variable-length tail of the frag, as well as the
455 treatment it gets in various phases of processing. It does not affect the
456 initial @code{fr_fix} characters; they are always supposed to be output
457 verbatim (fixups aside). See below for specific values this field can have.
460 Relaxation substate. If the macro @code{md_relax_frag} isn't defined, this is
461 assumed to be an index into @code{TC_GENERIC_RELAX_TABLE} for the generic
462 relaxation code to process (@pxref{Relaxation}). If @code{md_relax_frag} is
463 defined, this field is available for any use by the CPU-specific code.
466 This normally indicates the symbol to use when relaxing the frag according to
470 Points to the lowest-addressed byte of the opcode, for use in relaxation.
473 @itemx fr_opcode_offset
475 These fields are only used in the NS32k configuration. But since @code{struct
476 frag} is defined before the CPU-specific header files are included, they must
477 unconditionally be defined.
481 The file and line where this frag was last modified.
484 Declared as a one-character array, this last field grows arbitrarily large to
485 hold the actual contents of the frag.
488 These are the possible relaxation states, provided in the enumeration type
489 @code{relax_stateT}, and the interpretations they represent for the other
495 The start of the following frag should be aligned on some boundary. In this
496 frag, @code{fr_offset} is the logarithm (base 2) of the alignment in bytes.
497 (For example, if alignment on an 8-byte boundary were desired, @code{fr_offset}
498 would have a value of 3.) The variable characters indicate the fill pattern to
499 be used. The @code{fr_subtype} field holds the maximum number of bytes to skip
500 when doing this alignment. If more bytes are needed, the alignment is not
501 done. An @code{fr_subtype} value of 0 means no maximum, which is the normal
502 case. Target backends can use @code{rs_align_code} to handle certain types of
503 alignment differently.
506 This indicates that ``broken word'' processing should be done (@pxref{Broken
507 words}). If broken word processing is not necessary on the target machine,
508 this enumerator value will not be defined.
511 The variable characters are to be repeated @code{fr_offset} times. If
512 @code{fr_offset} is 0, this frag has a length of @code{fr_fix}. Most frags
516 This state is used to implement the DWARF ``little endian base 128''
517 variable length number format. The @code{fr_symbol} is always an expression
518 symbol, as constant expressions are emitted directly. The @code{fr_offset}
519 field is used during relaxation to hold the previous size of the number so
520 that we can determine if the fragment changed size.
522 @item rs_machine_dependent
523 Displacement relaxation is to be done on this frag. The target is indicated by
524 @code{fr_symbol} and @code{fr_offset}, and @code{fr_subtype} indicates the
525 particular machine-specific addressing mode desired. @xref{Relaxation}.
528 The start of the following frag should be pushed back to some specific offset
529 within the section. (Some assemblers use the value as an absolute address; GAS
530 does not handle final absolute addresses, but rather requires that the linker
531 set them.) The offset is given by @code{fr_symbol} and @code{fr_offset}; one
532 character from the variable-length tail is used as the fill character.
535 @cindex frchainS structure
536 A chain of frags is built up for each subsection. The data structure
537 describing a chain is called a @code{frchainS}, and contains the following
542 Points to the first frag in the chain. May be NULL if there are no frags in
545 Points to the last frag in the chain, or NULL if there are none.
547 Next in the list of @code{frchainS} structures.
549 Indicates the section this frag chain belongs to.
551 Subsection (subsegment) number of this frag chain.
552 @item fix_root, fix_tail
553 (Defined only if @code{BFD_ASSEMBLER} is defined). Point to first and last
554 @code{fixS} structures associated with this subsection.
556 Not currently used. Intended to be used for frag allocation for this
557 subsection. This should reduce frag generation caused by switching sections.
559 The current frag for this subsegment.
562 A @code{frchainS} corresponds to a subsection; each section has a list of
563 @code{frchainS} records associated with it. In most cases, only one subsection
564 of each section is used, so the list will only be one element long, but any
565 processing of frag chains should be prepared to deal with multiple chains per
568 After the input files have been completely processed, and no more frags are to
569 be generated, the frag chains are joined into one per section for further
570 processing. After this point, it is safe to operate on one chain per section.
572 The assembler always has a current frag, named @code{frag_now}. More space is
573 allocated for the current frag using the @code{frag_more} function; this
574 returns a pointer to the amount of requested space. Relaxing is done using
575 variant frags allocated by @code{frag_var} or @code{frag_variant}
576 (@pxref{Relaxation}).
579 @section What GAS does when it runs
580 @cindex internals, overview
582 This is a quick look at what an assembler run looks like.
586 The assembler initializes itself by calling various init routines.
589 For each source file, the @code{read_a_source_file} function reads in the file
590 and parses it. The global variable @code{input_line_pointer} points to the
591 current text; it is guaranteed to be correct up to the end of the line, but not
595 For each line, the assembler passes labels to the @code{colon} function, and
596 isolates the first word. If it looks like a pseudo-op, the word is looked up
597 in the pseudo-op hash table @code{po_hash} and dispatched to a pseudo-op
598 routine. Otherwise, the target dependent @code{md_assemble} routine is called
599 to parse the instruction.
602 When pseudo-ops or instructions output data, they add it to a frag, calling
603 @code{frag_more} to get space to store it in.
606 Pseudo-ops and instructions can also output fixups created by @code{fix_new} or
610 For certain targets, instructions can create variant frags which are used to
611 store relaxation information (@pxref{Relaxation}).
614 When the input file is finished, the @code{write_object_file} routine is
615 called. It assigns addresses to all the frags (@code{relax_segment}), resolves
616 all the fixups (@code{fixup_segment}), resolves all the symbol values (using
617 @code{resolve_symbol_value}), and finally writes out the file (in the
618 @code{BFD_ASSEMBLER} case, this is done by simply calling @code{bfd_close}).
625 Each GAS target specifies two main things: the CPU file and the object format
626 file. Two main switches in the @file{configure.in} file handle this. The
627 first switches on CPU type to set the shell variable @code{cpu_type}. The
628 second switches on the entire target to set the shell variable @code{fmt}.
630 The configure script uses the value of @code{cpu_type} to select two files in
631 the @file{config} directory: @file{tc-@var{CPU}.c} and @file{tc-@var{CPU}.h}.
632 The configuration process will create a file named @file{targ-cpu.h} in the
633 build directory which includes @file{tc-@var{CPU}.h}.
635 The configure script also uses the value of @code{fmt} to select two files:
636 @file{obj-@var{fmt}.c} and @file{obj-@var{fmt}.h}. The configuration process
637 will create a file named @file{obj-format.h} in the build directory which
638 includes @file{obj-@var{fmt}.h}.
640 You can also set the emulation in the configure script by setting the @code{em}
641 variable. Normally the default value of @samp{generic} is fine. The
642 configuration process will create a file named @file{targ-env.h} in the build
643 directory which includes @file{te-@var{em}.h}.
645 Porting GAS to a new CPU requires writing the @file{tc-@var{CPU}} files.
646 Porting GAS to a new object file format requires writing the
647 @file{obj-@var{fmt}} files. There is sometimes some interaction between these
648 two files, but it is normally minimal.
650 The best approach is, of course, to copy existing files. The documentation
651 below assumes that you are looking at existing files to see usage details.
653 These interfaces have grown over time, and have never been carefully thought
654 out or designed. Nothing about the interfaces described here is cast in stone.
655 It is possible that they will change from one version of the assembler to the
656 next. Also, new macros are added all the time as they are needed.
659 * CPU backend:: Writing a CPU backend
660 * Object format backend:: Writing an object format backend
661 * Emulations:: Writing emulation files
665 @subsection Writing a CPU backend
667 @cindex @file{tc-@var{CPU}}
669 The CPU backend files are the heart of the assembler. They are the only parts
670 of the assembler which actually know anything about the instruction set of the
673 You must define a reasonably small list of macros and functions in the CPU
674 backend files. You may define a large number of additional macros in the CPU
675 backend files, not all of which are documented here. You must, of course,
676 define macros in the @file{.h} file, which is included by every assembler
677 source file. You may define the functions as macros in the @file{.h} file, or
678 as functions in the @file{.c} file.
683 By convention, you should define this macro in the @file{.h} file. For
684 example, @file{tc-m68k.h} defines @code{TC_M68K}. You might have to use this
685 if it is necessary to add CPU specific code to the object format file.
688 This macro is the BFD target name to use when creating the output file. This
689 will normally depend upon the @code{OBJ_@var{FMT}} macro.
692 This macro is the BFD architecture to pass to @code{bfd_set_arch_mach}.
695 This macro is the BFD machine number to pass to @code{bfd_set_arch_mach}. If
696 it is not defined, GAS will use 0.
698 @item TARGET_BYTES_BIG_ENDIAN
699 You should define this macro to be non-zero if the target is big endian, and
700 zero if the target is little endian.
704 @itemx md_longopts_size
705 @itemx md_parse_option
709 @cindex md_longopts_size
710 @cindex md_parse_option
711 @cindex md_show_usage
712 GAS uses these variables and functions during option processing.
713 @code{md_shortopts} is a @code{const char *} which GAS adds to the machine
714 independent string passed to @code{getopt}. @code{md_longopts} is a
715 @code{struct option []} which GAS adds to the machine independent long options
716 passed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in
717 @file{as.h}, as the start of a set of long option indices, if necessary.
718 @code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}.
719 GAS will call @code{md_parse_option} whenever @code{getopt} returns an
720 unrecognized code, presumably indicating a special code value which appears in
721 @code{md_longopts}. GAS will call @code{md_show_usage} when a usage message is
722 printed; it should print a description of the machine specific options.
726 GAS will call this function at the start of the assembly, after the command
727 line arguments have been parsed and all the machine independent initializations
732 If you define this macro, GAS will call it at the end of each input file.
736 GAS will call this function for each input line which does not contain a
737 pseudo-op. The argument is a null terminated string. The function should
738 assemble the string as an instruction with operands. Normally
739 @code{md_assemble} will do this by calling @code{frag_more} and writing out
740 some bytes (@pxref{Frags}). @code{md_assemble} will call @code{fix_new} to
741 create fixups as needed (@pxref{Fixups}). Targets which need to do special
742 purpose relaxation will call @code{frag_var}.
744 @item md_pseudo_table
745 @cindex md_pseudo_table
746 This is a const array of type @code{pseudo_typeS}. It is a mapping from
747 pseudo-op names to functions. You should use this table to implement
748 pseudo-ops which are specific to the CPU.
750 @item tc_conditional_pseudoop
751 @cindex tc_conditional_pseudoop
752 If this macro is defined, GAS will call it with a @code{pseudo_typeS} argument.
753 It should return non-zero if the pseudo-op is a conditional which controls
754 whether code is assembled, such as @samp{.if}. GAS knows about the normal
755 conditional pseudo-ops,and you should normally not have to define this macro.
758 @cindex comment_chars
759 This is a null terminated @code{const char} array of characters which start a
762 @item tc_comment_chars
763 @cindex tc_comment_chars
764 If this macro is defined, GAS will use it instead of @code{comment_chars}.
766 @item line_comment_chars
767 @cindex line_comment_chars
768 This is a null terminated @code{const char} array of characters which start a
769 comment when they appear at the start of a line.
771 @item line_separator_chars
772 @cindex line_separator_chars
773 This is a null terminated @code{const char} array of characters which separate
774 lines (the semicolon is such a character by default, and need not be listed in
779 This is a null terminated @code{const char} array of characters which may be
780 used as the exponent character in a floating point number. This is normally
785 This is a null terminated @code{const char} array of characters which may be
786 used to indicate a floating point constant. A zero followed by one of these
787 characters is assumed to be followed by a floating point number; thus they
788 operate the way that @code{0x} is used to indicate a hexadecimal constant.
789 Usually this includes @samp{r} and @samp{f}.
793 You may define this macro to the lexical type of the @kbd{@}} character. The
796 Lexical types are a combination of @code{LEX_NAME} and @code{LEX_BEGIN_NAME},
797 both defined in @file{read.h}. @code{LEX_NAME} indicates that the character
798 may appear in a name. @code{LEX_BEGIN_NAME} indicates that the character may
799 appear at the beginning of a nem.
803 You may define this macro to the lexical type of the brace characters @kbd{@{},
804 @kbd{@}}, @kbd{[}, and @kbd{]}. The default value is zero.
808 You may define this macro to the lexical type of the @kbd{%} character. The
809 default value is zero.
813 You may define this macro to the lexical type of the @kbd{?} character. The
814 default value it zero.
818 You may define this macro to the lexical type of the @kbd{$} character. The
819 default value is @code{LEX_NAME | LEX_BEGIN_NAME}.
821 @item SINGLE_QUOTE_STRINGS
822 @cindex SINGLE_QUOTE_STRINGS
823 If you define this macro, GAS will treat single quotes as string delimiters.
824 Normally only double quotes are accepted as string delimiters.
826 @item NO_STRING_ESCAPES
827 @cindex NO_STRING_ESCAPES
828 If you define this macro, GAS will not permit escape sequences in a string.
830 @item ONLY_STANDARD_ESCAPES
831 @cindex ONLY_STANDARD_ESCAPES
832 If you define this macro, GAS will warn about the use of nonstandard escape
833 sequences in a string.
835 @item md_start_line_hook
836 @cindex md_start_line_hook
837 If you define this macro, GAS will call it at the start of each line.
839 @item LABELS_WITHOUT_COLONS
840 @cindex LABELS_WITHOUT_COLONS
841 If you define this macro, GAS will assume that any text at the start of a line
842 is a label, even if it does not have a colon.
845 @cindex TC_START_LABEL
846 You may define this macro to control what GAS considers to be a label. The
847 default definition is to accept any name followed by a colon character.
850 @cindex NO_PSEUDO_DOT
851 If you define this macro, GAS will not require pseudo-ops to start with a
854 @item TC_EQUAL_IN_INSN
855 @cindex TC_EQUAL_IN_INSN
856 If you define this macro, it should return nonzero if the instruction is
857 permitted to contain an @kbd{=} character. GAS will use this to decide if a
858 @kbd{=} is an assignment or an instruction.
861 @cindex TC_EOL_IN_INSN
862 If you define this macro, it should return nonzero if the current input line
863 pointer should be treated as the end of a line.
866 @cindex md_parse_name
867 If this macro is defined, GAS will call it for any symbol found in an
868 expression. You can define this to handle special symbols in a special way.
869 If a symbol always has a certain value, you should normally enter it in the
870 symbol table, perhaps using @code{reg_section}.
872 @item md_undefined_symbol
873 @cindex md_undefined_symbol
874 GAS will call this function when a symbol table lookup fails, before it
875 creates a new symbol. Typically this would be used to supply symbols whose
876 name or value changes dynamically, possibly in a context sensitive way.
877 Predefined symbols with fixed values, such as register names or condition
878 codes, are typically entered directly into the symbol table when @code{md_begin}
883 GAS will call this function for any expression that can not be recognized.
884 When the function is called, @code{input_line_pointer} will point to the start
887 @item tc_unrecognized_line
888 @cindex tc_unrecognized_line
889 If you define this macro, GAS will call it when it finds a line that it can not
894 You may define this macro to handle an alignment directive. GAS will call it
895 when the directive is seen in the input file. For example, the i386 backend
896 uses this to generate efficient nop instructions of varying lengths, depending
897 upon the number of bytes that the alignment will skip.
901 You may define this macro to do special handling for an alignment directive.
902 GAS will call it at the end of the assembly.
904 @item md_flush_pending_output
905 @cindex md_flush_pending_output
906 If you define this macro, GAS will call it each time it skips any space because of a
907 space filling or alignment or data allocation pseudo-op.
909 @item TC_PARSE_CONS_EXPRESSION
910 @cindex TC_PARSE_CONS_EXPRESSION
911 You may define this macro to parse an expression used in a data allocation
912 pseudo-op such as @code{.word}. You can use this to recognize relocation
913 directives that may appear in such directives.
915 @item BITFIELD_CONS_EXPRESSION
916 @cindex BITFIELD_CONS_EXPRESSION
917 If you define this macro, GAS will recognize bitfield instructions in data
918 allocation pseudo-ops, as used on the i960.
920 @item REPEAT_CONS_EXPRESSION
921 @cindex REPEAT_CONS_EXPRESSION
922 If you define this macro, GAS will recognize repeat counts in data allocation
923 pseudo-ops, as used on the MIPS.
926 @cindex md_cons_align
927 You may define this macro to do any special alignment before a data allocation
930 @item TC_CONS_FIX_NEW
931 @cindex TC_CONS_FIX_NEW
932 You may define this macro to generate a fixup for a data allocation pseudo-op.
934 @item TC_INIT_FIX_DATA (@var{fixp})
935 @cindex TC_INIT_FIX_DATA
936 A C statement to initialize the target specific fields of fixup @var{fixp}.
938 @item TC_FIX_DATA_PRINT (@var{stream}, @var{fixp})
939 @cindex TC_FIX_DATA_PRINT
940 A C statement to output target specific debugging information for
941 fixup @var{fixp} to @var{stream}. This macro is called by @code{print_fixup}.
943 @item md_number_to_chars
944 @cindex md_number_to_chars
945 This should just call either @code{number_to_chars_bigendian} or
946 @code{number_to_chars_littleendian}, whichever is appropriate. On targets like
947 the MIPS which support options to change the endianness, which function to call
948 is a runtime decision. On other targets, @code{md_number_to_chars} can be a
952 @cindex md_reloc_size
953 This variable is only used in the original version of gas (not
954 @code{BFD_ASSEMBLER} and not @code{MANY_SEGMENTS}). It holds the size of a
957 @item WORKING_DOT_WORD
958 @itemx md_short_jump_size
959 @itemx md_long_jump_size
960 @itemx md_create_short_jump
961 @itemx md_create_long_jump
962 @cindex WORKING_DOT_WORD
963 @cindex md_short_jump_size
964 @cindex md_long_jump_size
965 @cindex md_create_short_jump
966 @cindex md_create_long_jump
967 If @code{WORKING_DOT_WORD} is defined, GAS will not do broken word processing
968 (@pxref{Broken words}). Otherwise, you should set @code{md_short_jump_size} to
969 the size of a short jump (a jump that is just long enough to jump around a long
970 jmp) and @code{md_long_jump_size} to the size of a long jump (a jump that can
971 go anywhere in the function), You should define @code{md_create_short_jump} to
972 create a short jump around a long jump, and define @code{md_create_long_jump}
973 to create a long jump.
975 @item md_estimate_size_before_relax
976 @cindex md_estimate_size_before_relax
977 This function returns an estimate of the size of a @code{rs_machine_dependent}
978 frag before any relaxing is done. It may also create any necessary
982 @cindex md_relax_frag
983 This macro may be defined to relax a frag. GAS will call this with the frag
984 and the change in size of all previous frags; @code{md_relax_frag} should
985 return the change in size of the frag. @xref{Relaxation}.
987 @item TC_GENERIC_RELAX_TABLE
988 @cindex TC_GENERIC_RELAX_TABLE
989 If you do not define @code{md_relax_frag}, you may define
990 @code{TC_GENERIC_RELAX_TABLE} as a table of @code{relax_typeS} structures. The
991 machine independent code knows how to use such a table to relax PC relative
992 references. See @file{tc-m68k.c} for an example. @xref{Relaxation}.
994 @item md_prepare_relax_scan
995 @cindex md_prepare_relax_scan
996 If defined, it is a C statement that is invoked prior to scanning
999 @item LINKER_RELAXING_SHRINKS_ONLY
1000 @cindex LINKER_RELAXING_SHRINKS_ONLY
1001 If you define this macro, and the global variable @samp{linkrelax} is set
1002 (because of a command line option, or unconditionally in @code{md_begin}), a
1003 @samp{.align} directive will cause extra space to be allocated. The linker can
1004 then discard this space when relaxing the section.
1006 @item md_convert_frag
1007 @cindex md_convert_frag
1008 GAS will call this for each rs_machine_dependent fragment.
1009 The instruction is completed using the data from the relaxation pass.
1010 It may also create any necessary relocations.
1014 @cindex md_apply_fix
1015 GAS will call this for each fixup. It should store the correct value in the
1018 @item TC_HANDLES_FX_DONE
1019 @cindex TC_HANDLES_FX_DONE
1020 If this macro is defined, it means that @code{md_apply_fix} correctly sets the
1021 @code{fx_done} field in the fixup.
1024 @cindex tc_gen_reloc
1025 A @code{BFD_ASSEMBLER} GAS will call this to generate a reloc. GAS will pass
1026 the resulting reloc to @code{bfd_install_relocation}. This currently works
1027 poorly, as @code{bfd_install_relocation} often does the wrong thing, and
1028 instances of @code{tc_gen_reloc} have been written to work around the problems,
1029 which in turns makes it difficult to fix @code{bfd_install_relocation}.
1031 @item RELOC_EXPANSION_POSSIBLE
1032 @cindex RELOC_EXPANSION_POSSIBLE
1033 If you define this macro, it means that @code{tc_gen_reloc} may return multiple
1034 relocation entries for a single fixup. In this case, the return value of
1035 @code{tc_gen_reloc} is a pointer to a null terminated array.
1037 @item MAX_RELOC_EXPANSION
1038 @cindex MAX_RELOC_EXPANSION
1039 You must define this if @code{RELOC_EXPANSION_POSSIBLE} is defined; it
1040 indicates the largest number of relocs which @code{tc_gen_reloc} may return for
1043 @item tc_fix_adjustable
1044 @cindex tc_fix_adjustable
1045 You may define this macro to indicate whether a fixup against a locally defined
1046 symbol should be adjusted to be against the section symbol. It should return a
1047 non-zero value if the adjustment is acceptable.
1049 @item MD_PCREL_FROM_SECTION
1050 @cindex MD_PCREL_FROM_SECTION
1051 If you define this macro, it should return the offset between the address of a
1052 PC relative fixup and the position from which the PC relative adjustment should
1053 be made. On many processors, the base of a PC relative instruction is the next
1054 instruction, so this macro would return the length of an instruction.
1057 @cindex md_pcrel_from
1058 This is the default value of @code{MD_PCREL_FROM_SECTION}. The difference is
1059 that @code{md_pcrel_from} does not take a section argument.
1062 @cindex tc_frob_label
1063 If you define this macro, GAS will call it each time a label is defined.
1065 @item md_section_align
1066 @cindex md_section_align
1067 GAS will call this function for each section at the end of the assembly, to
1068 permit the CPU backend to adjust the alignment of a section.
1070 @item tc_frob_section
1071 @cindex tc_frob_section
1072 If you define this macro, a @code{BFD_ASSEMBLER} GAS will call it for each
1073 section at the end of the assembly.
1075 @item tc_frob_file_before_adjust
1076 @cindex tc_frob_file_before_adjust
1077 If you define this macro, GAS will call it after the symbol values are
1078 resolved, but before the fixups have been changed from local symbols to section
1081 @item tc_frob_symbol
1082 @cindex tc_frob_symbol
1083 If you define this macro, GAS will call it for each symbol. You can indicate
1084 that the symbol should not be included in the object file by definining this
1085 macro to set its second argument to a non-zero value.
1088 @cindex tc_frob_file
1089 If you define this macro, GAS will call it after the symbol table has been
1090 completed, but before the relocations have been generated.
1092 @item tc_frob_file_after_relocs
1093 If you define this macro, GAS will call it after the relocs have been
1096 @item LISTING_HEADER
1097 A string to use on the header line of a listing. The default value is simply
1098 @code{"GAS LISTING"}.
1100 @item LISTING_WORD_SIZE
1101 The number of bytes to put into a word in a listing. This affects the way the
1102 bytes are clumped together in the listing. For example, a value of 2 might
1103 print @samp{1234 5678} where a value of 1 would print @samp{12 34 56 78}. The
1106 @item LISTING_LHS_WIDTH
1107 The number of words of data to print on the first line of a listing for a
1108 particular source line, where each word is @code{LISTING_WORD_SIZE} bytes. The
1111 @item LISTING_LHS_WIDTH_SECOND
1112 Like @code{LISTING_LHS_WIDTH}, but applying to the second and subsequent line
1113 of the data printed for a particular source line. The default value is 1.
1115 @item LISTING_LHS_CONT_LINES
1116 The maximum number of continuation lines to print in a listing for a particular
1117 source line. The default value is 4.
1119 @item LISTING_RHS_WIDTH
1120 The maximum number of characters to print from one line of the input file. The
1121 default value is 100.
1124 @node Object format backend
1125 @subsection Writing an object format backend
1126 @cindex object format backend
1127 @cindex @file{obj-@var{fmt}}
1129 As with the CPU backend, the object format backend must define a few things,
1130 and may define some other things. The interface to the object format backend
1131 is generally simpler; most of the support for an object file format consists of
1132 defining a number of pseudo-ops.
1134 The object format @file{.h} file must include @file{targ-cpu.h}.
1136 This section will only define the @code{BFD_ASSEMBLER} version of GAS. It is
1137 impossible to support a new object file format using any other version anyhow,
1138 as the original GAS version only supports a.out, and the @code{MANY_SEGMENTS}
1139 GAS version only supports COFF.
1142 @item OBJ_@var{format}
1143 @cindex OBJ_@var{format}
1144 By convention, you should define this macro in the @file{.h} file. For
1145 example, @file{obj-elf.h} defines @code{OBJ_ELF}. You might have to use this
1146 if it is necessary to add object file format specific code to the CPU file.
1149 If you define this macro, GAS will call it at the start of the assembly, after
1150 the command line arguments have been parsed and all the machine independent
1151 initializations have been completed.
1154 @cindex obj_app_file
1155 If you define this macro, GAS will invoke it when it sees a @code{.file}
1156 pseudo-op or a @samp{#} line as used by the C preprocessor.
1158 @item OBJ_COPY_SYMBOL_ATTRIBUTES
1159 @cindex OBJ_COPY_SYMBOL_ATTRIBUTES
1160 You should define this macro to copy object format specific information from
1161 one symbol to another. GAS will call it when one symbol is equated to
1164 @item obj_fix_adjustable
1165 @cindex obj_fix_adjustable
1166 You may define this macro to indicate whether a fixup against a locally defined
1167 symbol should be adjusted to be against the section symbol. It should return a
1168 non-zero value if the adjustment is acceptable.
1170 @item obj_sec_sym_ok_for_reloc
1171 @cindex obj_sec_sym_ok_for_reloc
1172 You may define this macro to indicate that it is OK to use a section symbol in
1173 a relocateion entry. If it is not, GAS will define a new symbol at the start
1176 @item EMIT_SECTION_SYMBOLS
1177 @cindex EMIT_SECTION_SYMBOLS
1178 You should define this macro with a zero value if you do not want to include
1179 section symbols in the output symbol table. The default value for this macro
1182 @item obj_adjust_symtab
1183 @cindex obj_adjust_symtab
1184 If you define this macro, GAS will invoke it just before setting the symbol
1185 table of the output BFD. For example, the COFF support uses this macro to
1186 generate a @code{.file} symbol if none was generated previously.
1188 @item SEPARATE_STAB_SECTIONS
1189 @cindex SEPARATE_STAB_SECTIONS
1190 You may define this macro to indicate that stabs should be placed in separate
1191 sections, as in ELF.
1193 @item INIT_STAB_SECTION
1194 @cindex INIT_STAB_SECTION
1195 You may define this macro to initialize the stabs section in the output file.
1197 @item OBJ_PROCESS_STAB
1198 @cindex OBJ_PROCESS_STAB
1199 You may define this macro to do specific processing on a stabs entry.
1201 @item obj_frob_section
1202 @cindex obj_frob_section
1203 If you define this macro, GAS will call it for each section at the end of the
1206 @item obj_frob_file_before_adjust
1207 @cindex obj_frob_file_before_adjust
1208 If you define this macro, GAS will call it after the symbol values are
1209 resolved, but before the fixups have been changed from local symbols to section
1212 @item obj_frob_symbol
1213 @cindex obj_frob_symbol
1214 If you define this macro, GAS will call it for each symbol. You can indicate
1215 that the symbol should not be included in the object file by definining this
1216 macro to set its second argument to a non-zero value.
1219 @cindex obj_frob_file
1220 If you define this macro, GAS will call it after the symbol table has been
1221 completed, but before the relocations have been generated.
1223 @item obj_frob_file_after_relocs
1224 If you define this macro, GAS will call it after the relocs have been
1229 @subsection Writing emulation files
1231 Normally you do not have to write an emulation file. You can just use
1232 @file{te-generic.h}.
1234 If you do write your own emulation file, it must include @file{obj-format.h}.
1236 An emulation file will often define @code{TE_@var{EM}}; this may then be used
1237 in other files to change the output.
1243 @dfn{Relaxation} is a generic term used when the size of some instruction or
1244 data depends upon the value of some symbol or other data.
1246 GAS knows to relax a particular type of PC relative relocation using a table.
1247 You can also define arbitrarily complex forms of relaxation yourself.
1250 * Relaxing with a table:: Relaxing with a table
1251 * General relaxing:: General relaxing
1254 @node Relaxing with a table
1255 @subsection Relaxing with a table
1257 If you do not define @code{md_relax_frag}, and you do define
1258 @code{TC_GENERIC_RELAX_TABLE}, GAS will relax @code{rs_machine_dependent} frags
1259 based on the frag subtype and the displacement to some specified target
1260 address. The basic idea is that several machines have different addressing
1261 modes for instructions that can specify different ranges of values, with
1262 successive modes able to access wider ranges, including the entirety of the
1263 previous range. Smaller ranges are assumed to be more desirable (perhaps the
1264 instruction requires one word instead of two or three); if this is not the
1265 case, don't describe the smaller-range, inferior mode.
1267 The @code{fr_subtype} field of a frag is an index into a CPU-specific
1268 relaxation table. That table entry indicates the range of values that can be
1269 stored, the number of bytes that will have to be added to the frag to
1270 accomodate the addressing mode, and the index of the next entry to examine if
1271 the value to be stored is outside the range accessible by the current
1272 addressing mode. The @code{fr_symbol} field of the frag indicates what symbol
1273 is to be accessed; the @code{fr_offset} field is added in.
1275 If the @code{TC_PCREL_ADJUST} macro is defined, which currently should only happen
1276 for the NS32k family, the @code{TC_PCREL_ADJUST} macro is called on the frag to
1277 compute an adjustment to be made to the displacement.
1279 The value fitted by the relaxation code is always assumed to be a displacement
1280 from the current frag. (More specifically, from @code{fr_fix} bytes into the
1283 This seems kinda silly. What about fitting small absolute values? I suppose
1284 @code{md_assemble} is supposed to take care of that, but if the operand is a
1285 difference between symbols, it might not be able to, if the difference was not
1289 The end of the relaxation sequence is indicated by a ``next'' value of 0. This
1290 means that the first entry in the table can't be used.
1292 For some configurations, the linker can do relaxing within a section of an
1293 object file. If call instructions of various sizes exist, the linker can
1294 determine which should be used in each instance, when a symbol's value is
1295 resolved. In order for the linker to avoid wasting space and having to insert
1296 no-op instructions, it must be able to expand or shrink the section contents
1297 while still preserving intra-section references and meeting alignment
1300 For the i960 using b.out format, no expansion is done; instead, each
1301 @samp{.align} directive causes extra space to be allocated, enough that when
1302 the linker is relaxing a section and removing unneeded space, it can discard
1303 some or all of this extra padding and cause the following data to be correctly
1306 For the H8/300, I think the linker expands calls that can't reach, and doesn't
1307 worry about alignment issues; the cpu probably never needs any significant
1308 alignment beyond the instruction size.
1310 The relaxation table type contains these fields:
1313 @item long rlx_forward
1314 Forward reach, must be non-negative.
1315 @item long rlx_backward
1316 Backward reach, must be zero or negative.
1318 Length in bytes of this addressing mode.
1320 Index of the next-longer relax state, or zero if there is no next relax state.
1323 The relaxation is done in @code{relax_segment} in @file{write.c}. The
1324 difference in the length fields between the original mode and the one finally
1325 chosen by the relaxing code is taken as the size by which the current frag will
1326 be increased in size. For example, if the initial relaxing mode has a length
1327 of 2 bytes, and because of the size of the displacement, it gets upgraded to a
1328 mode with a size of 6 bytes, it is assumed that the frag will grow by 4 bytes.
1329 (The initial two bytes should have been part of the fixed portion of the frag,
1330 since it is already known that they will be output.) This growth must be
1331 effected by @code{md_convert_frag}; it should increase the @code{fr_fix} field
1332 by the appropriate size, and fill in the appropriate bytes of the frag.
1333 (Enough space for the maximum growth should have been allocated in the call to
1334 frag_var as the second argument.)
1336 If relocation records are needed, they should be emitted by
1337 @code{md_estimate_size_before_relax}. This function should examine the target
1338 symbol of the supplied frag and correct the @code{fr_subtype} of the frag if
1339 needed. When this function is called, if the symbol has not yet been defined,
1340 it will not become defined later; however, its value may still change if the
1341 section it is in gets relaxed.
1343 Usually, if the symbol is in the same section as the frag (given by the
1344 @var{sec} argument), the narrowest likely relaxation mode is stored in
1345 @code{fr_subtype}, and that's that.
1347 If the symbol is undefined, or in a different section (and therefore moveable
1348 to an arbitrarily large distance), the largest available relaxation mode is
1349 specified, @code{fix_new} is called to produce the relocation record,
1350 @code{fr_fix} is increased to include the relocated field (remember, this
1351 storage was allocated when @code{frag_var} was called), and @code{frag_wane} is
1352 called to convert the frag to an @code{rs_fill} frag with no variant part.
1353 Sometimes changing addressing modes may also require rewriting the instruction.
1354 It can be accessed via @code{fr_opcode} or @code{fr_fix}.
1356 Sometimes @code{fr_var} is increased instead, and @code{frag_wane} is not
1357 called. I'm not sure, but I think this is to keep @code{fr_fix} referring to
1358 an earlier byte, and @code{fr_subtype} set to @code{rs_machine_dependent} so
1359 that @code{md_convert_frag} will get called.
1361 @node General relaxing
1362 @subsection General relaxing
1364 If using a simple table is not suitable, you may implement arbitrarily complex
1365 relaxation semantics yourself. For example, the MIPS backend uses this to emit
1366 different instruction sequences depending upon the size of the symbol being
1369 When you assemble an instruction that may need relaxation, you should allocate
1370 a frag using @code{frag_var} or @code{frag_variant} with a type of
1371 @code{rs_machine_dependent}. You should store some sort of information in the
1372 @code{fr_subtype} field so that you can figure out what to do with the frag
1375 When GAS reaches the end of the input file, it will look through the frags and
1376 work out their final sizes.
1378 GAS will first call @code{md_estimate_size_before_relax} on each
1379 @code{rs_machine_dependent} frag. This function must return an estimated size
1382 GAS will then loop over the frags, calling @code{md_relax_frag} on each
1383 @code{rs_machine_dependent} frag. This function should return the change in
1384 size of the frag. GAS will keep looping over the frags until none of the frags
1388 @section Broken words
1389 @cindex internals, broken words
1390 @cindex broken words
1392 Some compilers, including GCC, will sometimes emit switch tables specifying
1393 16-bit @code{.word} displacements to branch targets, and branch instructions
1394 that load entries from that table to compute the target address. If this is
1395 done on a 32-bit machine, there is a chance (at least with really large
1396 functions) that the displacement will not fit in 16 bits. The assembler
1397 handles this using a concept called @dfn{broken words}. This idea is well
1398 named, since there is an implied promise that the 16-bit field will in fact
1399 hold the specified displacement.
1401 If broken word processing is enabled, and a situation like this is encountered,
1402 the assembler will insert a jump instruction into the instruction stream, close
1403 enough to be reached with the 16-bit displacement. This jump instruction will
1404 transfer to the real desired target address. Thus, as long as the @code{.word}
1405 value really is used as a displacement to compute an address to jump to, the
1406 net effect will be correct (minus a very small efficiency cost). If
1407 @code{.word} directives with label differences for values are used for other
1408 purposes, however, things may not work properly. For targets which use broken
1409 words, the @samp{-K} option will warn when a broken word is discovered.
1411 The broken word code is turned off by the @code{WORKING_DOT_WORD} macro. It
1412 isn't needed if @code{.word} emits a value large enough to contain an address
1413 (or, more correctly, any possible difference between two addresses).
1415 @node Internal functions
1416 @section Internal functions
1418 This section describes basic internal functions used by GAS.
1421 * Warning and error messages:: Warning and error messages
1422 * Hash tables:: Hash tables
1425 @node Warning and error messages
1426 @subsection Warning and error messages
1428 @deftypefun @{@} int had_warnings (void)
1429 @deftypefunx @{@} int had_errors (void)
1430 Returns non-zero if any warnings or errors, respectively, have been printed
1431 during this invocation.
1434 @deftypefun @{@} void as_perror (const char *@var{gripe}, const char *@var{filename})
1435 Displays a BFD or system error, then clears the error status.
1438 @deftypefun @{@} void as_tsktsk (const char *@var{format}, ...)
1439 @deftypefunx @{@} void as_warn (const char *@var{format}, ...)
1440 @deftypefunx @{@} void as_bad (const char *@var{format}, ...)
1441 @deftypefunx @{@} void as_fatal (const char *@var{format}, ...)
1442 These functions display messages about something amiss with the input file, or
1443 internal problems in the assembler itself. The current file name and line
1444 number are printed, followed by the supplied message, formatted using
1445 @code{vfprintf}, and a final newline.
1447 An error indicated by @code{as_bad} will result in a non-zero exit status when
1448 the assembler has finished. Calling @code{as_fatal} will result in immediate
1449 termination of the assembler process.
1452 @deftypefun @{@} void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
1453 @deftypefunx @{@} void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...)
1454 These variants permit specification of the file name and line number, and are
1455 used when problems are detected when reprocessing information saved away when
1456 processing some earlier part of the file. For example, fixups are processed
1457 after all input has been read, but messages about fixups should refer to the
1458 original filename and line number that they are applicable to.
1461 @deftypefun @{@} void fprint_value (FILE *@var{file}, valueT @var{val})
1462 @deftypefunx @{@} void sprint_value (char *@var{buf}, valueT @var{val})
1463 These functions are helpful for converting a @code{valueT} value into printable
1464 format, in case it's wider than modes that @code{*printf} can handle. If the
1465 type is narrow enough, a decimal number will be produced; otherwise, it will be
1466 in hexadecimal. The value itself is not examined to make this determination.
1470 @subsection Hash tables
1473 @deftypefun @{@} @{struct hash_control *@} hash_new (void)
1474 Creates the hash table control structure.
1477 @deftypefun @{@} void hash_die (struct hash_control *)
1478 Destroy a hash table.
1481 @deftypefun @{@} PTR hash_delete (struct hash_control *, const char *)
1482 Deletes entry from the hash table, returns the value it had.
1485 @deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR)
1486 Updates the value for an entry already in the table, returning the old value.
1487 If no entry was found, just returns NULL.
1490 @deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR)
1491 Inserting a value already in the table is an error.
1492 Returns an error message or NULL.
1495 @deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR)
1496 Inserts if the value isn't already present, updates it if it is.
1503 The test suite is kind of lame for most processors. Often it only checks to
1504 see if a couple of files can be assembled without the assembler reporting any
1505 errors. For more complete testing, write a test which either examines the
1506 assembler listing, or runs @code{objdump} and examines its output. For the
1507 latter, the TCL procedure @code{run_dump_test} may come in handy. It takes the
1508 base name of a file, and looks for @file{@var{file}.d}. This file should
1509 contain as its initial lines a set of variable settings in @samp{#} comments,
1513 #@var{varname}: @var{value}
1516 The @var{varname} may be @code{objdump}, @code{nm}, or @code{as}, in which case
1517 it specifies the options to be passed to the specified programs. Exactly one
1518 of @code{objdump} or @code{nm} must be specified, as that also specifies which
1519 program to run after the assembler has finished. If @var{varname} is
1520 @code{source}, it specifies the name of the source file; otherwise,
1521 @file{@var{file}.s} is used. If @var{varname} is @code{name}, it specifies the
1522 name of the test to be used in the @code{pass} or @code{fail} messages.
1524 The non-commented parts of the file are interpreted as regular expressions, one
1525 per line. Blank lines in the @code{objdump} or @code{nm} output are skipped,
1526 as are blank lines in the @code{.d} file; the other lines are tested to see if
1527 the regular expression matches the program output. If it does not, the test
1530 Note that this means the tests must be modified if the @code{objdump} output