133965Sjdp\input texinfo 278828Sobrien@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 3218822Sdim@c 2001, 2002, 2003, 2004, 2005, 2006 478828Sobrien@c Free Software Foundation, Inc. 533965Sjdp@setfilename internals.info 633965Sjdp@node Top 733965Sjdp@top Assembler Internals 833965Sjdp@raisesections 933965Sjdp@cindex internals 1033965Sjdp 1133965SjdpThis chapter describes the internals of the assembler. It is incomplete, but 1233965Sjdpit may help a bit. 1333965Sjdp 1477298SobrienThis chapter is not updated regularly, and it may be out of date. 1533965Sjdp 1633965Sjdp@menu 1733965Sjdp* Data types:: Data types 1833965Sjdp* GAS processing:: What GAS does when it runs 1933965Sjdp* Porting GAS:: Porting GAS 2033965Sjdp* Relaxation:: Relaxation 2133965Sjdp* Broken words:: Broken words 2233965Sjdp* Internal functions:: Internal functions 2333965Sjdp* Test suite:: Test suite 2433965Sjdp@end menu 2533965Sjdp 2633965Sjdp@node Data types 2733965Sjdp@section Data types 2833965Sjdp@cindex internals, data types 2933965Sjdp 3033965SjdpThis section describes some fundamental GAS data types. 3133965Sjdp 3233965Sjdp@menu 3333965Sjdp* Symbols:: The symbolS structure 3433965Sjdp* Expressions:: The expressionS structure 3533965Sjdp* Fixups:: The fixS structure 3633965Sjdp* Frags:: The fragS structure 3733965Sjdp@end menu 3833965Sjdp 3933965Sjdp@node Symbols 4033965Sjdp@subsection Symbols 4133965Sjdp@cindex internals, symbols 4233965Sjdp@cindex symbols, internal 4333965Sjdp@cindex symbolS structure 4433965Sjdp 4560484SobrienThe definition for the symbol structure, @code{symbolS}, is located in 4660484Sobrien@file{struc-symbol.h}. 4733965Sjdp 4860484SobrienIn general, the fields of this structure may not be referred to directly. 4960484SobrienInstead, you must use one of the accessor functions defined in @file{symbol.h}. 5060484SobrienThese accessor functions should work for any GAS version. 5160484Sobrien 5260484SobrienSymbol structures contain the following fields: 5360484Sobrien 5433965Sjdp@table @code 5533965Sjdp@item sy_value 5633965SjdpThis is an @code{expressionS} that describes the value of the symbol. It might 5733965Sjdprefer to one or more other symbols; if so, its true value may not be known 5889857Sobrienuntil @code{resolve_symbol_value} is called with @var{finalize_syms} non-zero 5989857Sobrienin @code{write_object_file}. 6033965Sjdp 6133965SjdpThe expression is often simply a constant. Before @code{resolve_symbol_value} 6289857Sobrienis called with @var{finalize_syms} set, the value is the offset from the frag 6389857Sobrien(@pxref{Frags}). Afterward, the frag address has been added in. 6433965Sjdp 6533965Sjdp@item sy_resolved 6633965SjdpThis field is non-zero if the symbol's value has been completely resolved. It 6733965Sjdpis used during the final pass over the symbol table. 6833965Sjdp 6933965Sjdp@item sy_resolving 7033965SjdpThis field is used to detect loops while resolving the symbol's value. 7133965Sjdp 7233965Sjdp@item sy_used_in_reloc 7333965SjdpThis field is non-zero if the symbol is used by a relocation entry. If a local 7433965Sjdpsymbol is used in a relocation entry, it must be possible to redirect those 7533965Sjdprelocations to other symbols, or this symbol cannot be removed from the final 7633965Sjdpsymbol list. 7733965Sjdp 7833965Sjdp@item sy_next 7933965Sjdp@itemx sy_previous 80218822SdimThese pointers to other @code{symbolS} structures describe a doubly 81218822Sdimlinked list. These fields should be accessed with 8233965Sjdpthe @code{symbol_next} and @code{symbol_previous} macros. 8333965Sjdp 8433965Sjdp@item sy_frag 8533965SjdpThis points to the frag (@pxref{Frags}) that this symbol is attached to. 8633965Sjdp 8733965Sjdp@item sy_used 8833965SjdpWhether the symbol is used as an operand or in an expression. Note: Not all of 8933965Sjdpthe backends keep this information accurate; backends which use this bit are 9033965Sjdpresponsible for setting it when a symbol is used in backend routines. 9133965Sjdp 9233965Sjdp@item sy_mri_common 9333965SjdpWhether the symbol is an MRI common symbol created by the @code{COMMON} 9433965Sjdppseudo-op when assembling in MRI mode. 9533965Sjdp 96218822Sdim@item sy_volatile 97218822SdimWhether the symbol can be re-defined. 9833965Sjdp 99218822Sdim@item sy_forward_ref 100218822SdimWhether the symbol's value must only be evaluated upon use. 10133965Sjdp 102218822Sdim@item sy_weakrefr 103218822SdimWhether the symbol is a @code{weakref} alias to another symbol. 10433965Sjdp 105218822Sdim@item sy_weakrefd 106218822SdimWhether the symbol is or was referenced by one or more @code{weakref} aliases, 107218822Sdimand has not had any direct references. 10833965Sjdp 109218822Sdim@item bsym 110218822SdimThis points to the BFD @code{asymbol} that 111218822Sdimwill be used in writing the object file. 112218822Sdim 11333965Sjdp@item sy_obj 11433965SjdpThis format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by 11533965Sjdpthat name is defined in @file{obj-format.h}, this field is not defined. 11633965Sjdp 11733965Sjdp@item sy_tc 11833965SjdpThis processor-specific data is of type @code{TC_SYMFIELD_TYPE}. If no macro 11933965Sjdpby that name is defined in @file{targ-cpu.h}, this field is not defined. 12033965Sjdp 12133965Sjdp@end table 12233965Sjdp 12360484SobrienHere is a description of the accessor functions. These should be used rather 12460484Sobrienthan referring to the fields of @code{symbolS} directly. 12533965Sjdp 12633965Sjdp@table @code 12733965Sjdp@item S_SET_VALUE 12833965Sjdp@cindex S_SET_VALUE 12933965SjdpSet the symbol's value. 13033965Sjdp 13133965Sjdp@item S_GET_VALUE 13233965Sjdp@cindex S_GET_VALUE 13333965SjdpGet the symbol's value. This will cause @code{resolve_symbol_value} to be 13489857Sobriencalled if necessary. 13533965Sjdp 13633965Sjdp@item S_SET_SEGMENT 13733965Sjdp@cindex S_SET_SEGMENT 13833965SjdpSet the section of the symbol. 13933965Sjdp 14033965Sjdp@item S_GET_SEGMENT 14133965Sjdp@cindex S_GET_SEGMENT 14233965SjdpGet the symbol's section. 14333965Sjdp 14433965Sjdp@item S_GET_NAME 14533965Sjdp@cindex S_GET_NAME 14633965SjdpGet the name of the symbol. 14733965Sjdp 14833965Sjdp@item S_SET_NAME 14933965Sjdp@cindex S_SET_NAME 15033965SjdpSet the name of the symbol. 15133965Sjdp 15233965Sjdp@item S_IS_EXTERNAL 15333965Sjdp@cindex S_IS_EXTERNAL 15433965SjdpReturn non-zero if the symbol is externally visible. 15533965Sjdp 15633965Sjdp@item S_IS_EXTERN 15733965Sjdp@cindex S_IS_EXTERN 15833965SjdpA synonym for @code{S_IS_EXTERNAL}. Don't use it. 15933965Sjdp 16033965Sjdp@item S_IS_WEAK 16133965Sjdp@cindex S_IS_WEAK 162218822SdimReturn non-zero if the symbol is weak, or if it is a @code{weakref} alias or 163218822Sdimsymbol that has not been strongly referenced. 16433965Sjdp 165218822Sdim@item S_IS_WEAKREFR 166218822Sdim@cindex S_IS_WEAKREFR 167218822SdimReturn non-zero if the symbol is a @code{weakref} alias. 168218822Sdim 169218822Sdim@item S_IS_WEAKREFD 170218822Sdim@cindex S_IS_WEAKREFD 171218822SdimReturn non-zero if the symbol was aliased by a @code{weakref} alias and has not 172218822Sdimhad any strong references. 173218822Sdim 174218822Sdim@item S_IS_VOLATILE 175218822Sdim@cindex S_IS_VOLATILE 176218822SdimReturn non-zero if the symbol may be re-defined. Such symbols get created by 177218822Sdimthe @code{=} operator, @code{equ}, or @code{set}. 178218822Sdim 179218822Sdim@item S_IS_FORWARD_REF 180218822Sdim@cindex S_IS_FORWARD_REF 181218822SdimReturn non-zero if the symbol is a forward reference, that is its value must 182218822Sdimonly be determined upon use. 183218822Sdim 18433965Sjdp@item S_IS_COMMON 18533965Sjdp@cindex S_IS_COMMON 18633965SjdpReturn non-zero if this is a common symbol. Common symbols are sometimes 18733965Sjdprepresented as undefined symbols with a value, in which case this function will 18833965Sjdpnot be reliable. 18933965Sjdp 19033965Sjdp@item S_IS_DEFINED 19133965Sjdp@cindex S_IS_DEFINED 19233965SjdpReturn non-zero if this symbol is defined. This function is not reliable when 19333965Sjdpcalled on a common symbol. 19433965Sjdp 19533965Sjdp@item S_IS_DEBUG 19633965Sjdp@cindex S_IS_DEBUG 19733965SjdpReturn non-zero if this is a debugging symbol. 19833965Sjdp 19933965Sjdp@item S_IS_LOCAL 20033965Sjdp@cindex S_IS_LOCAL 20133965SjdpReturn non-zero if this is a local assembler symbol which should not be 20233965Sjdpincluded in the final symbol table. Note that this is not the opposite of 20333965Sjdp@code{S_IS_EXTERNAL}. The @samp{-L} assembler option affects the return value 20433965Sjdpof this function. 20533965Sjdp 20633965Sjdp@item S_SET_EXTERNAL 20733965Sjdp@cindex S_SET_EXTERNAL 20833965SjdpMark the symbol as externally visible. 20933965Sjdp 21033965Sjdp@item S_CLEAR_EXTERNAL 21133965Sjdp@cindex S_CLEAR_EXTERNAL 21233965SjdpMark the symbol as not externally visible. 21333965Sjdp 21433965Sjdp@item S_SET_WEAK 21533965Sjdp@cindex S_SET_WEAK 21633965SjdpMark the symbol as weak. 21733965Sjdp 218218822Sdim@item S_SET_WEAKREFR 219218822Sdim@cindex S_SET_WEAKREFR 220218822SdimMark the symbol as the referrer in a @code{weakref} directive. The symbol it 221218822Sdimaliases must have been set to the value expression before this point. If the 222218822Sdimalias has already been used, the symbol is marked as used too. 223218822Sdim 224218822Sdim@item S_CLEAR_WEAKREFR 225218822Sdim@cindex S_CLEAR_WEAKREFR 226218822SdimClear the @code{weakref} alias status of a symbol. This is implicitly called 227218822Sdimwhenever a symbol is defined or set to a new expression. 228218822Sdim 229218822Sdim@item S_SET_WEAKREFD 230218822Sdim@cindex S_SET_WEAKREFD 231218822SdimMark the symbol as the referred symbol in a @code{weakref} directive. 232218822SdimImplicitly marks the symbol as weak, but see below. It should only be called 233218822Sdimif the referenced symbol has just been added to the symbol table. 234218822Sdim 235218822Sdim@item S_SET_WEAKREFD 236218822Sdim@cindex S_SET_WEAKREFD 237218822SdimClear the @code{weakref} aliased status of a symbol. This is implicitly called 238218822Sdimwhenever the symbol is looked up, as part of a direct reference or a 239218822Sdimdefinition, but not as part of a @code{weakref} directive. 240218822Sdim 241218822Sdim@item S_SET_VOLATILE 242218822Sdim@cindex S_SET_VOLATILE 243218822SdimIndicate that the symbol may be re-defined. 244218822Sdim 245218822Sdim@item S_CLEAR_VOLATILE 246218822Sdim@cindex S_CLEAR_VOLATILE 247218822SdimIndicate that the symbol may no longer be re-defined. 248218822Sdim 249218822Sdim@item S_SET_FORWARD_REF 250218822Sdim@cindex S_SET_FORWARD_REF 251218822SdimIndicate that the symbol is a forward reference, that is its value must only 252218822Sdimbe determined upon use. 253218822Sdim 25433965Sjdp@item S_GET_TYPE 25533965Sjdp@item S_GET_DESC 25633965Sjdp@item S_GET_OTHER 25733965Sjdp@cindex S_GET_TYPE 25833965Sjdp@cindex S_GET_DESC 25933965Sjdp@cindex S_GET_OTHER 26033965SjdpGet the @code{type}, @code{desc}, and @code{other} fields of the symbol. These 26133965Sjdpare only defined for object file formats for which they make sense (primarily 26233965Sjdpa.out). 26333965Sjdp 26433965Sjdp@item S_SET_TYPE 26533965Sjdp@item S_SET_DESC 26633965Sjdp@item S_SET_OTHER 26733965Sjdp@cindex S_SET_TYPE 26833965Sjdp@cindex S_SET_DESC 26933965Sjdp@cindex S_SET_OTHER 27033965SjdpSet the @code{type}, @code{desc}, and @code{other} fields of the symbol. These 27133965Sjdpare only defined for object file formats for which they make sense (primarily 27233965Sjdpa.out). 27333965Sjdp 27433965Sjdp@item S_GET_SIZE 27533965Sjdp@cindex S_GET_SIZE 27633965SjdpGet the size of a symbol. This is only defined for object file formats for 27733965Sjdpwhich it makes sense (primarily ELF). 27833965Sjdp 27933965Sjdp@item S_SET_SIZE 28033965Sjdp@cindex S_SET_SIZE 28133965SjdpSet the size of a symbol. This is only defined for object file formats for 28233965Sjdpwhich it makes sense (primarily ELF). 28360484Sobrien 28460484Sobrien@item symbol_get_value_expression 28560484Sobrien@cindex symbol_get_value_expression 28660484SobrienGet a pointer to an @code{expressionS} structure which represents the value of 28760484Sobrienthe symbol as an expression. 28860484Sobrien 28960484Sobrien@item symbol_set_value_expression 29060484Sobrien@cindex symbol_set_value_expression 29160484SobrienSet the value of a symbol to an expression. 29260484Sobrien 29360484Sobrien@item symbol_set_frag 29460484Sobrien@cindex symbol_set_frag 29560484SobrienSet the frag where a symbol is defined. 29660484Sobrien 29760484Sobrien@item symbol_get_frag 29860484Sobrien@cindex symbol_get_frag 29960484SobrienGet the frag where a symbol is defined. 30060484Sobrien 30160484Sobrien@item symbol_mark_used 30260484Sobrien@cindex symbol_mark_used 30360484SobrienMark a symbol as having been used in an expression. 30460484Sobrien 30560484Sobrien@item symbol_clear_used 30660484Sobrien@cindex symbol_clear_used 30760484SobrienClear the mark indicating that a symbol was used in an expression. 30860484Sobrien 30960484Sobrien@item symbol_used_p 31060484Sobrien@cindex symbol_used_p 31160484SobrienReturn whether a symbol was used in an expression. 31260484Sobrien 31360484Sobrien@item symbol_mark_used_in_reloc 31460484Sobrien@cindex symbol_mark_used_in_reloc 31560484SobrienMark a symbol as having been used by a relocation. 31660484Sobrien 31760484Sobrien@item symbol_clear_used_in_reloc 31860484Sobrien@cindex symbol_clear_used_in_reloc 31960484SobrienClear the mark indicating that a symbol was used in a relocation. 32060484Sobrien 32160484Sobrien@item symbol_used_in_reloc_p 32260484Sobrien@cindex symbol_used_in_reloc_p 32360484SobrienReturn whether a symbol was used in a relocation. 32460484Sobrien 32560484Sobrien@item symbol_mark_mri_common 32660484Sobrien@cindex symbol_mark_mri_common 32760484SobrienMark a symbol as an MRI common symbol. 32860484Sobrien 32960484Sobrien@item symbol_clear_mri_common 33060484Sobrien@cindex symbol_clear_mri_common 33160484SobrienClear the mark indicating that a symbol is an MRI common symbol. 33260484Sobrien 33360484Sobrien@item symbol_mri_common_p 33460484Sobrien@cindex symbol_mri_common_p 33560484SobrienReturn whether a symbol is an MRI common symbol. 33660484Sobrien 33760484Sobrien@item symbol_mark_written 33860484Sobrien@cindex symbol_mark_written 33960484SobrienMark a symbol as having been written. 34060484Sobrien 34160484Sobrien@item symbol_clear_written 34260484Sobrien@cindex symbol_clear_written 34360484SobrienClear the mark indicating that a symbol was written. 34460484Sobrien 34560484Sobrien@item symbol_written_p 34660484Sobrien@cindex symbol_written_p 34760484SobrienReturn whether a symbol was written. 34860484Sobrien 34960484Sobrien@item symbol_mark_resolved 35060484Sobrien@cindex symbol_mark_resolved 35160484SobrienMark a symbol as having been resolved. 35260484Sobrien 35360484Sobrien@item symbol_resolved_p 35460484Sobrien@cindex symbol_resolved_p 35560484SobrienReturn whether a symbol has been resolved. 35660484Sobrien 35760484Sobrien@item symbol_section_p 35860484Sobrien@cindex symbol_section_p 35960484SobrienReturn whether a symbol is a section symbol. 36060484Sobrien 36160484Sobrien@item symbol_equated_p 36260484Sobrien@cindex symbol_equated_p 36360484SobrienReturn whether a symbol is equated to another symbol. 36460484Sobrien 36560484Sobrien@item symbol_constant_p 36660484Sobrien@cindex symbol_constant_p 36760484SobrienReturn whether a symbol has a constant value, including being an offset within 36860484Sobriensome frag. 36960484Sobrien 37060484Sobrien@item symbol_get_bfdsym 37160484Sobrien@cindex symbol_get_bfdsym 37260484SobrienReturn the BFD symbol associated with a symbol. 37360484Sobrien 37460484Sobrien@item symbol_set_bfdsym 37560484Sobrien@cindex symbol_set_bfdsym 37660484SobrienSet the BFD symbol associated with a symbol. 37760484Sobrien 37860484Sobrien@item symbol_get_obj 37960484Sobrien@cindex symbol_get_obj 38060484SobrienReturn a pointer to the @code{OBJ_SYMFIELD_TYPE} field of a symbol. 38160484Sobrien 38260484Sobrien@item symbol_set_obj 38360484Sobrien@cindex symbol_set_obj 38460484SobrienSet the @code{OBJ_SYMFIELD_TYPE} field of a symbol. 38560484Sobrien 38660484Sobrien@item symbol_get_tc 38760484Sobrien@cindex symbol_get_tc 38860484SobrienReturn a pointer to the @code{TC_SYMFIELD_TYPE} field of a symbol. 38960484Sobrien 39060484Sobrien@item symbol_set_tc 39160484Sobrien@cindex symbol_set_tc 39260484SobrienSet the @code{TC_SYMFIELD_TYPE} field of a symbol. 39360484Sobrien 39433965Sjdp@end table 39533965Sjdp 396218822SdimGAS attempts to store local 39760484Sobriensymbols--symbols which will not be written to the output file--using a 39860484Sobriendifferent structure, @code{struct local_symbol}. This structure can only 39960484Sobrienrepresent symbols whose value is an offset within a frag. 40060484Sobrien 40160484SobrienCode outside of the symbol handler will always deal with @code{symbolS} 40260484Sobrienstructures and use the accessor functions. The accessor functions correctly 40360484Sobriendeal with local symbols. @code{struct local_symbol} is much smaller than 40460484Sobrien@code{symbolS} (which also automatically creates a bfd @code{asymbol} 40560484Sobrienstructure), so this saves space when assembling large files. 40660484Sobrien 40760484SobrienThe first field of @code{symbolS} is @code{bsym}, the pointer to the BFD 40860484Sobriensymbol. The first field of @code{struct local_symbol} is a pointer which is 40960484Sobrienalways set to NULL. This is how the symbol accessor functions can distinguish 41060484Sobrienlocal symbols from ordinary symbols. The symbol accessor functions 41160484Sobrienautomatically convert a local symbol into an ordinary symbol when necessary. 41260484Sobrien 41333965Sjdp@node Expressions 41433965Sjdp@subsection Expressions 41533965Sjdp@cindex internals, expressions 41633965Sjdp@cindex expressions, internal 41733965Sjdp@cindex expressionS structure 41833965Sjdp 41933965SjdpExpressions are stored in an @code{expressionS} structure. The structure is 42033965Sjdpdefined in @file{expr.h}. 42133965Sjdp 42233965Sjdp@cindex expression 42333965SjdpThe macro @code{expression} will create an @code{expressionS} structure based 42433965Sjdpon the text found at the global variable @code{input_line_pointer}. 42533965Sjdp 42633965Sjdp@cindex make_expr_symbol 42733965Sjdp@cindex expr_symbol_where 42833965SjdpA single @code{expressionS} structure can represent a single operation. 42933965SjdpComplex expressions are formed by creating @dfn{expression symbols} and 43033965Sjdpcombining them in @code{expressionS} structures. An expression symbol is 43133965Sjdpcreated by calling @code{make_expr_symbol}. An expression symbol should 43233965Sjdpnaturally never appear in a symbol table, and the implementation of 43333965Sjdp@code{S_IS_LOCAL} (@pxref{Symbols}) reflects that. The function 43433965Sjdp@code{expr_symbol_where} returns non-zero if a symbol is an expression symbol, 43533965Sjdpand also returns the file and line for the expression which caused it to be 43633965Sjdpcreated. 43733965Sjdp 43833965SjdpThe @code{expressionS} structure has two symbol fields, a number field, an 43933965Sjdpoperator field, and a field indicating whether the number is unsigned. 44033965Sjdp 44133965SjdpThe operator field is of type @code{operatorT}, and describes how to interpret 44233965Sjdpthe other fields; see the definition in @file{expr.h} for the possibilities. 44333965Sjdp 44433965SjdpAn @code{operatorT} value of @code{O_big} indicates either a floating point 44533965Sjdpnumber, stored in the global variable @code{generic_floating_point_number}, or 44677298Sobrienan integer too large to store in an @code{offsetT} type, stored in the global 44733965Sjdparray @code{generic_bignum}. This rather inflexible approach makes it 44833965Sjdpimpossible to use floating point numbers or large expressions in complex 44933965Sjdpexpressions. 45033965Sjdp 45133965Sjdp@node Fixups 45233965Sjdp@subsection Fixups 45333965Sjdp@cindex internals, fixups 45433965Sjdp@cindex fixups 45533965Sjdp@cindex fixS structure 45633965Sjdp 45733965SjdpA @dfn{fixup} is basically anything which can not be resolved in the first 45833965Sjdppass. Sometimes a fixup can be resolved by the end of the assembly; if not, 45933965Sjdpthe fixup becomes a relocation entry in the object file. 46033965Sjdp 46133965Sjdp@cindex fix_new 46233965Sjdp@cindex fix_new_exp 46333965SjdpA fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both 46433965Sjdptake a frag (@pxref{Frags}), a position within the frag, a size, an indication 465218822Sdimof whether the fixup is PC relative, and a type. 466218822SdimThe type is nominally a @code{bfd_reloc_code_real_type}, but several 46733965Sjdptargets use other type codes to represent fixups that can not be described as 46833965Sjdprelocations. 46933965Sjdp 47033965SjdpThe @code{fixS} structure has a number of fields, several of which are obsolete 47133965Sjdpor are only used by a particular target. The important fields are: 47233965Sjdp 47333965Sjdp@table @code 47433965Sjdp@item fx_frag 47533965SjdpThe frag (@pxref{Frags}) this fixup is in. 47633965Sjdp 47733965Sjdp@item fx_where 47833965SjdpThe location within the frag where the fixup occurs. 47933965Sjdp 48033965Sjdp@item fx_addsy 48133965SjdpThe symbol this fixup is against. Typically, the value of this symbol is added 48233965Sjdpinto the object contents. This may be NULL. 48333965Sjdp 48433965Sjdp@item fx_subsy 48533965SjdpThe value of this symbol is subtracted from the object contents. This is 48633965Sjdpnormally NULL. 48733965Sjdp 48833965Sjdp@item fx_offset 48933965SjdpA number which is added into the fixup. 49033965Sjdp 49133965Sjdp@item fx_addnumber 49233965SjdpSome CPU backends use this field to convey information between 493218822Sdim@code{md_apply_fix} and @code{tc_gen_reloc}. The machine independent code does 49433965Sjdpnot use it. 49533965Sjdp 49633965Sjdp@item fx_next 49733965SjdpThe next fixup in the section. 49833965Sjdp 49933965Sjdp@item fx_r_type 500218822SdimThe type of the fixup. 50133965Sjdp 50233965Sjdp@item fx_size 50333965SjdpThe size of the fixup. This is mostly used for error checking. 50433965Sjdp 50533965Sjdp@item fx_pcrel 50633965SjdpWhether the fixup is PC relative. 50733965Sjdp 50833965Sjdp@item fx_done 50933965SjdpNon-zero if the fixup has been applied, and no relocation entry needs to be 51033965Sjdpgenerated. 51133965Sjdp 51233965Sjdp@item fx_file 51333965Sjdp@itemx fx_line 51433965SjdpThe file and line where the fixup was created. 51533965Sjdp 51633965Sjdp@item tc_fix_data 51733965SjdpThis has the type @code{TC_FIX_TYPE}, and is only defined if the target defines 51833965Sjdpthat macro. 51933965Sjdp@end table 52033965Sjdp 52133965Sjdp@node Frags 52233965Sjdp@subsection Frags 52333965Sjdp@cindex internals, frags 52433965Sjdp@cindex frags 52533965Sjdp@cindex fragS structure. 52633965Sjdp 52733965SjdpThe @code{fragS} structure is defined in @file{as.h}. Each frag represents a 52833965Sjdpportion of the final object file. As GAS reads the source file, it creates 52933965Sjdpfrags to hold the data that it reads. At the end of the assembly the frags and 53033965Sjdpfixups are processed to produce the final contents. 53133965Sjdp 53233965Sjdp@table @code 53333965Sjdp@item fr_address 53433965SjdpThe address of the frag. This is not set until the assembler rescans the list 53533965Sjdpof all frags after the entire input file is parsed. The function 53633965Sjdp@code{relax_segment} fills in this field. 53733965Sjdp 53833965Sjdp@item fr_next 53933965SjdpPointer to the next frag in this (sub)section. 54033965Sjdp 54133965Sjdp@item fr_fix 54233965SjdpFixed number of characters we know we're going to emit to the output file. May 54333965Sjdpbe zero. 54433965Sjdp 54533965Sjdp@item fr_var 54633965SjdpVariable number of characters we may output, after the initial @code{fr_fix} 54733965Sjdpcharacters. May be zero. 54833965Sjdp 54933965Sjdp@item fr_offset 55033965SjdpThe interpretation of this field is controlled by @code{fr_type}. Generally, 55133965Sjdpif @code{fr_var} is non-zero, this is a repeat count: the @code{fr_var} 55233965Sjdpcharacters are output @code{fr_offset} times. 55333965Sjdp 55433965Sjdp@item line 55533965SjdpHolds line number info when an assembler listing was requested. 55633965Sjdp 55733965Sjdp@item fr_type 55833965SjdpRelaxation state. This field indicates the interpretation of @code{fr_offset}, 55933965Sjdp@code{fr_symbol} and the variable-length tail of the frag, as well as the 56033965Sjdptreatment it gets in various phases of processing. It does not affect the 56133965Sjdpinitial @code{fr_fix} characters; they are always supposed to be output 56233965Sjdpverbatim (fixups aside). See below for specific values this field can have. 56333965Sjdp 56433965Sjdp@item fr_subtype 56533965SjdpRelaxation substate. If the macro @code{md_relax_frag} isn't defined, this is 56633965Sjdpassumed to be an index into @code{TC_GENERIC_RELAX_TABLE} for the generic 56733965Sjdprelaxation code to process (@pxref{Relaxation}). If @code{md_relax_frag} is 56833965Sjdpdefined, this field is available for any use by the CPU-specific code. 56933965Sjdp 57033965Sjdp@item fr_symbol 57133965SjdpThis normally indicates the symbol to use when relaxing the frag according to 57233965Sjdp@code{fr_type}. 57333965Sjdp 57433965Sjdp@item fr_opcode 57533965SjdpPoints to the lowest-addressed byte of the opcode, for use in relaxation. 57633965Sjdp 57738889Sjdp@item tc_frag_data 57838889SjdpTarget specific fragment data of type TC_FRAG_TYPE. 57938889SjdpOnly present if @code{TC_FRAG_TYPE} is defined. 58033965Sjdp 58133965Sjdp@item fr_file 58233965Sjdp@itemx fr_line 58333965SjdpThe file and line where this frag was last modified. 58433965Sjdp 58533965Sjdp@item fr_literal 58633965SjdpDeclared as a one-character array, this last field grows arbitrarily large to 58733965Sjdphold the actual contents of the frag. 58833965Sjdp@end table 58933965Sjdp 59033965SjdpThese are the possible relaxation states, provided in the enumeration type 59133965Sjdp@code{relax_stateT}, and the interpretations they represent for the other 59233965Sjdpfields: 59333965Sjdp 59433965Sjdp@table @code 59533965Sjdp@item rs_align 59633965Sjdp@itemx rs_align_code 59733965SjdpThe start of the following frag should be aligned on some boundary. In this 59833965Sjdpfrag, @code{fr_offset} is the logarithm (base 2) of the alignment in bytes. 59933965Sjdp(For example, if alignment on an 8-byte boundary were desired, @code{fr_offset} 60033965Sjdpwould have a value of 3.) The variable characters indicate the fill pattern to 60133965Sjdpbe used. The @code{fr_subtype} field holds the maximum number of bytes to skip 60233965Sjdpwhen doing this alignment. If more bytes are needed, the alignment is not 60333965Sjdpdone. An @code{fr_subtype} value of 0 means no maximum, which is the normal 60433965Sjdpcase. Target backends can use @code{rs_align_code} to handle certain types of 60533965Sjdpalignment differently. 60633965Sjdp 60733965Sjdp@item rs_broken_word 60833965SjdpThis indicates that ``broken word'' processing should be done (@pxref{Broken 60933965Sjdpwords}). If broken word processing is not necessary on the target machine, 61033965Sjdpthis enumerator value will not be defined. 61133965Sjdp 61238889Sjdp@item rs_cfa 61338889SjdpThis state is used to implement exception frame optimizations. The 61438889Sjdp@code{fr_symbol} is an expression symbol for the subtraction which may be 61538889Sjdprelaxed. The @code{fr_opcode} field holds the frag for the preceding command 61638889Sjdpbyte. The @code{fr_offset} field holds the offset within that frag. The 61738889Sjdp@code{fr_subtype} field is used during relaxation to hold the current size of 61838889Sjdpthe frag. 61938889Sjdp 62033965Sjdp@item rs_fill 62133965SjdpThe variable characters are to be repeated @code{fr_offset} times. If 62233965Sjdp@code{fr_offset} is 0, this frag has a length of @code{fr_fix}. Most frags 62333965Sjdphave this type. 62433965Sjdp 62538889Sjdp@item rs_leb128 62677298SobrienThis state is used to implement the DWARF ``little endian base 128'' 62738889Sjdpvariable length number format. The @code{fr_symbol} is always an expression 62838889Sjdpsymbol, as constant expressions are emitted directly. The @code{fr_offset} 62938889Sjdpfield is used during relaxation to hold the previous size of the number so 63038889Sjdpthat we can determine if the fragment changed size. 63138889Sjdp 63233965Sjdp@item rs_machine_dependent 63333965SjdpDisplacement relaxation is to be done on this frag. The target is indicated by 63433965Sjdp@code{fr_symbol} and @code{fr_offset}, and @code{fr_subtype} indicates the 63533965Sjdpparticular machine-specific addressing mode desired. @xref{Relaxation}. 63633965Sjdp 63733965Sjdp@item rs_org 63833965SjdpThe start of the following frag should be pushed back to some specific offset 63933965Sjdpwithin the section. (Some assemblers use the value as an absolute address; GAS 64033965Sjdpdoes not handle final absolute addresses, but rather requires that the linker 64133965Sjdpset them.) The offset is given by @code{fr_symbol} and @code{fr_offset}; one 64233965Sjdpcharacter from the variable-length tail is used as the fill character. 64333965Sjdp@end table 64433965Sjdp 64533965Sjdp@cindex frchainS structure 64633965SjdpA chain of frags is built up for each subsection. The data structure 64733965Sjdpdescribing a chain is called a @code{frchainS}, and contains the following 64833965Sjdpfields: 64933965Sjdp 65033965Sjdp@table @code 65133965Sjdp@item frch_root 65233965SjdpPoints to the first frag in the chain. May be NULL if there are no frags in 65333965Sjdpthis chain. 65433965Sjdp@item frch_last 65533965SjdpPoints to the last frag in the chain, or NULL if there are none. 65633965Sjdp@item frch_next 65733965SjdpNext in the list of @code{frchainS} structures. 65833965Sjdp@item frch_seg 65933965SjdpIndicates the section this frag chain belongs to. 66033965Sjdp@item frch_subseg 66133965SjdpSubsection (subsegment) number of this frag chain. 66233965Sjdp@item fix_root, fix_tail 663218822SdimPoint to first and last @code{fixS} structures associated with this subsection. 66433965Sjdp@item frch_obstack 66533965SjdpNot currently used. Intended to be used for frag allocation for this 66633965Sjdpsubsection. This should reduce frag generation caused by switching sections. 66733965Sjdp@item frch_frag_now 66833965SjdpThe current frag for this subsegment. 66933965Sjdp@end table 67033965Sjdp 67133965SjdpA @code{frchainS} corresponds to a subsection; each section has a list of 67233965Sjdp@code{frchainS} records associated with it. In most cases, only one subsection 67333965Sjdpof each section is used, so the list will only be one element long, but any 67433965Sjdpprocessing of frag chains should be prepared to deal with multiple chains per 67533965Sjdpsection. 67633965Sjdp 67733965SjdpAfter the input files have been completely processed, and no more frags are to 67833965Sjdpbe generated, the frag chains are joined into one per section for further 67933965Sjdpprocessing. After this point, it is safe to operate on one chain per section. 68033965Sjdp 68133965SjdpThe assembler always has a current frag, named @code{frag_now}. More space is 68233965Sjdpallocated for the current frag using the @code{frag_more} function; this 683130561Sobrienreturns a pointer to the amount of requested space. The function 684130561Sobrien@code{frag_room} says by how much the current frag can be extended. 685130561SobrienRelaxing is done using variant frags allocated by @code{frag_var} 686130561Sobrienor @code{frag_variant} (@pxref{Relaxation}). 68733965Sjdp 68833965Sjdp@node GAS processing 68933965Sjdp@section What GAS does when it runs 69033965Sjdp@cindex internals, overview 69133965Sjdp 69233965SjdpThis is a quick look at what an assembler run looks like. 69333965Sjdp 69433965Sjdp@itemize @bullet 69533965Sjdp@item 69633965SjdpThe assembler initializes itself by calling various init routines. 69733965Sjdp 69833965Sjdp@item 69933965SjdpFor each source file, the @code{read_a_source_file} function reads in the file 70033965Sjdpand parses it. The global variable @code{input_line_pointer} points to the 70133965Sjdpcurrent text; it is guaranteed to be correct up to the end of the line, but not 70233965Sjdpfarther. 70333965Sjdp 70433965Sjdp@item 70533965SjdpFor each line, the assembler passes labels to the @code{colon} function, and 70633965Sjdpisolates the first word. If it looks like a pseudo-op, the word is looked up 70733965Sjdpin the pseudo-op hash table @code{po_hash} and dispatched to a pseudo-op 70833965Sjdproutine. Otherwise, the target dependent @code{md_assemble} routine is called 70933965Sjdpto parse the instruction. 71033965Sjdp 71133965Sjdp@item 71233965SjdpWhen pseudo-ops or instructions output data, they add it to a frag, calling 71333965Sjdp@code{frag_more} to get space to store it in. 71433965Sjdp 71533965Sjdp@item 71633965SjdpPseudo-ops and instructions can also output fixups created by @code{fix_new} or 71733965Sjdp@code{fix_new_exp}. 71833965Sjdp 71933965Sjdp@item 72033965SjdpFor certain targets, instructions can create variant frags which are used to 72133965Sjdpstore relaxation information (@pxref{Relaxation}). 72233965Sjdp 72333965Sjdp@item 72433965SjdpWhen the input file is finished, the @code{write_object_file} routine is 72533965Sjdpcalled. It assigns addresses to all the frags (@code{relax_segment}), resolves 72633965Sjdpall the fixups (@code{fixup_segment}), resolves all the symbol values (using 727218822Sdim@code{resolve_symbol_value}), and finally writes out the file. 72833965Sjdp@end itemize 72933965Sjdp 73033965Sjdp@node Porting GAS 73133965Sjdp@section Porting GAS 73233965Sjdp@cindex porting 73333965Sjdp 73433965SjdpEach GAS target specifies two main things: the CPU file and the object format 73533965Sjdpfile. Two main switches in the @file{configure.in} file handle this. The 73633965Sjdpfirst switches on CPU type to set the shell variable @code{cpu_type}. The 73733965Sjdpsecond switches on the entire target to set the shell variable @code{fmt}. 73833965Sjdp 73933965SjdpThe configure script uses the value of @code{cpu_type} to select two files in 74033965Sjdpthe @file{config} directory: @file{tc-@var{CPU}.c} and @file{tc-@var{CPU}.h}. 74133965SjdpThe configuration process will create a file named @file{targ-cpu.h} in the 74233965Sjdpbuild directory which includes @file{tc-@var{CPU}.h}. 74333965Sjdp 74433965SjdpThe configure script also uses the value of @code{fmt} to select two files: 74533965Sjdp@file{obj-@var{fmt}.c} and @file{obj-@var{fmt}.h}. The configuration process 74633965Sjdpwill create a file named @file{obj-format.h} in the build directory which 74733965Sjdpincludes @file{obj-@var{fmt}.h}. 74833965Sjdp 74933965SjdpYou can also set the emulation in the configure script by setting the @code{em} 75033965Sjdpvariable. Normally the default value of @samp{generic} is fine. The 75133965Sjdpconfiguration process will create a file named @file{targ-env.h} in the build 75233965Sjdpdirectory which includes @file{te-@var{em}.h}. 75333965Sjdp 75477298SobrienThere is a special case for COFF. For historical reason, the GNU COFF 75577298Sobrienassembler doesn't follow the documented behavior on certain debug symbols for 75677298Sobrienthe compatibility with other COFF assemblers. A port can define 75777298Sobrien@code{STRICTCOFF} in the configure script to make the GNU COFF assembler 75877298Sobriento follow the documented behavior. 75977298Sobrien 76033965SjdpPorting GAS to a new CPU requires writing the @file{tc-@var{CPU}} files. 76133965SjdpPorting GAS to a new object file format requires writing the 76233965Sjdp@file{obj-@var{fmt}} files. There is sometimes some interaction between these 76333965Sjdptwo files, but it is normally minimal. 76433965Sjdp 76533965SjdpThe best approach is, of course, to copy existing files. The documentation 76633965Sjdpbelow assumes that you are looking at existing files to see usage details. 76733965Sjdp 76833965SjdpThese interfaces have grown over time, and have never been carefully thought 76933965Sjdpout or designed. Nothing about the interfaces described here is cast in stone. 77033965SjdpIt is possible that they will change from one version of the assembler to the 77133965Sjdpnext. Also, new macros are added all the time as they are needed. 77233965Sjdp 77333965Sjdp@menu 77433965Sjdp* CPU backend:: Writing a CPU backend 77533965Sjdp* Object format backend:: Writing an object format backend 77633965Sjdp* Emulations:: Writing emulation files 77733965Sjdp@end menu 77833965Sjdp 77933965Sjdp@node CPU backend 78033965Sjdp@subsection Writing a CPU backend 78133965Sjdp@cindex CPU backend 78233965Sjdp@cindex @file{tc-@var{CPU}} 78333965Sjdp 78433965SjdpThe CPU backend files are the heart of the assembler. They are the only parts 78533965Sjdpof the assembler which actually know anything about the instruction set of the 78633965Sjdpprocessor. 78733965Sjdp 78833965SjdpYou must define a reasonably small list of macros and functions in the CPU 78933965Sjdpbackend files. You may define a large number of additional macros in the CPU 79033965Sjdpbackend files, not all of which are documented here. You must, of course, 79133965Sjdpdefine macros in the @file{.h} file, which is included by every assembler 79233965Sjdpsource file. You may define the functions as macros in the @file{.h} file, or 79333965Sjdpas functions in the @file{.c} file. 79433965Sjdp 79533965Sjdp@table @code 79633965Sjdp@item TC_@var{CPU} 79733965Sjdp@cindex TC_@var{CPU} 79833965SjdpBy convention, you should define this macro in the @file{.h} file. For 79933965Sjdpexample, @file{tc-m68k.h} defines @code{TC_M68K}. You might have to use this 80033965Sjdpif it is necessary to add CPU specific code to the object format file. 80133965Sjdp 80233965Sjdp@item TARGET_FORMAT 80333965SjdpThis macro is the BFD target name to use when creating the output file. This 80433965Sjdpwill normally depend upon the @code{OBJ_@var{FMT}} macro. 80533965Sjdp 80633965Sjdp@item TARGET_ARCH 80733965SjdpThis macro is the BFD architecture to pass to @code{bfd_set_arch_mach}. 80833965Sjdp 80933965Sjdp@item TARGET_MACH 81033965SjdpThis macro is the BFD machine number to pass to @code{bfd_set_arch_mach}. If 81133965Sjdpit is not defined, GAS will use 0. 81233965Sjdp 81333965Sjdp@item TARGET_BYTES_BIG_ENDIAN 81433965SjdpYou should define this macro to be non-zero if the target is big endian, and 81533965Sjdpzero if the target is little endian. 81633965Sjdp 81733965Sjdp@item md_shortopts 81833965Sjdp@itemx md_longopts 81933965Sjdp@itemx md_longopts_size 82033965Sjdp@itemx md_parse_option 82133965Sjdp@itemx md_show_usage 82289857Sobrien@itemx md_after_parse_args 82333965Sjdp@cindex md_shortopts 82433965Sjdp@cindex md_longopts 82533965Sjdp@cindex md_longopts_size 82633965Sjdp@cindex md_parse_option 82733965Sjdp@cindex md_show_usage 82889857Sobrien@cindex md_after_parse_args 82933965SjdpGAS uses these variables and functions during option processing. 83033965Sjdp@code{md_shortopts} is a @code{const char *} which GAS adds to the machine 83133965Sjdpindependent string passed to @code{getopt}. @code{md_longopts} is a 83233965Sjdp@code{struct option []} which GAS adds to the machine independent long options 83333965Sjdppassed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in 83433965Sjdp@file{as.h}, as the start of a set of long option indices, if necessary. 83533965Sjdp@code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}. 836218822Sdim 83733965SjdpGAS will call @code{md_parse_option} whenever @code{getopt} returns an 83833965Sjdpunrecognized code, presumably indicating a special code value which appears in 839218822Sdim@code{md_longopts}. This function should return non-zero if it handled the 840218822Sdimoption and zero otherwise. There is no need to print a message about an option 841218822Sdimnot being recognized. This will be handled by the generic code. 84233965Sjdp 843218822SdimGAS will call @code{md_show_usage} when a usage message is printed; it should 844218822Sdimprint a description of the machine specific options. @code{md_after_pase_args}, 845218822Sdimif defined, is called after all options are processed, to let the backend 846218822Sdimoverride settings done by the generic option parsing. 847218822Sdim 84833965Sjdp@item md_begin 84933965Sjdp@cindex md_begin 85033965SjdpGAS will call this function at the start of the assembly, after the command 85133965Sjdpline arguments have been parsed and all the machine independent initializations 85233965Sjdphave been completed. 85333965Sjdp 85433965Sjdp@item md_cleanup 85533965Sjdp@cindex md_cleanup 85633965SjdpIf you define this macro, GAS will call it at the end of each input file. 85733965Sjdp 85833965Sjdp@item md_assemble 85933965Sjdp@cindex md_assemble 86033965SjdpGAS will call this function for each input line which does not contain a 86133965Sjdppseudo-op. The argument is a null terminated string. The function should 86233965Sjdpassemble the string as an instruction with operands. Normally 86333965Sjdp@code{md_assemble} will do this by calling @code{frag_more} and writing out 86433965Sjdpsome bytes (@pxref{Frags}). @code{md_assemble} will call @code{fix_new} to 86533965Sjdpcreate fixups as needed (@pxref{Fixups}). Targets which need to do special 86633965Sjdppurpose relaxation will call @code{frag_var}. 86733965Sjdp 86833965Sjdp@item md_pseudo_table 86933965Sjdp@cindex md_pseudo_table 87033965SjdpThis is a const array of type @code{pseudo_typeS}. It is a mapping from 87133965Sjdppseudo-op names to functions. You should use this table to implement 87233965Sjdppseudo-ops which are specific to the CPU. 87333965Sjdp 87433965Sjdp@item tc_conditional_pseudoop 87533965Sjdp@cindex tc_conditional_pseudoop 87633965SjdpIf this macro is defined, GAS will call it with a @code{pseudo_typeS} argument. 87733965SjdpIt should return non-zero if the pseudo-op is a conditional which controls 87833965Sjdpwhether code is assembled, such as @samp{.if}. GAS knows about the normal 87977298Sobrienconditional pseudo-ops, and you should normally not have to define this macro. 88033965Sjdp 88133965Sjdp@item comment_chars 88233965Sjdp@cindex comment_chars 88333965SjdpThis is a null terminated @code{const char} array of characters which start a 88433965Sjdpcomment. 88533965Sjdp 88633965Sjdp@item tc_comment_chars 88733965Sjdp@cindex tc_comment_chars 88833965SjdpIf this macro is defined, GAS will use it instead of @code{comment_chars}. 88933965Sjdp 89060484Sobrien@item tc_symbol_chars 89160484Sobrien@cindex tc_symbol_chars 89260484SobrienIf this macro is defined, it is a pointer to a null terminated list of 89360484Sobriencharacters which may appear in an operand. GAS already assumes that all 894218822Sdimalphanumeric characters, and @samp{$}, @samp{.}, and @samp{_} may appear in an 89560484Sobrienoperand (see @samp{symbol_chars} in @file{app.c}). This macro may be defined 89660484Sobriento treat additional characters as appearing in an operand. This affects the 89760484Sobrienway in which GAS removes whitespace before passing the string to 89860484Sobrien@samp{md_assemble}. 89960484Sobrien 90033965Sjdp@item line_comment_chars 90133965Sjdp@cindex line_comment_chars 90233965SjdpThis is a null terminated @code{const char} array of characters which start a 90333965Sjdpcomment when they appear at the start of a line. 90433965Sjdp 90533965Sjdp@item line_separator_chars 90633965Sjdp@cindex line_separator_chars 90733965SjdpThis is a null terminated @code{const char} array of characters which separate 90877298Sobrienlines (null and newline are such characters by default, and need not be 90960484Sobrienlisted in this array). Note that line_separator_chars do not separate lines 91060484Sobrienif found in a comment, such as after a character in line_comment_chars or 91160484Sobriencomment_chars. 91233965Sjdp 91333965Sjdp@item EXP_CHARS 91433965Sjdp@cindex EXP_CHARS 91533965SjdpThis is a null terminated @code{const char} array of characters which may be 91633965Sjdpused as the exponent character in a floating point number. This is normally 91733965Sjdp@code{"eE"}. 91833965Sjdp 91933965Sjdp@item FLT_CHARS 92033965Sjdp@cindex FLT_CHARS 92133965SjdpThis is a null terminated @code{const char} array of characters which may be 92233965Sjdpused to indicate a floating point constant. A zero followed by one of these 92333965Sjdpcharacters is assumed to be followed by a floating point number; thus they 92433965Sjdpoperate the way that @code{0x} is used to indicate a hexadecimal constant. 92533965SjdpUsually this includes @samp{r} and @samp{f}. 92633965Sjdp 92733965Sjdp@item LEX_AT 92833965Sjdp@cindex LEX_AT 92960484SobrienYou may define this macro to the lexical type of the @kbd{@@} character. The 93033965Sjdpdefault is zero. 93133965Sjdp 93233965SjdpLexical types are a combination of @code{LEX_NAME} and @code{LEX_BEGIN_NAME}, 93333965Sjdpboth defined in @file{read.h}. @code{LEX_NAME} indicates that the character 93433965Sjdpmay appear in a name. @code{LEX_BEGIN_NAME} indicates that the character may 93560484Sobrienappear at the beginning of a name. 93633965Sjdp 93733965Sjdp@item LEX_BR 93833965Sjdp@cindex LEX_BR 93933965SjdpYou may define this macro to the lexical type of the brace characters @kbd{@{}, 94033965Sjdp@kbd{@}}, @kbd{[}, and @kbd{]}. The default value is zero. 94133965Sjdp 94233965Sjdp@item LEX_PCT 94333965Sjdp@cindex LEX_PCT 94433965SjdpYou may define this macro to the lexical type of the @kbd{%} character. The 94533965Sjdpdefault value is zero. 94633965Sjdp 94733965Sjdp@item LEX_QM 94833965Sjdp@cindex LEX_QM 94933965SjdpYou may define this macro to the lexical type of the @kbd{?} character. The 95033965Sjdpdefault value it zero. 95133965Sjdp 95233965Sjdp@item LEX_DOLLAR 95333965Sjdp@cindex LEX_DOLLAR 95433965SjdpYou may define this macro to the lexical type of the @kbd{$} character. The 95533965Sjdpdefault value is @code{LEX_NAME | LEX_BEGIN_NAME}. 95633965Sjdp 95760484Sobrien@item NUMBERS_WITH_SUFFIX 95860484Sobrien@cindex NUMBERS_WITH_SUFFIX 95960484SobrienWhen this macro is defined to be non-zero, the parser allows the radix of a 96077298Sobrienconstant to be indicated with a suffix. Valid suffixes are binary (B), 96160484Sobrienoctal (Q), and hexadecimal (H). Case is not significant. 96260484Sobrien 96333965Sjdp@item SINGLE_QUOTE_STRINGS 96433965Sjdp@cindex SINGLE_QUOTE_STRINGS 96533965SjdpIf you define this macro, GAS will treat single quotes as string delimiters. 96633965SjdpNormally only double quotes are accepted as string delimiters. 96733965Sjdp 96833965Sjdp@item NO_STRING_ESCAPES 96933965Sjdp@cindex NO_STRING_ESCAPES 97033965SjdpIf you define this macro, GAS will not permit escape sequences in a string. 97133965Sjdp 97233965Sjdp@item ONLY_STANDARD_ESCAPES 97333965Sjdp@cindex ONLY_STANDARD_ESCAPES 97433965SjdpIf you define this macro, GAS will warn about the use of nonstandard escape 97533965Sjdpsequences in a string. 97633965Sjdp 97733965Sjdp@item md_start_line_hook 97833965Sjdp@cindex md_start_line_hook 97933965SjdpIf you define this macro, GAS will call it at the start of each line. 98033965Sjdp 98133965Sjdp@item LABELS_WITHOUT_COLONS 98233965Sjdp@cindex LABELS_WITHOUT_COLONS 98333965SjdpIf you define this macro, GAS will assume that any text at the start of a line 98433965Sjdpis a label, even if it does not have a colon. 98533965Sjdp 98633965Sjdp@item TC_START_LABEL 98777298Sobrien@itemx TC_START_LABEL_WITHOUT_COLON 98833965Sjdp@cindex TC_START_LABEL 98933965SjdpYou may define this macro to control what GAS considers to be a label. The 99033965Sjdpdefault definition is to accept any name followed by a colon character. 99133965Sjdp 99260484Sobrien@item TC_START_LABEL_WITHOUT_COLON 99360484Sobrien@cindex TC_START_LABEL_WITHOUT_COLON 99460484SobrienSame as TC_START_LABEL, but should be used instead of TC_START_LABEL when 99577298SobrienLABELS_WITHOUT_COLONS is defined. 99660484Sobrien 997218822Sdim@item TC_FAKE_LABEL 998218822Sdim@cindex TC_FAKE_LABEL 999218822SdimYou may define this macro to control what GAS considers to be a fake 1000218822Sdimlabel. The default fake label is FAKE_LABEL_NAME. 1001218822Sdim 100233965Sjdp@item NO_PSEUDO_DOT 100333965Sjdp@cindex NO_PSEUDO_DOT 100433965SjdpIf you define this macro, GAS will not require pseudo-ops to start with a 100533965Sjdp@kbd{.} character. 100633965Sjdp 100733965Sjdp@item TC_EQUAL_IN_INSN 100833965Sjdp@cindex TC_EQUAL_IN_INSN 100933965SjdpIf you define this macro, it should return nonzero if the instruction is 101060484Sobrienpermitted to contain an @kbd{=} character. GAS will call it with two 101160484Sobrienarguments, the character before the @kbd{=} character, and the value of 1012218822Sdimthe string preceding the equal sign. GAS uses this macro to decide if a 101333965Sjdp@kbd{=} is an assignment or an instruction. 101433965Sjdp 101533965Sjdp@item TC_EOL_IN_INSN 101633965Sjdp@cindex TC_EOL_IN_INSN 101733965SjdpIf you define this macro, it should return nonzero if the current input line 101833965Sjdppointer should be treated as the end of a line. 101933965Sjdp 1020130561Sobrien@item TC_CASE_SENSITIVE 1021130561Sobrien@cindex TC_CASE_SENSITIVE 1022130561SobrienDefine this macro if instruction mnemonics and pseudos are case sensitive. 1023130561SobrienThe default is to have it undefined giving case insensitive names. 1024130561Sobrien 102533965Sjdp@item md_parse_name 102633965Sjdp@cindex md_parse_name 102733965SjdpIf this macro is defined, GAS will call it for any symbol found in an 102833965Sjdpexpression. You can define this to handle special symbols in a special way. 102933965SjdpIf a symbol always has a certain value, you should normally enter it in the 103033965Sjdpsymbol table, perhaps using @code{reg_section}. 103133965Sjdp 103233965Sjdp@item md_undefined_symbol 103333965Sjdp@cindex md_undefined_symbol 103433965SjdpGAS will call this function when a symbol table lookup fails, before it 103533965Sjdpcreates a new symbol. Typically this would be used to supply symbols whose 103633965Sjdpname or value changes dynamically, possibly in a context sensitive way. 103733965SjdpPredefined symbols with fixed values, such as register names or condition 103833965Sjdpcodes, are typically entered directly into the symbol table when @code{md_begin} 103960484Sobrienis called. One argument is passed, a @code{char *} for the symbol. 104033965Sjdp 104133965Sjdp@item md_operand 104233965Sjdp@cindex md_operand 104360484SobrienGAS will call this function with one argument, an @code{expressionS} 104460484Sobrienpointer, for any expression that can not be recognized. When the function 104560484Sobrienis called, @code{input_line_pointer} will point to the start of the 104660484Sobrienexpression. 104733965Sjdp 104833965Sjdp@item tc_unrecognized_line 104933965Sjdp@cindex tc_unrecognized_line 105033965SjdpIf you define this macro, GAS will call it when it finds a line that it can not 105133965Sjdpparse. 105233965Sjdp 105333965Sjdp@item md_do_align 105433965Sjdp@cindex md_do_align 105533965SjdpYou may define this macro to handle an alignment directive. GAS will call it 105633965Sjdpwhen the directive is seen in the input file. For example, the i386 backend 105733965Sjdpuses this to generate efficient nop instructions of varying lengths, depending 105833965Sjdpupon the number of bytes that the alignment will skip. 105933965Sjdp 106033965Sjdp@item HANDLE_ALIGN 106133965Sjdp@cindex HANDLE_ALIGN 106233965SjdpYou may define this macro to do special handling for an alignment directive. 106333965SjdpGAS will call it at the end of the assembly. 106433965Sjdp 106560484Sobrien@item TC_IMPLICIT_LCOMM_ALIGNMENT (@var{size}, @var{p2var}) 106660484Sobrien@cindex TC_IMPLICIT_LCOMM_ALIGNMENT 106760484SobrienAn @code{.lcomm} directive with no explicit alignment parameter will use this 106860484Sobrienmacro to set @var{p2var} to the alignment that a request for @var{size} bytes 106960484Sobrienwill have. The alignment is expressed as a power of two. If no alignment 107060484Sobrienshould take place, the macro definition should do nothing. Some targets define 107160484Sobriena @code{.bss} directive that is also affected by this macro. The default 107260484Sobriendefinition will set @var{p2var} to the truncated power of two of sizes up to 107360484Sobrieneight bytes. 107460484Sobrien 107533965Sjdp@item md_flush_pending_output 107633965Sjdp@cindex md_flush_pending_output 107733965SjdpIf you define this macro, GAS will call it each time it skips any space because of a 107833965Sjdpspace filling or alignment or data allocation pseudo-op. 107933965Sjdp 108033965Sjdp@item TC_PARSE_CONS_EXPRESSION 108133965Sjdp@cindex TC_PARSE_CONS_EXPRESSION 108233965SjdpYou may define this macro to parse an expression used in a data allocation 108333965Sjdppseudo-op such as @code{.word}. You can use this to recognize relocation 108433965Sjdpdirectives that may appear in such directives. 108533965Sjdp 108633965Sjdp@item BITFIELD_CONS_EXPRESSION 108733965Sjdp@cindex BITFIELD_CONS_EXPRESSION 108833965SjdpIf you define this macro, GAS will recognize bitfield instructions in data 108933965Sjdpallocation pseudo-ops, as used on the i960. 109033965Sjdp 109133965Sjdp@item REPEAT_CONS_EXPRESSION 109233965Sjdp@cindex REPEAT_CONS_EXPRESSION 109333965SjdpIf you define this macro, GAS will recognize repeat counts in data allocation 109433965Sjdppseudo-ops, as used on the MIPS. 109533965Sjdp 109633965Sjdp@item md_cons_align 109733965Sjdp@cindex md_cons_align 109833965SjdpYou may define this macro to do any special alignment before a data allocation 109933965Sjdppseudo-op. 110033965Sjdp 110133965Sjdp@item TC_CONS_FIX_NEW 110233965Sjdp@cindex TC_CONS_FIX_NEW 110333965SjdpYou may define this macro to generate a fixup for a data allocation pseudo-op. 110433965Sjdp 1105218822Sdim@item TC_ADDRESS_BYTES 1106218822Sdim@cindex TC_ADDRESS_BYTES 1107218822SdimDefine this macro to specify the number of bytes used to store an address. 1108218822SdimUsed to implement @code{dc.a}. The target must have a reloc for this size. 1109218822Sdim 111038889Sjdp@item TC_INIT_FIX_DATA (@var{fixp}) 111138889Sjdp@cindex TC_INIT_FIX_DATA 111238889SjdpA C statement to initialize the target specific fields of fixup @var{fixp}. 111338889SjdpThese fields are defined with the @code{TC_FIX_TYPE} macro. 111438889Sjdp 111538889Sjdp@item TC_FIX_DATA_PRINT (@var{stream}, @var{fixp}) 111638889Sjdp@cindex TC_FIX_DATA_PRINT 111738889SjdpA C statement to output target specific debugging information for 111838889Sjdpfixup @var{fixp} to @var{stream}. This macro is called by @code{print_fixup}. 111938889Sjdp 112038889Sjdp@item TC_FRAG_INIT (@var{fragp}) 112138889Sjdp@cindex TC_FRAG_INIT 112238889SjdpA C statement to initialize the target specific fields of frag @var{fragp}. 112338889SjdpThese fields are defined with the @code{TC_FRAG_TYPE} macro. 112438889Sjdp 112533965Sjdp@item md_number_to_chars 112633965Sjdp@cindex md_number_to_chars 112733965SjdpThis should just call either @code{number_to_chars_bigendian} or 112833965Sjdp@code{number_to_chars_littleendian}, whichever is appropriate. On targets like 112933965Sjdpthe MIPS which support options to change the endianness, which function to call 113033965Sjdpis a runtime decision. On other targets, @code{md_number_to_chars} can be a 113133965Sjdpsimple macro. 113233965Sjdp 113389857Sobrien@item md_atof (@var{type},@var{litP},@var{sizeP}) 113489857Sobrien@cindex md_atof 113589857SobrienThis function is called to convert an ASCII string into a floating point value 113689857Sobrienin format used by the CPU. It takes three arguments. The first is @var{type} 113789857Sobrienwhich is a byte describing the type of floating point number to be created. 113889857SobrienPossible values are @var{'f'} or @var{'s'} for single precision, @var{'d'} or 113989857Sobrien@var{'r'} for double precision and @var{'x'} or @var{'p'} for extended 114089857Sobrienprecision. Either lower or upper case versions of these letters can be used. 114189857Sobrien 114289857SobrienThe second parameter is @var{litP} which is a pointer to a byte array where the 114389857Sobrienconverted value should be stored. The third argument is @var{sizeP}, which is 114489857Sobriena pointer to a integer that should be filled in with the number of 114589857Sobrien@var{LITTLENUM}s emitted into the byte array. (@var{LITTLENUM} is defined in 114689857Sobriengas/bignum.h). The function should return NULL upon success or an error string 114789857Sobrienupon failure. 114889857Sobrien 1149104834Sobrien@item TC_LARGEST_EXPONENT_IS_NORMAL 1150104834Sobrien@cindex TC_LARGEST_EXPONENT_IS_NORMAL (@var{precision}) 1151104834SobrienThis macro is used only by @file{atof-ieee.c}. It should evaluate to true 1152104834Sobrienif floats of the given precision use the largest exponent for normal numbers 1153104834Sobrieninstead of NaNs and infinities. @var{precision} is @samp{F_PRECISION} for 1154104834Sobriensingle precision, @samp{D_PRECISION} for double precision, or 1155104834Sobrien@samp{X_PRECISION} for extended double precision. 1156104834Sobrien 1157104834SobrienThe macro has a default definition which returns 0 for all cases. 1158104834Sobrien 115933965Sjdp@item WORKING_DOT_WORD 116033965Sjdp@itemx md_short_jump_size 116133965Sjdp@itemx md_long_jump_size 116233965Sjdp@itemx md_create_short_jump 116333965Sjdp@itemx md_create_long_jump 116477298Sobrien@itemx TC_CHECK_ADJUSTED_BROKEN_DOT_WORD 116533965Sjdp@cindex WORKING_DOT_WORD 116633965Sjdp@cindex md_short_jump_size 116733965Sjdp@cindex md_long_jump_size 116833965Sjdp@cindex md_create_short_jump 116933965Sjdp@cindex md_create_long_jump 117077298Sobrien@cindex TC_CHECK_ADJUSTED_BROKEN_DOT_WORD 117133965SjdpIf @code{WORKING_DOT_WORD} is defined, GAS will not do broken word processing 117233965Sjdp(@pxref{Broken words}). Otherwise, you should set @code{md_short_jump_size} to 117360484Sobrienthe size of a short jump (a jump that is just long enough to jump around a 117460484Sobriennumber of long jumps) and @code{md_long_jump_size} to the size of a long jump 117560484Sobrien(a jump that can go anywhere in the function). You should define 117660484Sobrien@code{md_create_short_jump} to create a short jump around a number of long 117760484Sobrienjumps, and define @code{md_create_long_jump} to create a long jump. 117877298SobrienIf defined, the macro TC_CHECK_ADJUSTED_BROKEN_DOT_WORD will be called for each 117977298Sobrienadjusted word just before the word is output. The macro takes two arguments, 118077298Sobrienan @code{addressT} with the adjusted word and a pointer to the current 118177298Sobrien@code{struct broken_word}. 118233965Sjdp 118333965Sjdp@item md_estimate_size_before_relax 118433965Sjdp@cindex md_estimate_size_before_relax 118533965SjdpThis function returns an estimate of the size of a @code{rs_machine_dependent} 118633965Sjdpfrag before any relaxing is done. It may also create any necessary 118733965Sjdprelocations. 118833965Sjdp 118933965Sjdp@item md_relax_frag 119033965Sjdp@cindex md_relax_frag 119178828SobrienThis macro may be defined to relax a frag. GAS will call this with the 119278828Sobriensegment, the frag, and the change in size of all previous frags; 119378828Sobrien@code{md_relax_frag} should return the change in size of the frag. 119478828Sobrien@xref{Relaxation}. 119533965Sjdp 119633965Sjdp@item TC_GENERIC_RELAX_TABLE 119733965Sjdp@cindex TC_GENERIC_RELAX_TABLE 119833965SjdpIf you do not define @code{md_relax_frag}, you may define 119933965Sjdp@code{TC_GENERIC_RELAX_TABLE} as a table of @code{relax_typeS} structures. The 120033965Sjdpmachine independent code knows how to use such a table to relax PC relative 120133965Sjdpreferences. See @file{tc-m68k.c} for an example. @xref{Relaxation}. 120233965Sjdp 120333965Sjdp@item md_prepare_relax_scan 120433965Sjdp@cindex md_prepare_relax_scan 120533965SjdpIf defined, it is a C statement that is invoked prior to scanning 120633965Sjdpthe relax table. 120733965Sjdp 120833965Sjdp@item LINKER_RELAXING_SHRINKS_ONLY 120933965Sjdp@cindex LINKER_RELAXING_SHRINKS_ONLY 121033965SjdpIf you define this macro, and the global variable @samp{linkrelax} is set 121133965Sjdp(because of a command line option, or unconditionally in @code{md_begin}), a 121233965Sjdp@samp{.align} directive will cause extra space to be allocated. The linker can 121333965Sjdpthen discard this space when relaxing the section. 121433965Sjdp 121577298Sobrien@item TC_LINKRELAX_FIXUP (@var{segT}) 121677298Sobrien@cindex TC_LINKRELAX_FIXUP 121777298SobrienIf defined, this macro allows control over whether fixups for a 121877298Sobriengiven section will be processed when the @var{linkrelax} variable is 121977298Sobrienset. The macro is given the N_TYPE bits for the section in its 122077298Sobrien@var{segT} argument. If the macro evaluates to a non-zero value 122177298Sobrienthen the fixups will be converted into relocs, otherwise they will 1222218822Sdimbe passed to @var{md_apply_fix} as normal. 122377298Sobrien 122433965Sjdp@item md_convert_frag 122533965Sjdp@cindex md_convert_frag 122633965SjdpGAS will call this for each rs_machine_dependent fragment. 122733965SjdpThe instruction is completed using the data from the relaxation pass. 122833965SjdpIt may also create any necessary relocations. 122933965Sjdp@xref{Relaxation}. 123033965Sjdp 123189857Sobrien@item TC_FINALIZE_SYMS_BEFORE_SIZE_SEG 123289857Sobrien@cindex TC_FINALIZE_SYMS_BEFORE_SIZE_SEG 123389857SobrienSpecifies the value to be assigned to @code{finalize_syms} before the function 123489857Sobrien@code{size_segs} is called. Since @code{size_segs} calls @code{cvt_frag_to_fill} 123589857Sobrienwhich can call @code{md_convert_frag}, this constant governs whether the symbols 123689857Sobrienaccessed in @code{md_convert_frag} will be fully resolved. In particular it 123789857Sobriengoverns whether local symbols will have been resolved, and had their frag 123889857Sobrieninformation removed. Depending upon the processing performed by 123989857Sobrien@code{md_convert_frag} the frag information may or may not be necessary, as may 124089857Sobrienthe resolved values of the symbols. The default value is 1. 124189857Sobrien 1242130561Sobrien@item TC_VALIDATE_FIX (@var{fixP}, @var{seg}, @var{skip}) 1243130561Sobrien@cindex TC_VALIDATE_FIX 1244130561SobrienThis macro is evaluated for each fixup (when @var{linkrelax} is not set). 1245130561SobrienIt may be used to change the fixup in @code{struct fix *@var{fixP}} before 1246130561Sobrienthe generic code sees it, or to fully process the fixup. In the latter case, 1247130561Sobriena @code{goto @var{skip}} will bypass the generic code. 1248130561Sobrien 1249218822Sdim@item md_apply_fix (@var{fixP}, @var{valP}, @var{seg}) 1250218822Sdim@cindex md_apply_fix 1251130561SobrienGAS will call this for each fixup that passes the @code{TC_VALIDATE_FIX} test 1252130561Sobrienwhen @var{linkrelax} is not set. It should store the correct value in the 1253218822Sdimobject file. @code{struct fix *@var{fixP}} is the fixup @code{md_apply_fix} 1254130561Sobrienis operating on. @code{valueT *@var{valP}} is the value to store into the 1255130561Sobrienobject files, or at least is the generic code's best guess. Specifically, 1256130561Sobrien*@var{valP} is the value of the fixup symbol, perhaps modified by 1257130561Sobrien@code{MD_APPLY_SYM_VALUE}, plus @code{@var{fixP}->fx_offset} (symbol addend), 1258130561Sobrienless @code{MD_PCREL_FROM_SECTION} for pc-relative fixups. 1259130561Sobrien@code{segT @var{seg}} is the section the fix is in. 1260130561Sobrien@code{fixup_segment} performs a generic overflow check on *@var{valP} after 1261218822Sdim@code{md_apply_fix} returns. If the overflow check is relevant for the target 1262218822Sdimmachine, then @code{md_apply_fix} should modify *@var{valP}, typically to the 1263130561Sobrienvalue stored in the object file. 126433965Sjdp 1265130561Sobrien@item TC_FORCE_RELOCATION (@var{fix}) 1266130561Sobrien@cindex TC_FORCE_RELOCATION 1267130561SobrienIf this macro returns non-zero, it guarantees that a relocation will be emitted 1268130561Sobrieneven when the value can be resolved locally, as @code{fixup_segment} tries to 1269130561Sobrienreduce the number of relocations emitted. For example, a fixup expression 1270130561Sobrienagainst an absolute symbol will normally not require a reloc. If undefined, 1271130561Sobriena default of @w{@code{(S_FORCE_RELOC ((@var{fix})->fx_addsy))}} is used. 127233965Sjdp 1273130561Sobrien@item TC_FORCE_RELOCATION_ABS (@var{fix}) 1274130561Sobrien@cindex TC_FORCE_RELOCATION_ABS 1275130561SobrienLike @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against an 1276130561Sobrienabsolute symbol. If undefined, @code{TC_FORCE_RELOCATION} will be used. 1277130561Sobrien 1278130561Sobrien@item TC_FORCE_RELOCATION_LOCAL (@var{fix}) 1279130561Sobrien@cindex TC_FORCE_RELOCATION_LOCAL 1280130561SobrienLike @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against a 1281130561Sobriensymbol in the current section. If undefined, fixups that are not 1282218822Sdim@code{fx_pcrel} or for which @code{TC_FORCE_RELOCATION} 1283130561Sobrienreturns non-zero, will emit relocs. 1284130561Sobrien 1285130561Sobrien@item TC_FORCE_RELOCATION_SUB_SAME (@var{fix}, @var{seg}) 1286130561Sobrien@cindex TC_FORCE_RELOCATION_SUB_SAME 1287130561SobrienThis macro controls resolution of fixup expressions involving the 1288130561Sobriendifference of two symbols in the same section. If this macro returns zero, 1289130561Sobrienthe subtrahend will be resolved and @code{fx_subsy} set to @code{NULL} for 1290218822Sdim@code{md_apply_fix}. If undefined, the default of 1291130561Sobrien@w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will 1292130561Sobrienbe used. 1293130561Sobrien 1294130561Sobrien@item TC_FORCE_RELOCATION_SUB_ABS (@var{fix}) 1295130561Sobrien@cindex TC_FORCE_RELOCATION_SUB_ABS 1296130561SobrienLike @code{TC_FORCE_RELOCATION_SUB_SAME}, but used when the subtrahend is an 1297130561Sobrienabsolute symbol. If the macro is undefined a default of @code{0} is used. 1298130561Sobrien 1299130561Sobrien@item TC_FORCE_RELOCATION_SUB_LOCAL (@var{fix}) 1300130561Sobrien@cindex TC_FORCE_RELOCATION_SUB_LOCAL 1301130561SobrienLike @code{TC_FORCE_RELOCATION_SUB_ABS}, but the subtrahend is a symbol in the 1302130561Sobriensame section as the fixup. 1303130561Sobrien 1304130561Sobrien@item TC_VALIDATE_FIX_SUB (@var{fix}) 1305130561Sobrien@cindex TC_VALIDATE_FIX_SUB 1306130561SobrienThis macro is evaluated for any fixup with a @code{fx_subsy} that 1307130561Sobrien@code{fixup_segment} cannot reduce to a number. If the macro returns 1308130561Sobrien@code{false} an error will be reported. 1309130561Sobrien 1310130561Sobrien@item MD_APPLY_SYM_VALUE (@var{fix}) 1311130561Sobrien@cindex MD_APPLY_SYM_VALUE 1312130561SobrienThis macro controls whether the symbol value becomes part of the value passed 1313218822Sdimto @code{md_apply_fix}. If the macro is undefined, or returns non-zero, the 1314130561Sobriensymbol value will be included. For ELF, a suitable definition might simply be 1315130561Sobrien@code{0}, because ELF relocations don't include the symbol value in the addend. 1316130561Sobrien 1317130561Sobrien@item S_FORCE_RELOC (@var{sym}, @var{strict}) 1318130561Sobrien@cindex S_FORCE_RELOC 1319218822SdimThis function returns true for symbols 1320130561Sobrienthat should not be reduced to section symbols or eliminated from expressions, 1321130561Sobrienbecause they may be overridden by the linker. ie. for symbols that are 1322130561Sobrienundefined or common, and when @var{strict} is set, weak, or global (for ELF 1323130561Sobrienassemblers that support ELF shared library linking semantics). 1324130561Sobrien 1325130561Sobrien@item EXTERN_FORCE_RELOC 1326130561Sobrien@cindex EXTERN_FORCE_RELOC 1327130561SobrienThis macro controls whether @code{S_FORCE_RELOC} returns true for global 1328130561Sobriensymbols. If undefined, the default is @code{true} for ELF assemblers, and 1329130561Sobrien@code{false} for non-ELF. 1330130561Sobrien 133133965Sjdp@item tc_gen_reloc 133233965Sjdp@cindex tc_gen_reloc 1333218822SdimGAS will call this to generate a reloc. GAS will pass 133433965Sjdpthe resulting reloc to @code{bfd_install_relocation}. This currently works 133533965Sjdppoorly, as @code{bfd_install_relocation} often does the wrong thing, and 133633965Sjdpinstances of @code{tc_gen_reloc} have been written to work around the problems, 133733965Sjdpwhich in turns makes it difficult to fix @code{bfd_install_relocation}. 133833965Sjdp 133933965Sjdp@item RELOC_EXPANSION_POSSIBLE 134033965Sjdp@cindex RELOC_EXPANSION_POSSIBLE 134133965SjdpIf you define this macro, it means that @code{tc_gen_reloc} may return multiple 134233965Sjdprelocation entries for a single fixup. In this case, the return value of 134333965Sjdp@code{tc_gen_reloc} is a pointer to a null terminated array. 134433965Sjdp 134533965Sjdp@item MAX_RELOC_EXPANSION 134633965Sjdp@cindex MAX_RELOC_EXPANSION 134733965SjdpYou must define this if @code{RELOC_EXPANSION_POSSIBLE} is defined; it 134833965Sjdpindicates the largest number of relocs which @code{tc_gen_reloc} may return for 134933965Sjdpa single fixup. 135033965Sjdp 135133965Sjdp@item tc_fix_adjustable 135233965Sjdp@cindex tc_fix_adjustable 135333965SjdpYou may define this macro to indicate whether a fixup against a locally defined 135433965Sjdpsymbol should be adjusted to be against the section symbol. It should return a 135533965Sjdpnon-zero value if the adjustment is acceptable. 135633965Sjdp 135789857Sobrien@item MD_PCREL_FROM_SECTION (@var{fixp}, @var{section}) 135833965Sjdp@cindex MD_PCREL_FROM_SECTION 135989857SobrienIf you define this macro, it should return the position from which the PC 136089857Sobrienrelative adjustment for a PC relative fixup should be made. On many 136189857Sobrienprocessors, the base of a PC relative instruction is the next instruction, 136289857Sobrienso this macro would return the length of an instruction, plus the address of 136389857Sobrienthe PC relative fixup. The latter can be calculated as 136489857Sobrien@var{fixp}->fx_where + @var{fixp}->fx_frag->fr_address . 136533965Sjdp 136633965Sjdp@item md_pcrel_from 136733965Sjdp@cindex md_pcrel_from 136833965SjdpThis is the default value of @code{MD_PCREL_FROM_SECTION}. The difference is 136933965Sjdpthat @code{md_pcrel_from} does not take a section argument. 137033965Sjdp 137133965Sjdp@item tc_frob_label 137233965Sjdp@cindex tc_frob_label 137333965SjdpIf you define this macro, GAS will call it each time a label is defined. 137433965Sjdp 137533965Sjdp@item md_section_align 137633965Sjdp@cindex md_section_align 137733965SjdpGAS will call this function for each section at the end of the assembly, to 137860484Sobrienpermit the CPU backend to adjust the alignment of a section. The function 137960484Sobrienmust take two arguments, a @code{segT} for the section and a @code{valueT} 138060484Sobrienfor the size of the section, and return a @code{valueT} for the rounded 138160484Sobriensize. 138233965Sjdp 138360484Sobrien@item md_macro_start 138460484Sobrien@cindex md_macro_start 138560484SobrienIf defined, GAS will call this macro when it starts to include a macro 138660484Sobrienexpansion. @code{macro_nest} indicates the current macro nesting level, which 138777298Sobrienincludes the one being expanded. 138860484Sobrien 138960484Sobrien@item md_macro_info 139060484Sobrien@cindex md_macro_info 139160484SobrienIf defined, GAS will call this macro after the macro expansion has been 139260484Sobrienincluded in the input and after parsing the macro arguments. The single 139360484Sobrienargument is a pointer to the macro processing's internal representation of the 139460484Sobrienmacro (macro_entry *), which includes expansion of the formal arguments. 139560484Sobrien 139660484Sobrien@item md_macro_end 139760484Sobrien@cindex md_macro_end 139860484SobrienComplement to md_macro_start. If defined, it is called when finished 139977298Sobrienprocessing an inserted macro expansion, just before decrementing macro_nest. 140060484Sobrien 140160484Sobrien@item DOUBLEBAR_PARALLEL 140260484Sobrien@cindex DOUBLEBAR_PARALLEL 140360484SobrienAffects the preprocessor so that lines containing '||' don't have their 140460484Sobrienwhitespace stripped following the double bar. This is useful for targets that 140560484Sobrienimplement parallel instructions. 140660484Sobrien 140760484Sobrien@item KEEP_WHITE_AROUND_COLON 140860484Sobrien@cindex KEEP_WHITE_AROUND_COLON 140960484SobrienNormally, whitespace is compressed and removed when, in the presence of the 141060484Sobriencolon, the adjoining tokens can be distinguished. This option affects the 141160484Sobrienpreprocessor so that whitespace around colons is preserved. This is useful 141260484Sobrienwhen colons might be removed from the input after preprocessing but before 141360484Sobrienassembling, so that adjoining tokens can still be distinguished if there is 1414130561Sobrienwhitespace, or concatenated if there is not. 141560484Sobrien 141633965Sjdp@item tc_frob_section 141733965Sjdp@cindex tc_frob_section 1418218822SdimIf you define this macro, GAS will call it for each 141933965Sjdpsection at the end of the assembly. 142033965Sjdp 142133965Sjdp@item tc_frob_file_before_adjust 142233965Sjdp@cindex tc_frob_file_before_adjust 142333965SjdpIf you define this macro, GAS will call it after the symbol values are 142433965Sjdpresolved, but before the fixups have been changed from local symbols to section 142533965Sjdpsymbols. 142633965Sjdp 142733965Sjdp@item tc_frob_symbol 142833965Sjdp@cindex tc_frob_symbol 142933965SjdpIf you define this macro, GAS will call it for each symbol. You can indicate 1430130561Sobrienthat the symbol should not be included in the object file by defining this 143133965Sjdpmacro to set its second argument to a non-zero value. 143233965Sjdp 143333965Sjdp@item tc_frob_file 143433965Sjdp@cindex tc_frob_file 143533965SjdpIf you define this macro, GAS will call it after the symbol table has been 143633965Sjdpcompleted, but before the relocations have been generated. 143733965Sjdp 143833965Sjdp@item tc_frob_file_after_relocs 143933965SjdpIf you define this macro, GAS will call it after the relocs have been 144033965Sjdpgenerated. 144133965Sjdp 1442130561Sobrien@item md_post_relax_hook 1443130561SobrienIf you define this macro, GAS will call it after relaxing and sizing the 1444130561Sobriensegments. 1445130561Sobrien 144633965Sjdp@item LISTING_HEADER 144733965SjdpA string to use on the header line of a listing. The default value is simply 144833965Sjdp@code{"GAS LISTING"}. 144933965Sjdp 145033965Sjdp@item LISTING_WORD_SIZE 145133965SjdpThe number of bytes to put into a word in a listing. This affects the way the 145233965Sjdpbytes are clumped together in the listing. For example, a value of 2 might 145333965Sjdpprint @samp{1234 5678} where a value of 1 would print @samp{12 34 56 78}. The 145433965Sjdpdefault value is 4. 145533965Sjdp 145633965Sjdp@item LISTING_LHS_WIDTH 145733965SjdpThe number of words of data to print on the first line of a listing for a 145833965Sjdpparticular source line, where each word is @code{LISTING_WORD_SIZE} bytes. The 145933965Sjdpdefault value is 1. 146033965Sjdp 146133965Sjdp@item LISTING_LHS_WIDTH_SECOND 146233965SjdpLike @code{LISTING_LHS_WIDTH}, but applying to the second and subsequent line 146333965Sjdpof the data printed for a particular source line. The default value is 1. 146433965Sjdp 146533965Sjdp@item LISTING_LHS_CONT_LINES 146633965SjdpThe maximum number of continuation lines to print in a listing for a particular 146733965Sjdpsource line. The default value is 4. 146833965Sjdp 146933965Sjdp@item LISTING_RHS_WIDTH 147033965SjdpThe maximum number of characters to print from one line of the input file. The 147133965Sjdpdefault value is 100. 147277298Sobrien 147377298Sobrien@item TC_COFF_SECTION_DEFAULT_ATTRIBUTES 147477298Sobrien@cindex TC_COFF_SECTION_DEFAULT_ATTRIBUTES 147577298SobrienThe COFF @code{.section} directive will use the value of this macro to set 147677298Sobriena new section's attributes when a directive has no valid flags or when the 147777298Sobrienflag is @code{w}. The default value of the macro is @code{SEC_LOAD | SEC_DATA}. 147877298Sobrien 1479130561Sobrien@item DWARF2_FORMAT () 1480130561Sobrien@cindex DWARF2_FORMAT 1481130561SobrienIf you define this, it should return one of @code{dwarf2_format_32bit}, 1482130561Sobrien@code{dwarf2_format_64bit}, or @code{dwarf2_format_64bit_irix} to indicate 1483130561Sobrienthe size of internal DWARF section offsets and the format of the DWARF initial 1484130561Sobrienlength fields. When @code{dwarf2_format_32bit} is returned, the initial 1485130561Sobrienlength field will be 4 bytes long and section offsets are 32 bits in size. 1486130561SobrienFor @code{dwarf2_format_64bit} and @code{dwarf2_format_64bit_irix}, section 1487130561Sobrienoffsets are 64 bits in size, but the initial length field differs. An 8 byte 1488130561Sobrieninitial length is indicated by @code{dwarf2_format_64bit_irix} and 1489130561Sobrien@code{dwarf2_format_64bit} indicates a 12 byte initial length field in 1490130561Sobrienwhich the first four bytes are 0xffffffff and the next 8 bytes are 1491130561Sobrienthe section's length. 1492130561Sobrien 1493130561SobrienIf you don't define this, @code{dwarf2_format_32bit} will be used as 1494130561Sobrienthe default. 1495130561Sobrien 1496130561SobrienThis define only affects @code{.debug_info} and @code{.debug_line} 1497130561Sobriensections generated by the assembler. DWARF 2 sections generated by 1498130561Sobrienother tools will be unaffected by this setting. 1499130561Sobrien 1500130561Sobrien@item DWARF2_ADDR_SIZE (@var{bfd}) 1501130561Sobrien@cindex DWARF2_ADDR_SIZE 1502130561SobrienIt should return the size of an address, as it should be represented in 1503130561Sobriendebugging info. If you don't define this macro, the default definition uses 1504130561Sobrienthe number of bits per address, as defined in @var{bfd}, divided by 8. 1505130561Sobrien 1506218822Sdim@item MD_DEBUG_FORMAT_SELECTOR 1507218822Sdim@cindex MD_DEBUG_FORMAT_SELECTOR 1508218822SdimIf defined this macro is the name of a function to be called when the 1509218822Sdim@samp{--gen-debug} switch is detected on the assembler's command line. The 1510218822Sdimprototype for the function looks like this: 1511218822Sdim 1512218822Sdim@smallexample 1513218822Sdim enum debug_info_type MD_DEBUG_FORMAT_SELECTOR (int * use_gnu_extensions) 1514218822Sdim@end smallexample 1515218822Sdim 1516218822SdimThe function should return the debug format that is preferred by the CPU 1517218822Sdimbackend. This format will be used when generating assembler specific debug 1518218822Sdiminformation. 1519218822Sdim 152033965Sjdp@end table 152133965Sjdp 152233965Sjdp@node Object format backend 152333965Sjdp@subsection Writing an object format backend 152433965Sjdp@cindex object format backend 152533965Sjdp@cindex @file{obj-@var{fmt}} 152633965Sjdp 152733965SjdpAs with the CPU backend, the object format backend must define a few things, 152833965Sjdpand may define some other things. The interface to the object format backend 152933965Sjdpis generally simpler; most of the support for an object file format consists of 153033965Sjdpdefining a number of pseudo-ops. 153133965Sjdp 153233965SjdpThe object format @file{.h} file must include @file{targ-cpu.h}. 153333965Sjdp 153433965Sjdp@table @code 153533965Sjdp@item OBJ_@var{format} 153633965Sjdp@cindex OBJ_@var{format} 153733965SjdpBy convention, you should define this macro in the @file{.h} file. For 153833965Sjdpexample, @file{obj-elf.h} defines @code{OBJ_ELF}. You might have to use this 153933965Sjdpif it is necessary to add object file format specific code to the CPU file. 154033965Sjdp 154133965Sjdp@item obj_begin 154233965SjdpIf you define this macro, GAS will call it at the start of the assembly, after 154333965Sjdpthe command line arguments have been parsed and all the machine independent 154433965Sjdpinitializations have been completed. 154533965Sjdp 154633965Sjdp@item obj_app_file 154733965Sjdp@cindex obj_app_file 154833965SjdpIf you define this macro, GAS will invoke it when it sees a @code{.file} 154933965Sjdppseudo-op or a @samp{#} line as used by the C preprocessor. 155033965Sjdp 155133965Sjdp@item OBJ_COPY_SYMBOL_ATTRIBUTES 155233965Sjdp@cindex OBJ_COPY_SYMBOL_ATTRIBUTES 155333965SjdpYou should define this macro to copy object format specific information from 155433965Sjdpone symbol to another. GAS will call it when one symbol is equated to 155533965Sjdpanother. 155633965Sjdp 155733965Sjdp@item obj_sec_sym_ok_for_reloc 155833965Sjdp@cindex obj_sec_sym_ok_for_reloc 155933965SjdpYou may define this macro to indicate that it is OK to use a section symbol in 1560130561Sobriena relocation entry. If it is not, GAS will define a new symbol at the start 156133965Sjdpof a section. 156233965Sjdp 156333965Sjdp@item EMIT_SECTION_SYMBOLS 156433965Sjdp@cindex EMIT_SECTION_SYMBOLS 156533965SjdpYou should define this macro with a zero value if you do not want to include 156633965Sjdpsection symbols in the output symbol table. The default value for this macro 156733965Sjdpis one. 156833965Sjdp 156933965Sjdp@item obj_adjust_symtab 157033965Sjdp@cindex obj_adjust_symtab 157133965SjdpIf you define this macro, GAS will invoke it just before setting the symbol 157233965Sjdptable of the output BFD. For example, the COFF support uses this macro to 157333965Sjdpgenerate a @code{.file} symbol if none was generated previously. 157433965Sjdp 157533965Sjdp@item SEPARATE_STAB_SECTIONS 157633965Sjdp@cindex SEPARATE_STAB_SECTIONS 157777298SobrienYou may define this macro to a nonzero value to indicate that stabs should be 157877298Sobrienplaced in separate sections, as in ELF. 157933965Sjdp 158033965Sjdp@item INIT_STAB_SECTION 158133965Sjdp@cindex INIT_STAB_SECTION 158233965SjdpYou may define this macro to initialize the stabs section in the output file. 158333965Sjdp 158433965Sjdp@item OBJ_PROCESS_STAB 158533965Sjdp@cindex OBJ_PROCESS_STAB 158633965SjdpYou may define this macro to do specific processing on a stabs entry. 158733965Sjdp 158833965Sjdp@item obj_frob_section 158933965Sjdp@cindex obj_frob_section 159033965SjdpIf you define this macro, GAS will call it for each section at the end of the 159133965Sjdpassembly. 159233965Sjdp 159333965Sjdp@item obj_frob_file_before_adjust 159433965Sjdp@cindex obj_frob_file_before_adjust 159533965SjdpIf you define this macro, GAS will call it after the symbol values are 159633965Sjdpresolved, but before the fixups have been changed from local symbols to section 159733965Sjdpsymbols. 159833965Sjdp 159933965Sjdp@item obj_frob_symbol 160033965Sjdp@cindex obj_frob_symbol 160133965SjdpIf you define this macro, GAS will call it for each symbol. You can indicate 1602130561Sobrienthat the symbol should not be included in the object file by defining this 160333965Sjdpmacro to set its second argument to a non-zero value. 160433965Sjdp 1605218822Sdim@item obj_set_weak_hook 1606218822Sdim@cindex obj_set_weak_hook 1607218822SdimIf you define this macro, @code{S_SET_WEAK} will call it before modifying the 1608218822Sdimsymbol's flags. 1609218822Sdim 1610218822Sdim@item obj_clear_weak_hook 1611218822Sdim@cindex obj_clear_weak_hook 1612218822SdimIf you define this macro, @code{S_CLEAR_WEAKREFD} will call it after cleaning 1613218822Sdimthe @code{weakrefd} flag, but before modifying any other flags. 1614218822Sdim 161533965Sjdp@item obj_frob_file 161633965Sjdp@cindex obj_frob_file 161733965SjdpIf you define this macro, GAS will call it after the symbol table has been 161833965Sjdpcompleted, but before the relocations have been generated. 161933965Sjdp 162033965Sjdp@item obj_frob_file_after_relocs 162133965SjdpIf you define this macro, GAS will call it after the relocs have been 162233965Sjdpgenerated. 162360484Sobrien 162460484Sobrien@item SET_SECTION_RELOCS (@var{sec}, @var{relocs}, @var{n}) 162560484Sobrien@cindex SET_SECTION_RELOCS 162660484SobrienIf you define this, it will be called after the relocations have been set for 162760484Sobrienthe section @var{sec}. The list of relocations is in @var{relocs}, and the 1628218822Sdimnumber of relocations is in @var{n}. 162933965Sjdp@end table 163033965Sjdp 163133965Sjdp@node Emulations 163233965Sjdp@subsection Writing emulation files 163333965Sjdp 163433965SjdpNormally you do not have to write an emulation file. You can just use 163533965Sjdp@file{te-generic.h}. 163633965Sjdp 163733965SjdpIf you do write your own emulation file, it must include @file{obj-format.h}. 163833965Sjdp 163933965SjdpAn emulation file will often define @code{TE_@var{EM}}; this may then be used 164033965Sjdpin other files to change the output. 164133965Sjdp 164233965Sjdp@node Relaxation 164333965Sjdp@section Relaxation 164433965Sjdp@cindex relaxation 164533965Sjdp 164633965Sjdp@dfn{Relaxation} is a generic term used when the size of some instruction or 164733965Sjdpdata depends upon the value of some symbol or other data. 164833965Sjdp 164933965SjdpGAS knows to relax a particular type of PC relative relocation using a table. 165033965SjdpYou can also define arbitrarily complex forms of relaxation yourself. 165133965Sjdp 165233965Sjdp@menu 165333965Sjdp* Relaxing with a table:: Relaxing with a table 165433965Sjdp* General relaxing:: General relaxing 165533965Sjdp@end menu 165633965Sjdp 165733965Sjdp@node Relaxing with a table 165833965Sjdp@subsection Relaxing with a table 165933965Sjdp 166033965SjdpIf you do not define @code{md_relax_frag}, and you do define 166133965Sjdp@code{TC_GENERIC_RELAX_TABLE}, GAS will relax @code{rs_machine_dependent} frags 166233965Sjdpbased on the frag subtype and the displacement to some specified target 166333965Sjdpaddress. The basic idea is that several machines have different addressing 166433965Sjdpmodes for instructions that can specify different ranges of values, with 166533965Sjdpsuccessive modes able to access wider ranges, including the entirety of the 166633965Sjdpprevious range. Smaller ranges are assumed to be more desirable (perhaps the 166733965Sjdpinstruction requires one word instead of two or three); if this is not the 166833965Sjdpcase, don't describe the smaller-range, inferior mode. 166933965Sjdp 167033965SjdpThe @code{fr_subtype} field of a frag is an index into a CPU-specific 167133965Sjdprelaxation table. That table entry indicates the range of values that can be 167233965Sjdpstored, the number of bytes that will have to be added to the frag to 1673130561Sobrienaccommodate the addressing mode, and the index of the next entry to examine if 167433965Sjdpthe value to be stored is outside the range accessible by the current 167533965Sjdpaddressing mode. The @code{fr_symbol} field of the frag indicates what symbol 167633965Sjdpis to be accessed; the @code{fr_offset} field is added in. 167733965Sjdp 167838889SjdpIf the @code{TC_PCREL_ADJUST} macro is defined, which currently should only happen 167933965Sjdpfor the NS32k family, the @code{TC_PCREL_ADJUST} macro is called on the frag to 168033965Sjdpcompute an adjustment to be made to the displacement. 168133965Sjdp 168233965SjdpThe value fitted by the relaxation code is always assumed to be a displacement 168333965Sjdpfrom the current frag. (More specifically, from @code{fr_fix} bytes into the 168433965Sjdpfrag.) 168533965Sjdp@ignore 168633965SjdpThis seems kinda silly. What about fitting small absolute values? I suppose 168733965Sjdp@code{md_assemble} is supposed to take care of that, but if the operand is a 168833965Sjdpdifference between symbols, it might not be able to, if the difference was not 168933965Sjdpcomputable yet. 169033965Sjdp@end ignore 169133965Sjdp 169233965SjdpThe end of the relaxation sequence is indicated by a ``next'' value of 0. This 169333965Sjdpmeans that the first entry in the table can't be used. 169433965Sjdp 169533965SjdpFor some configurations, the linker can do relaxing within a section of an 169633965Sjdpobject file. If call instructions of various sizes exist, the linker can 169733965Sjdpdetermine which should be used in each instance, when a symbol's value is 169833965Sjdpresolved. In order for the linker to avoid wasting space and having to insert 169933965Sjdpno-op instructions, it must be able to expand or shrink the section contents 170033965Sjdpwhile still preserving intra-section references and meeting alignment 170133965Sjdprequirements. 170233965Sjdp 170333965SjdpFor the i960 using b.out format, no expansion is done; instead, each 170433965Sjdp@samp{.align} directive causes extra space to be allocated, enough that when 170533965Sjdpthe linker is relaxing a section and removing unneeded space, it can discard 170633965Sjdpsome or all of this extra padding and cause the following data to be correctly 170733965Sjdpaligned. 170833965Sjdp 170933965SjdpFor the H8/300, I think the linker expands calls that can't reach, and doesn't 171033965Sjdpworry about alignment issues; the cpu probably never needs any significant 171133965Sjdpalignment beyond the instruction size. 171233965Sjdp 171333965SjdpThe relaxation table type contains these fields: 171433965Sjdp 171533965Sjdp@table @code 171633965Sjdp@item long rlx_forward 171733965SjdpForward reach, must be non-negative. 171833965Sjdp@item long rlx_backward 171933965SjdpBackward reach, must be zero or negative. 172033965Sjdp@item rlx_length 172133965SjdpLength in bytes of this addressing mode. 172233965Sjdp@item rlx_more 172333965SjdpIndex of the next-longer relax state, or zero if there is no next relax state. 172433965Sjdp@end table 172533965Sjdp 172633965SjdpThe relaxation is done in @code{relax_segment} in @file{write.c}. The 172733965Sjdpdifference in the length fields between the original mode and the one finally 172833965Sjdpchosen by the relaxing code is taken as the size by which the current frag will 172933965Sjdpbe increased in size. For example, if the initial relaxing mode has a length 173033965Sjdpof 2 bytes, and because of the size of the displacement, it gets upgraded to a 173133965Sjdpmode with a size of 6 bytes, it is assumed that the frag will grow by 4 bytes. 173233965Sjdp(The initial two bytes should have been part of the fixed portion of the frag, 173333965Sjdpsince it is already known that they will be output.) This growth must be 173433965Sjdpeffected by @code{md_convert_frag}; it should increase the @code{fr_fix} field 173533965Sjdpby the appropriate size, and fill in the appropriate bytes of the frag. 173633965Sjdp(Enough space for the maximum growth should have been allocated in the call to 173733965Sjdpfrag_var as the second argument.) 173833965Sjdp 173933965SjdpIf relocation records are needed, they should be emitted by 174033965Sjdp@code{md_estimate_size_before_relax}. This function should examine the target 174133965Sjdpsymbol of the supplied frag and correct the @code{fr_subtype} of the frag if 174233965Sjdpneeded. When this function is called, if the symbol has not yet been defined, 174333965Sjdpit will not become defined later; however, its value may still change if the 174433965Sjdpsection it is in gets relaxed. 174533965Sjdp 174633965SjdpUsually, if the symbol is in the same section as the frag (given by the 174733965Sjdp@var{sec} argument), the narrowest likely relaxation mode is stored in 174833965Sjdp@code{fr_subtype}, and that's that. 174933965Sjdp 1750130561SobrienIf the symbol is undefined, or in a different section (and therefore movable 175133965Sjdpto an arbitrarily large distance), the largest available relaxation mode is 175233965Sjdpspecified, @code{fix_new} is called to produce the relocation record, 175333965Sjdp@code{fr_fix} is increased to include the relocated field (remember, this 175433965Sjdpstorage was allocated when @code{frag_var} was called), and @code{frag_wane} is 175533965Sjdpcalled to convert the frag to an @code{rs_fill} frag with no variant part. 175633965SjdpSometimes changing addressing modes may also require rewriting the instruction. 175733965SjdpIt can be accessed via @code{fr_opcode} or @code{fr_fix}. 175833965Sjdp 175977298SobrienIf you generate frags separately for the basic insn opcode and any relaxable 176077298Sobrienoperands, do not call @code{fix_new} thinking you can emit fixups for the 1761130561Sobrienopcode field from the relaxable frag. It is not guaranteed to be the same frag. 176277298SobrienIf you need to emit fixups for the opcode field from inspection of the 176377298Sobrienrelaxable frag, then you need to generate a common frag for both the basic 176477298Sobrienopcode and relaxable fields, or you need to provide the frag for the opcode to 176577298Sobrienpass to @code{fix_new}. The latter can be done for example by defining 176677298Sobrien@code{TC_FRAG_TYPE} to include a pointer to it and defining @code{TC_FRAG_INIT} 176777298Sobriento set the pointer. 176877298Sobrien 176933965SjdpSometimes @code{fr_var} is increased instead, and @code{frag_wane} is not 177033965Sjdpcalled. I'm not sure, but I think this is to keep @code{fr_fix} referring to 177133965Sjdpan earlier byte, and @code{fr_subtype} set to @code{rs_machine_dependent} so 177233965Sjdpthat @code{md_convert_frag} will get called. 177333965Sjdp 177433965Sjdp@node General relaxing 177533965Sjdp@subsection General relaxing 177633965Sjdp 177733965SjdpIf using a simple table is not suitable, you may implement arbitrarily complex 177833965Sjdprelaxation semantics yourself. For example, the MIPS backend uses this to emit 177933965Sjdpdifferent instruction sequences depending upon the size of the symbol being 178033965Sjdpaccessed. 178133965Sjdp 178233965SjdpWhen you assemble an instruction that may need relaxation, you should allocate 178333965Sjdpa frag using @code{frag_var} or @code{frag_variant} with a type of 178433965Sjdp@code{rs_machine_dependent}. You should store some sort of information in the 178533965Sjdp@code{fr_subtype} field so that you can figure out what to do with the frag 178633965Sjdplater. 178733965Sjdp 178833965SjdpWhen GAS reaches the end of the input file, it will look through the frags and 178933965Sjdpwork out their final sizes. 179033965Sjdp 179133965SjdpGAS will first call @code{md_estimate_size_before_relax} on each 179233965Sjdp@code{rs_machine_dependent} frag. This function must return an estimated size 179333965Sjdpfor the frag. 179433965Sjdp 179533965SjdpGAS will then loop over the frags, calling @code{md_relax_frag} on each 179633965Sjdp@code{rs_machine_dependent} frag. This function should return the change in 179733965Sjdpsize of the frag. GAS will keep looping over the frags until none of the frags 179833965Sjdpchanges size. 179933965Sjdp 180033965Sjdp@node Broken words 180133965Sjdp@section Broken words 180233965Sjdp@cindex internals, broken words 180333965Sjdp@cindex broken words 180433965Sjdp 180533965SjdpSome compilers, including GCC, will sometimes emit switch tables specifying 180633965Sjdp16-bit @code{.word} displacements to branch targets, and branch instructions 180733965Sjdpthat load entries from that table to compute the target address. If this is 180833965Sjdpdone on a 32-bit machine, there is a chance (at least with really large 180933965Sjdpfunctions) that the displacement will not fit in 16 bits. The assembler 181033965Sjdphandles this using a concept called @dfn{broken words}. This idea is well 181133965Sjdpnamed, since there is an implied promise that the 16-bit field will in fact 181233965Sjdphold the specified displacement. 181333965Sjdp 181433965SjdpIf broken word processing is enabled, and a situation like this is encountered, 181533965Sjdpthe assembler will insert a jump instruction into the instruction stream, close 181633965Sjdpenough to be reached with the 16-bit displacement. This jump instruction will 181733965Sjdptransfer to the real desired target address. Thus, as long as the @code{.word} 181833965Sjdpvalue really is used as a displacement to compute an address to jump to, the 181933965Sjdpnet effect will be correct (minus a very small efficiency cost). If 182033965Sjdp@code{.word} directives with label differences for values are used for other 182133965Sjdppurposes, however, things may not work properly. For targets which use broken 182233965Sjdpwords, the @samp{-K} option will warn when a broken word is discovered. 182333965Sjdp 182433965SjdpThe broken word code is turned off by the @code{WORKING_DOT_WORD} macro. It 182533965Sjdpisn't needed if @code{.word} emits a value large enough to contain an address 182633965Sjdp(or, more correctly, any possible difference between two addresses). 182733965Sjdp 182833965Sjdp@node Internal functions 182933965Sjdp@section Internal functions 183033965Sjdp 183133965SjdpThis section describes basic internal functions used by GAS. 183233965Sjdp 183333965Sjdp@menu 183433965Sjdp* Warning and error messages:: Warning and error messages 183533965Sjdp* Hash tables:: Hash tables 183633965Sjdp@end menu 183733965Sjdp 183833965Sjdp@node Warning and error messages 183933965Sjdp@subsection Warning and error messages 184033965Sjdp 184133965Sjdp@deftypefun @{@} int had_warnings (void) 184233965Sjdp@deftypefunx @{@} int had_errors (void) 184333965SjdpReturns non-zero if any warnings or errors, respectively, have been printed 184433965Sjdpduring this invocation. 184533965Sjdp@end deftypefun 184633965Sjdp 184733965Sjdp@deftypefun @{@} void as_tsktsk (const char *@var{format}, ...) 184833965Sjdp@deftypefunx @{@} void as_warn (const char *@var{format}, ...) 184933965Sjdp@deftypefunx @{@} void as_bad (const char *@var{format}, ...) 185033965Sjdp@deftypefunx @{@} void as_fatal (const char *@var{format}, ...) 185133965SjdpThese functions display messages about something amiss with the input file, or 185233965Sjdpinternal problems in the assembler itself. The current file name and line 185333965Sjdpnumber are printed, followed by the supplied message, formatted using 185433965Sjdp@code{vfprintf}, and a final newline. 185533965Sjdp 185633965SjdpAn error indicated by @code{as_bad} will result in a non-zero exit status when 185733965Sjdpthe assembler has finished. Calling @code{as_fatal} will result in immediate 185833965Sjdptermination of the assembler process. 185933965Sjdp@end deftypefun 186033965Sjdp 186133965Sjdp@deftypefun @{@} void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...) 186233965Sjdp@deftypefunx @{@} void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...) 186333965SjdpThese variants permit specification of the file name and line number, and are 186433965Sjdpused when problems are detected when reprocessing information saved away when 186533965Sjdpprocessing some earlier part of the file. For example, fixups are processed 186633965Sjdpafter all input has been read, but messages about fixups should refer to the 186733965Sjdporiginal filename and line number that they are applicable to. 186833965Sjdp@end deftypefun 186933965Sjdp 1870218822Sdim@deftypefun @{@} void sprint_value (char *@var{buf}, valueT @var{val}) 1871218822SdimThis function is helpful for converting a @code{valueT} value into printable 187233965Sjdpformat, in case it's wider than modes that @code{*printf} can handle. If the 187333965Sjdptype is narrow enough, a decimal number will be produced; otherwise, it will be 187433965Sjdpin hexadecimal. The value itself is not examined to make this determination. 187533965Sjdp@end deftypefun 187633965Sjdp 187733965Sjdp@node Hash tables 187833965Sjdp@subsection Hash tables 187933965Sjdp@cindex hash tables 188033965Sjdp 188133965Sjdp@deftypefun @{@} @{struct hash_control *@} hash_new (void) 188233965SjdpCreates the hash table control structure. 188333965Sjdp@end deftypefun 188433965Sjdp 188533965Sjdp@deftypefun @{@} void hash_die (struct hash_control *) 188633965SjdpDestroy a hash table. 188733965Sjdp@end deftypefun 188833965Sjdp 188933965Sjdp@deftypefun @{@} PTR hash_delete (struct hash_control *, const char *) 189033965SjdpDeletes entry from the hash table, returns the value it had. 189133965Sjdp@end deftypefun 189233965Sjdp 189333965Sjdp@deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR) 189433965SjdpUpdates the value for an entry already in the table, returning the old value. 189533965SjdpIf no entry was found, just returns NULL. 189633965Sjdp@end deftypefun 189733965Sjdp 189833965Sjdp@deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR) 189933965SjdpInserting a value already in the table is an error. 190033965SjdpReturns an error message or NULL. 190133965Sjdp@end deftypefun 190233965Sjdp 190333965Sjdp@deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR) 190433965SjdpInserts if the value isn't already present, updates it if it is. 190533965Sjdp@end deftypefun 190633965Sjdp 190733965Sjdp@node Test suite 190833965Sjdp@section Test suite 190933965Sjdp@cindex test suite 191033965Sjdp 191133965SjdpThe test suite is kind of lame for most processors. Often it only checks to 191233965Sjdpsee if a couple of files can be assembled without the assembler reporting any 191333965Sjdperrors. For more complete testing, write a test which either examines the 191433965Sjdpassembler listing, or runs @code{objdump} and examines its output. For the 191533965Sjdplatter, the TCL procedure @code{run_dump_test} may come in handy. It takes the 191633965Sjdpbase name of a file, and looks for @file{@var{file}.d}. This file should 191733965Sjdpcontain as its initial lines a set of variable settings in @samp{#} comments, 191833965Sjdpin the form: 191933965Sjdp 192033965Sjdp@example 192133965Sjdp #@var{varname}: @var{value} 192233965Sjdp@end example 192333965Sjdp 192433965SjdpThe @var{varname} may be @code{objdump}, @code{nm}, or @code{as}, in which case 192533965Sjdpit specifies the options to be passed to the specified programs. Exactly one 192633965Sjdpof @code{objdump} or @code{nm} must be specified, as that also specifies which 192733965Sjdpprogram to run after the assembler has finished. If @var{varname} is 192833965Sjdp@code{source}, it specifies the name of the source file; otherwise, 192933965Sjdp@file{@var{file}.s} is used. If @var{varname} is @code{name}, it specifies the 193033965Sjdpname of the test to be used in the @code{pass} or @code{fail} messages. 193133965Sjdp 193233965SjdpThe non-commented parts of the file are interpreted as regular expressions, one 193333965Sjdpper line. Blank lines in the @code{objdump} or @code{nm} output are skipped, 193433965Sjdpas are blank lines in the @code{.d} file; the other lines are tested to see if 193533965Sjdpthe regular expression matches the program output. If it does not, the test 193633965Sjdpfails. 193733965Sjdp 193833965SjdpNote that this means the tests must be modified if the @code{objdump} output 193933965Sjdpstyle is changed. 194033965Sjdp 194133965Sjdp@bye 194233965Sjdp@c Local Variables: 194333965Sjdp@c fill-column: 79 194433965Sjdp@c End: 1945