1*3d8817e4Smiod\input texinfo 2*3d8817e4Smiod@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 3*3d8817e4Smiod@c 2001, 2002, 2003, 2004, 2005 4*3d8817e4Smiod@c Free Software Foundation, Inc. 5*3d8817e4Smiod@setfilename internals.info 6*3d8817e4Smiod@node Top 7*3d8817e4Smiod@top Assembler Internals 8*3d8817e4Smiod@raisesections 9*3d8817e4Smiod@cindex internals 10*3d8817e4Smiod 11*3d8817e4SmiodThis chapter describes the internals of the assembler. It is incomplete, but 12*3d8817e4Smiodit may help a bit. 13*3d8817e4Smiod 14*3d8817e4SmiodThis chapter is not updated regularly, and it may be out of date. 15*3d8817e4Smiod 16*3d8817e4Smiod@menu 17*3d8817e4Smiod* Data types:: Data types 18*3d8817e4Smiod* GAS processing:: What GAS does when it runs 19*3d8817e4Smiod* Porting GAS:: Porting GAS 20*3d8817e4Smiod* Relaxation:: Relaxation 21*3d8817e4Smiod* Broken words:: Broken words 22*3d8817e4Smiod* Internal functions:: Internal functions 23*3d8817e4Smiod* Test suite:: Test suite 24*3d8817e4Smiod@end menu 25*3d8817e4Smiod 26*3d8817e4Smiod@node Data types 27*3d8817e4Smiod@section Data types 28*3d8817e4Smiod@cindex internals, data types 29*3d8817e4Smiod 30*3d8817e4SmiodThis section describes some fundamental GAS data types. 31*3d8817e4Smiod 32*3d8817e4Smiod@menu 33*3d8817e4Smiod* Symbols:: The symbolS structure 34*3d8817e4Smiod* Expressions:: The expressionS structure 35*3d8817e4Smiod* Fixups:: The fixS structure 36*3d8817e4Smiod* Frags:: The fragS structure 37*3d8817e4Smiod@end menu 38*3d8817e4Smiod 39*3d8817e4Smiod@node Symbols 40*3d8817e4Smiod@subsection Symbols 41*3d8817e4Smiod@cindex internals, symbols 42*3d8817e4Smiod@cindex symbols, internal 43*3d8817e4Smiod@cindex symbolS structure 44*3d8817e4Smiod 45*3d8817e4SmiodThe definition for the symbol structure, @code{symbolS}, is located in 46*3d8817e4Smiod@file{struc-symbol.h}. 47*3d8817e4Smiod 48*3d8817e4SmiodIn general, the fields of this structure may not be referred to directly. 49*3d8817e4SmiodInstead, you must use one of the accessor functions defined in @file{symbol.h}. 50*3d8817e4SmiodThese accessor functions should work for any GAS version. 51*3d8817e4Smiod 52*3d8817e4SmiodSymbol structures contain the following fields: 53*3d8817e4Smiod 54*3d8817e4Smiod@table @code 55*3d8817e4Smiod@item sy_value 56*3d8817e4SmiodThis is an @code{expressionS} that describes the value of the symbol. It might 57*3d8817e4Smiodrefer to one or more other symbols; if so, its true value may not be known 58*3d8817e4Smioduntil @code{resolve_symbol_value} is called with @var{finalize_syms} non-zero 59*3d8817e4Smiodin @code{write_object_file}. 60*3d8817e4Smiod 61*3d8817e4SmiodThe expression is often simply a constant. Before @code{resolve_symbol_value} 62*3d8817e4Smiodis called with @var{finalize_syms} set, the value is the offset from the frag 63*3d8817e4Smiod(@pxref{Frags}). Afterward, the frag address has been added in. 64*3d8817e4Smiod 65*3d8817e4Smiod@item sy_resolved 66*3d8817e4SmiodThis field is non-zero if the symbol's value has been completely resolved. It 67*3d8817e4Smiodis used during the final pass over the symbol table. 68*3d8817e4Smiod 69*3d8817e4Smiod@item sy_resolving 70*3d8817e4SmiodThis field is used to detect loops while resolving the symbol's value. 71*3d8817e4Smiod 72*3d8817e4Smiod@item sy_used_in_reloc 73*3d8817e4SmiodThis field is non-zero if the symbol is used by a relocation entry. If a local 74*3d8817e4Smiodsymbol is used in a relocation entry, it must be possible to redirect those 75*3d8817e4Smiodrelocations to other symbols, or this symbol cannot be removed from the final 76*3d8817e4Smiodsymbol list. 77*3d8817e4Smiod 78*3d8817e4Smiod@item sy_next 79*3d8817e4Smiod@itemx sy_previous 80*3d8817e4SmiodThese pointers to other @code{symbolS} structures describe a doubly 81*3d8817e4Smiodlinked list. These fields should be accessed with 82*3d8817e4Smiodthe @code{symbol_next} and @code{symbol_previous} macros. 83*3d8817e4Smiod 84*3d8817e4Smiod@item sy_frag 85*3d8817e4SmiodThis points to the frag (@pxref{Frags}) that this symbol is attached to. 86*3d8817e4Smiod 87*3d8817e4Smiod@item sy_used 88*3d8817e4SmiodWhether the symbol is used as an operand or in an expression. Note: Not all of 89*3d8817e4Smiodthe backends keep this information accurate; backends which use this bit are 90*3d8817e4Smiodresponsible for setting it when a symbol is used in backend routines. 91*3d8817e4Smiod 92*3d8817e4Smiod@item sy_mri_common 93*3d8817e4SmiodWhether the symbol is an MRI common symbol created by the @code{COMMON} 94*3d8817e4Smiodpseudo-op when assembling in MRI mode. 95*3d8817e4Smiod 96*3d8817e4Smiod@item sy_volatile 97*3d8817e4SmiodWhether the symbol can be re-defined. 98*3d8817e4Smiod 99*3d8817e4Smiod@item sy_forward_ref 100*3d8817e4SmiodWhether the symbol's value must only be evaluated upon use. 101*3d8817e4Smiod 102*3d8817e4Smiod@item sy_weakrefr 103*3d8817e4SmiodWhether the symbol is a @code{weakref} alias to another symbol. 104*3d8817e4Smiod 105*3d8817e4Smiod@item sy_weakrefd 106*3d8817e4SmiodWhether the symbol is or was referenced by one or more @code{weakref} aliases, 107*3d8817e4Smiodand has not had any direct references. 108*3d8817e4Smiod 109*3d8817e4Smiod@item bsym 110*3d8817e4SmiodThis points to the BFD @code{asymbol} that 111*3d8817e4Smiodwill be used in writing the object file. 112*3d8817e4Smiod 113*3d8817e4Smiod@item sy_obj 114*3d8817e4SmiodThis format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by 115*3d8817e4Smiodthat name is defined in @file{obj-format.h}, this field is not defined. 116*3d8817e4Smiod 117*3d8817e4Smiod@item sy_tc 118*3d8817e4SmiodThis processor-specific data is of type @code{TC_SYMFIELD_TYPE}. If no macro 119*3d8817e4Smiodby that name is defined in @file{targ-cpu.h}, this field is not defined. 120*3d8817e4Smiod 121*3d8817e4Smiod@end table 122*3d8817e4Smiod 123*3d8817e4SmiodHere is a description of the accessor functions. These should be used rather 124*3d8817e4Smiodthan referring to the fields of @code{symbolS} directly. 125*3d8817e4Smiod 126*3d8817e4Smiod@table @code 127*3d8817e4Smiod@item S_SET_VALUE 128*3d8817e4Smiod@cindex S_SET_VALUE 129*3d8817e4SmiodSet the symbol's value. 130*3d8817e4Smiod 131*3d8817e4Smiod@item S_GET_VALUE 132*3d8817e4Smiod@cindex S_GET_VALUE 133*3d8817e4SmiodGet the symbol's value. This will cause @code{resolve_symbol_value} to be 134*3d8817e4Smiodcalled if necessary. 135*3d8817e4Smiod 136*3d8817e4Smiod@item S_SET_SEGMENT 137*3d8817e4Smiod@cindex S_SET_SEGMENT 138*3d8817e4SmiodSet the section of the symbol. 139*3d8817e4Smiod 140*3d8817e4Smiod@item S_GET_SEGMENT 141*3d8817e4Smiod@cindex S_GET_SEGMENT 142*3d8817e4SmiodGet the symbol's section. 143*3d8817e4Smiod 144*3d8817e4Smiod@item S_GET_NAME 145*3d8817e4Smiod@cindex S_GET_NAME 146*3d8817e4SmiodGet the name of the symbol. 147*3d8817e4Smiod 148*3d8817e4Smiod@item S_SET_NAME 149*3d8817e4Smiod@cindex S_SET_NAME 150*3d8817e4SmiodSet the name of the symbol. 151*3d8817e4Smiod 152*3d8817e4Smiod@item S_IS_EXTERNAL 153*3d8817e4Smiod@cindex S_IS_EXTERNAL 154*3d8817e4SmiodReturn non-zero if the symbol is externally visible. 155*3d8817e4Smiod 156*3d8817e4Smiod@item S_IS_EXTERN 157*3d8817e4Smiod@cindex S_IS_EXTERN 158*3d8817e4SmiodA synonym for @code{S_IS_EXTERNAL}. Don't use it. 159*3d8817e4Smiod 160*3d8817e4Smiod@item S_IS_WEAK 161*3d8817e4Smiod@cindex S_IS_WEAK 162*3d8817e4SmiodReturn non-zero if the symbol is weak, or if it is a @code{weakref} alias or 163*3d8817e4Smiodsymbol that has not been strongly referenced. 164*3d8817e4Smiod 165*3d8817e4Smiod@item S_IS_WEAKREFR 166*3d8817e4Smiod@cindex S_IS_WEAKREFR 167*3d8817e4SmiodReturn non-zero if the symbol is a @code{weakref} alias. 168*3d8817e4Smiod 169*3d8817e4Smiod@item S_IS_WEAKREFD 170*3d8817e4Smiod@cindex S_IS_WEAKREFD 171*3d8817e4SmiodReturn non-zero if the symbol was aliased by a @code{weakref} alias and has not 172*3d8817e4Smiodhad any strong references. 173*3d8817e4Smiod 174*3d8817e4Smiod@item S_IS_VOLATILE 175*3d8817e4Smiod@cindex S_IS_VOLATILE 176*3d8817e4SmiodReturn non-zero if the symbol may be re-defined. Such symbols get created by 177*3d8817e4Smiodthe @code{=} operator, @code{equ}, or @code{set}. 178*3d8817e4Smiod 179*3d8817e4Smiod@item S_IS_FORWARD_REF 180*3d8817e4Smiod@cindex S_IS_FORWARD_REF 181*3d8817e4SmiodReturn non-zero if the symbol is a forward reference, that is its value must 182*3d8817e4Smiodonly be determined upon use. 183*3d8817e4Smiod 184*3d8817e4Smiod@item S_IS_COMMON 185*3d8817e4Smiod@cindex S_IS_COMMON 186*3d8817e4SmiodReturn non-zero if this is a common symbol. Common symbols are sometimes 187*3d8817e4Smiodrepresented as undefined symbols with a value, in which case this function will 188*3d8817e4Smiodnot be reliable. 189*3d8817e4Smiod 190*3d8817e4Smiod@item S_IS_DEFINED 191*3d8817e4Smiod@cindex S_IS_DEFINED 192*3d8817e4SmiodReturn non-zero if this symbol is defined. This function is not reliable when 193*3d8817e4Smiodcalled on a common symbol. 194*3d8817e4Smiod 195*3d8817e4Smiod@item S_IS_DEBUG 196*3d8817e4Smiod@cindex S_IS_DEBUG 197*3d8817e4SmiodReturn non-zero if this is a debugging symbol. 198*3d8817e4Smiod 199*3d8817e4Smiod@item S_IS_LOCAL 200*3d8817e4Smiod@cindex S_IS_LOCAL 201*3d8817e4SmiodReturn non-zero if this is a local assembler symbol which should not be 202*3d8817e4Smiodincluded in the final symbol table. Note that this is not the opposite of 203*3d8817e4Smiod@code{S_IS_EXTERNAL}. The @samp{-L} assembler option affects the return value 204*3d8817e4Smiodof this function. 205*3d8817e4Smiod 206*3d8817e4Smiod@item S_SET_EXTERNAL 207*3d8817e4Smiod@cindex S_SET_EXTERNAL 208*3d8817e4SmiodMark the symbol as externally visible. 209*3d8817e4Smiod 210*3d8817e4Smiod@item S_CLEAR_EXTERNAL 211*3d8817e4Smiod@cindex S_CLEAR_EXTERNAL 212*3d8817e4SmiodMark the symbol as not externally visible. 213*3d8817e4Smiod 214*3d8817e4Smiod@item S_SET_WEAK 215*3d8817e4Smiod@cindex S_SET_WEAK 216*3d8817e4SmiodMark the symbol as weak. 217*3d8817e4Smiod 218*3d8817e4Smiod@item S_SET_WEAKREFR 219*3d8817e4Smiod@cindex S_SET_WEAKREFR 220*3d8817e4SmiodMark the symbol as the referrer in a @code{weakref} directive. The symbol it 221*3d8817e4Smiodaliases must have been set to the value expression before this point. If the 222*3d8817e4Smiodalias has already been used, the symbol is marked as used too. 223*3d8817e4Smiod 224*3d8817e4Smiod@item S_CLEAR_WEAKREFR 225*3d8817e4Smiod@cindex S_CLEAR_WEAKREFR 226*3d8817e4SmiodClear the @code{weakref} alias status of a symbol. This is implicitly called 227*3d8817e4Smiodwhenever a symbol is defined or set to a new expression. 228*3d8817e4Smiod 229*3d8817e4Smiod@item S_SET_WEAKREFD 230*3d8817e4Smiod@cindex S_SET_WEAKREFD 231*3d8817e4SmiodMark the symbol as the referred symbol in a @code{weakref} directive. 232*3d8817e4SmiodImplicitly marks the symbol as weak, but see below. It should only be called 233*3d8817e4Smiodif the referenced symbol has just been added to the symbol table. 234*3d8817e4Smiod 235*3d8817e4Smiod@item S_SET_WEAKREFD 236*3d8817e4Smiod@cindex S_SET_WEAKREFD 237*3d8817e4SmiodClear the @code{weakref} aliased status of a symbol. This is implicitly called 238*3d8817e4Smiodwhenever the symbol is looked up, as part of a direct reference or a 239*3d8817e4Smioddefinition, but not as part of a @code{weakref} directive. 240*3d8817e4Smiod 241*3d8817e4Smiod@item S_SET_VOLATILE 242*3d8817e4Smiod@cindex S_SET_VOLATILE 243*3d8817e4SmiodIndicate that the symbol may be re-defined. 244*3d8817e4Smiod 245*3d8817e4Smiod@item S_CLEAR_VOLATILE 246*3d8817e4Smiod@cindex S_CLEAR_VOLATILE 247*3d8817e4SmiodIndicate that the symbol may no longer be re-defined. 248*3d8817e4Smiod 249*3d8817e4Smiod@item S_SET_FORWARD_REF 250*3d8817e4Smiod@cindex S_SET_FORWARD_REF 251*3d8817e4SmiodIndicate that the symbol is a forward reference, that is its value must only 252*3d8817e4Smiodbe determined upon use. 253*3d8817e4Smiod 254*3d8817e4Smiod@item S_GET_TYPE 255*3d8817e4Smiod@item S_GET_DESC 256*3d8817e4Smiod@item S_GET_OTHER 257*3d8817e4Smiod@cindex S_GET_TYPE 258*3d8817e4Smiod@cindex S_GET_DESC 259*3d8817e4Smiod@cindex S_GET_OTHER 260*3d8817e4SmiodGet the @code{type}, @code{desc}, and @code{other} fields of the symbol. These 261*3d8817e4Smiodare only defined for object file formats for which they make sense (primarily 262*3d8817e4Smioda.out). 263*3d8817e4Smiod 264*3d8817e4Smiod@item S_SET_TYPE 265*3d8817e4Smiod@item S_SET_DESC 266*3d8817e4Smiod@item S_SET_OTHER 267*3d8817e4Smiod@cindex S_SET_TYPE 268*3d8817e4Smiod@cindex S_SET_DESC 269*3d8817e4Smiod@cindex S_SET_OTHER 270*3d8817e4SmiodSet the @code{type}, @code{desc}, and @code{other} fields of the symbol. These 271*3d8817e4Smiodare only defined for object file formats for which they make sense (primarily 272*3d8817e4Smioda.out). 273*3d8817e4Smiod 274*3d8817e4Smiod@item S_GET_SIZE 275*3d8817e4Smiod@cindex S_GET_SIZE 276*3d8817e4SmiodGet the size of a symbol. This is only defined for object file formats for 277*3d8817e4Smiodwhich it makes sense (primarily ELF). 278*3d8817e4Smiod 279*3d8817e4Smiod@item S_SET_SIZE 280*3d8817e4Smiod@cindex S_SET_SIZE 281*3d8817e4SmiodSet the size of a symbol. This is only defined for object file formats for 282*3d8817e4Smiodwhich it makes sense (primarily ELF). 283*3d8817e4Smiod 284*3d8817e4Smiod@item symbol_get_value_expression 285*3d8817e4Smiod@cindex symbol_get_value_expression 286*3d8817e4SmiodGet a pointer to an @code{expressionS} structure which represents the value of 287*3d8817e4Smiodthe symbol as an expression. 288*3d8817e4Smiod 289*3d8817e4Smiod@item symbol_set_value_expression 290*3d8817e4Smiod@cindex symbol_set_value_expression 291*3d8817e4SmiodSet the value of a symbol to an expression. 292*3d8817e4Smiod 293*3d8817e4Smiod@item symbol_set_frag 294*3d8817e4Smiod@cindex symbol_set_frag 295*3d8817e4SmiodSet the frag where a symbol is defined. 296*3d8817e4Smiod 297*3d8817e4Smiod@item symbol_get_frag 298*3d8817e4Smiod@cindex symbol_get_frag 299*3d8817e4SmiodGet the frag where a symbol is defined. 300*3d8817e4Smiod 301*3d8817e4Smiod@item symbol_mark_used 302*3d8817e4Smiod@cindex symbol_mark_used 303*3d8817e4SmiodMark a symbol as having been used in an expression. 304*3d8817e4Smiod 305*3d8817e4Smiod@item symbol_clear_used 306*3d8817e4Smiod@cindex symbol_clear_used 307*3d8817e4SmiodClear the mark indicating that a symbol was used in an expression. 308*3d8817e4Smiod 309*3d8817e4Smiod@item symbol_used_p 310*3d8817e4Smiod@cindex symbol_used_p 311*3d8817e4SmiodReturn whether a symbol was used in an expression. 312*3d8817e4Smiod 313*3d8817e4Smiod@item symbol_mark_used_in_reloc 314*3d8817e4Smiod@cindex symbol_mark_used_in_reloc 315*3d8817e4SmiodMark a symbol as having been used by a relocation. 316*3d8817e4Smiod 317*3d8817e4Smiod@item symbol_clear_used_in_reloc 318*3d8817e4Smiod@cindex symbol_clear_used_in_reloc 319*3d8817e4SmiodClear the mark indicating that a symbol was used in a relocation. 320*3d8817e4Smiod 321*3d8817e4Smiod@item symbol_used_in_reloc_p 322*3d8817e4Smiod@cindex symbol_used_in_reloc_p 323*3d8817e4SmiodReturn whether a symbol was used in a relocation. 324*3d8817e4Smiod 325*3d8817e4Smiod@item symbol_mark_mri_common 326*3d8817e4Smiod@cindex symbol_mark_mri_common 327*3d8817e4SmiodMark a symbol as an MRI common symbol. 328*3d8817e4Smiod 329*3d8817e4Smiod@item symbol_clear_mri_common 330*3d8817e4Smiod@cindex symbol_clear_mri_common 331*3d8817e4SmiodClear the mark indicating that a symbol is an MRI common symbol. 332*3d8817e4Smiod 333*3d8817e4Smiod@item symbol_mri_common_p 334*3d8817e4Smiod@cindex symbol_mri_common_p 335*3d8817e4SmiodReturn whether a symbol is an MRI common symbol. 336*3d8817e4Smiod 337*3d8817e4Smiod@item symbol_mark_written 338*3d8817e4Smiod@cindex symbol_mark_written 339*3d8817e4SmiodMark a symbol as having been written. 340*3d8817e4Smiod 341*3d8817e4Smiod@item symbol_clear_written 342*3d8817e4Smiod@cindex symbol_clear_written 343*3d8817e4SmiodClear the mark indicating that a symbol was written. 344*3d8817e4Smiod 345*3d8817e4Smiod@item symbol_written_p 346*3d8817e4Smiod@cindex symbol_written_p 347*3d8817e4SmiodReturn whether a symbol was written. 348*3d8817e4Smiod 349*3d8817e4Smiod@item symbol_mark_resolved 350*3d8817e4Smiod@cindex symbol_mark_resolved 351*3d8817e4SmiodMark a symbol as having been resolved. 352*3d8817e4Smiod 353*3d8817e4Smiod@item symbol_resolved_p 354*3d8817e4Smiod@cindex symbol_resolved_p 355*3d8817e4SmiodReturn whether a symbol has been resolved. 356*3d8817e4Smiod 357*3d8817e4Smiod@item symbol_section_p 358*3d8817e4Smiod@cindex symbol_section_p 359*3d8817e4SmiodReturn whether a symbol is a section symbol. 360*3d8817e4Smiod 361*3d8817e4Smiod@item symbol_equated_p 362*3d8817e4Smiod@cindex symbol_equated_p 363*3d8817e4SmiodReturn whether a symbol is equated to another symbol. 364*3d8817e4Smiod 365*3d8817e4Smiod@item symbol_constant_p 366*3d8817e4Smiod@cindex symbol_constant_p 367*3d8817e4SmiodReturn whether a symbol has a constant value, including being an offset within 368*3d8817e4Smiodsome frag. 369*3d8817e4Smiod 370*3d8817e4Smiod@item symbol_get_bfdsym 371*3d8817e4Smiod@cindex symbol_get_bfdsym 372*3d8817e4SmiodReturn the BFD symbol associated with a symbol. 373*3d8817e4Smiod 374*3d8817e4Smiod@item symbol_set_bfdsym 375*3d8817e4Smiod@cindex symbol_set_bfdsym 376*3d8817e4SmiodSet the BFD symbol associated with a symbol. 377*3d8817e4Smiod 378*3d8817e4Smiod@item symbol_get_obj 379*3d8817e4Smiod@cindex symbol_get_obj 380*3d8817e4SmiodReturn a pointer to the @code{OBJ_SYMFIELD_TYPE} field of a symbol. 381*3d8817e4Smiod 382*3d8817e4Smiod@item symbol_set_obj 383*3d8817e4Smiod@cindex symbol_set_obj 384*3d8817e4SmiodSet the @code{OBJ_SYMFIELD_TYPE} field of a symbol. 385*3d8817e4Smiod 386*3d8817e4Smiod@item symbol_get_tc 387*3d8817e4Smiod@cindex symbol_get_tc 388*3d8817e4SmiodReturn a pointer to the @code{TC_SYMFIELD_TYPE} field of a symbol. 389*3d8817e4Smiod 390*3d8817e4Smiod@item symbol_set_tc 391*3d8817e4Smiod@cindex symbol_set_tc 392*3d8817e4SmiodSet the @code{TC_SYMFIELD_TYPE} field of a symbol. 393*3d8817e4Smiod 394*3d8817e4Smiod@end table 395*3d8817e4Smiod 396*3d8817e4SmiodGAS attempts to store local 397*3d8817e4Smiodsymbols--symbols which will not be written to the output file--using a 398*3d8817e4Smioddifferent structure, @code{struct local_symbol}. This structure can only 399*3d8817e4Smiodrepresent symbols whose value is an offset within a frag. 400*3d8817e4Smiod 401*3d8817e4SmiodCode outside of the symbol handler will always deal with @code{symbolS} 402*3d8817e4Smiodstructures and use the accessor functions. The accessor functions correctly 403*3d8817e4Smioddeal with local symbols. @code{struct local_symbol} is much smaller than 404*3d8817e4Smiod@code{symbolS} (which also automatically creates a bfd @code{asymbol} 405*3d8817e4Smiodstructure), so this saves space when assembling large files. 406*3d8817e4Smiod 407*3d8817e4SmiodThe first field of @code{symbolS} is @code{bsym}, the pointer to the BFD 408*3d8817e4Smiodsymbol. The first field of @code{struct local_symbol} is a pointer which is 409*3d8817e4Smiodalways set to NULL. This is how the symbol accessor functions can distinguish 410*3d8817e4Smiodlocal symbols from ordinary symbols. The symbol accessor functions 411*3d8817e4Smiodautomatically convert a local symbol into an ordinary symbol when necessary. 412*3d8817e4Smiod 413*3d8817e4Smiod@node Expressions 414*3d8817e4Smiod@subsection Expressions 415*3d8817e4Smiod@cindex internals, expressions 416*3d8817e4Smiod@cindex expressions, internal 417*3d8817e4Smiod@cindex expressionS structure 418*3d8817e4Smiod 419*3d8817e4SmiodExpressions are stored in an @code{expressionS} structure. The structure is 420*3d8817e4Smioddefined in @file{expr.h}. 421*3d8817e4Smiod 422*3d8817e4Smiod@cindex expression 423*3d8817e4SmiodThe macro @code{expression} will create an @code{expressionS} structure based 424*3d8817e4Smiodon the text found at the global variable @code{input_line_pointer}. 425*3d8817e4Smiod 426*3d8817e4Smiod@cindex make_expr_symbol 427*3d8817e4Smiod@cindex expr_symbol_where 428*3d8817e4SmiodA single @code{expressionS} structure can represent a single operation. 429*3d8817e4SmiodComplex expressions are formed by creating @dfn{expression symbols} and 430*3d8817e4Smiodcombining them in @code{expressionS} structures. An expression symbol is 431*3d8817e4Smiodcreated by calling @code{make_expr_symbol}. An expression symbol should 432*3d8817e4Smiodnaturally never appear in a symbol table, and the implementation of 433*3d8817e4Smiod@code{S_IS_LOCAL} (@pxref{Symbols}) reflects that. The function 434*3d8817e4Smiod@code{expr_symbol_where} returns non-zero if a symbol is an expression symbol, 435*3d8817e4Smiodand also returns the file and line for the expression which caused it to be 436*3d8817e4Smiodcreated. 437*3d8817e4Smiod 438*3d8817e4SmiodThe @code{expressionS} structure has two symbol fields, a number field, an 439*3d8817e4Smiodoperator field, and a field indicating whether the number is unsigned. 440*3d8817e4Smiod 441*3d8817e4SmiodThe operator field is of type @code{operatorT}, and describes how to interpret 442*3d8817e4Smiodthe other fields; see the definition in @file{expr.h} for the possibilities. 443*3d8817e4Smiod 444*3d8817e4SmiodAn @code{operatorT} value of @code{O_big} indicates either a floating point 445*3d8817e4Smiodnumber, stored in the global variable @code{generic_floating_point_number}, or 446*3d8817e4Smiodan integer too large to store in an @code{offsetT} type, stored in the global 447*3d8817e4Smiodarray @code{generic_bignum}. This rather inflexible approach makes it 448*3d8817e4Smiodimpossible to use floating point numbers or large expressions in complex 449*3d8817e4Smiodexpressions. 450*3d8817e4Smiod 451*3d8817e4Smiod@node Fixups 452*3d8817e4Smiod@subsection Fixups 453*3d8817e4Smiod@cindex internals, fixups 454*3d8817e4Smiod@cindex fixups 455*3d8817e4Smiod@cindex fixS structure 456*3d8817e4Smiod 457*3d8817e4SmiodA @dfn{fixup} is basically anything which can not be resolved in the first 458*3d8817e4Smiodpass. Sometimes a fixup can be resolved by the end of the assembly; if not, 459*3d8817e4Smiodthe fixup becomes a relocation entry in the object file. 460*3d8817e4Smiod 461*3d8817e4Smiod@cindex fix_new 462*3d8817e4Smiod@cindex fix_new_exp 463*3d8817e4SmiodA fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both 464*3d8817e4Smiodtake a frag (@pxref{Frags}), a position within the frag, a size, an indication 465*3d8817e4Smiodof whether the fixup is PC relative, and a type. 466*3d8817e4SmiodThe type is nominally a @code{bfd_reloc_code_real_type}, but several 467*3d8817e4Smiodtargets use other type codes to represent fixups that can not be described as 468*3d8817e4Smiodrelocations. 469*3d8817e4Smiod 470*3d8817e4SmiodThe @code{fixS} structure has a number of fields, several of which are obsolete 471*3d8817e4Smiodor are only used by a particular target. The important fields are: 472*3d8817e4Smiod 473*3d8817e4Smiod@table @code 474*3d8817e4Smiod@item fx_frag 475*3d8817e4SmiodThe frag (@pxref{Frags}) this fixup is in. 476*3d8817e4Smiod 477*3d8817e4Smiod@item fx_where 478*3d8817e4SmiodThe location within the frag where the fixup occurs. 479*3d8817e4Smiod 480*3d8817e4Smiod@item fx_addsy 481*3d8817e4SmiodThe symbol this fixup is against. Typically, the value of this symbol is added 482*3d8817e4Smiodinto the object contents. This may be NULL. 483*3d8817e4Smiod 484*3d8817e4Smiod@item fx_subsy 485*3d8817e4SmiodThe value of this symbol is subtracted from the object contents. This is 486*3d8817e4Smiodnormally NULL. 487*3d8817e4Smiod 488*3d8817e4Smiod@item fx_offset 489*3d8817e4SmiodA number which is added into the fixup. 490*3d8817e4Smiod 491*3d8817e4Smiod@item fx_addnumber 492*3d8817e4SmiodSome CPU backends use this field to convey information between 493*3d8817e4Smiod@code{md_apply_fix} and @code{tc_gen_reloc}. The machine independent code does 494*3d8817e4Smiodnot use it. 495*3d8817e4Smiod 496*3d8817e4Smiod@item fx_next 497*3d8817e4SmiodThe next fixup in the section. 498*3d8817e4Smiod 499*3d8817e4Smiod@item fx_r_type 500*3d8817e4SmiodThe type of the fixup. 501*3d8817e4Smiod 502*3d8817e4Smiod@item fx_size 503*3d8817e4SmiodThe size of the fixup. This is mostly used for error checking. 504*3d8817e4Smiod 505*3d8817e4Smiod@item fx_pcrel 506*3d8817e4SmiodWhether the fixup is PC relative. 507*3d8817e4Smiod 508*3d8817e4Smiod@item fx_done 509*3d8817e4SmiodNon-zero if the fixup has been applied, and no relocation entry needs to be 510*3d8817e4Smiodgenerated. 511*3d8817e4Smiod 512*3d8817e4Smiod@item fx_file 513*3d8817e4Smiod@itemx fx_line 514*3d8817e4SmiodThe file and line where the fixup was created. 515*3d8817e4Smiod 516*3d8817e4Smiod@item tc_fix_data 517*3d8817e4SmiodThis has the type @code{TC_FIX_TYPE}, and is only defined if the target defines 518*3d8817e4Smiodthat macro. 519*3d8817e4Smiod@end table 520*3d8817e4Smiod 521*3d8817e4Smiod@node Frags 522*3d8817e4Smiod@subsection Frags 523*3d8817e4Smiod@cindex internals, frags 524*3d8817e4Smiod@cindex frags 525*3d8817e4Smiod@cindex fragS structure. 526*3d8817e4Smiod 527*3d8817e4SmiodThe @code{fragS} structure is defined in @file{as.h}. Each frag represents a 528*3d8817e4Smiodportion of the final object file. As GAS reads the source file, it creates 529*3d8817e4Smiodfrags to hold the data that it reads. At the end of the assembly the frags and 530*3d8817e4Smiodfixups are processed to produce the final contents. 531*3d8817e4Smiod 532*3d8817e4Smiod@table @code 533*3d8817e4Smiod@item fr_address 534*3d8817e4SmiodThe address of the frag. This is not set until the assembler rescans the list 535*3d8817e4Smiodof all frags after the entire input file is parsed. The function 536*3d8817e4Smiod@code{relax_segment} fills in this field. 537*3d8817e4Smiod 538*3d8817e4Smiod@item fr_next 539*3d8817e4SmiodPointer to the next frag in this (sub)section. 540*3d8817e4Smiod 541*3d8817e4Smiod@item fr_fix 542*3d8817e4SmiodFixed number of characters we know we're going to emit to the output file. May 543*3d8817e4Smiodbe zero. 544*3d8817e4Smiod 545*3d8817e4Smiod@item fr_var 546*3d8817e4SmiodVariable number of characters we may output, after the initial @code{fr_fix} 547*3d8817e4Smiodcharacters. May be zero. 548*3d8817e4Smiod 549*3d8817e4Smiod@item fr_offset 550*3d8817e4SmiodThe interpretation of this field is controlled by @code{fr_type}. Generally, 551*3d8817e4Smiodif @code{fr_var} is non-zero, this is a repeat count: the @code{fr_var} 552*3d8817e4Smiodcharacters are output @code{fr_offset} times. 553*3d8817e4Smiod 554*3d8817e4Smiod@item line 555*3d8817e4SmiodHolds line number info when an assembler listing was requested. 556*3d8817e4Smiod 557*3d8817e4Smiod@item fr_type 558*3d8817e4SmiodRelaxation state. This field indicates the interpretation of @code{fr_offset}, 559*3d8817e4Smiod@code{fr_symbol} and the variable-length tail of the frag, as well as the 560*3d8817e4Smiodtreatment it gets in various phases of processing. It does not affect the 561*3d8817e4Smiodinitial @code{fr_fix} characters; they are always supposed to be output 562*3d8817e4Smiodverbatim (fixups aside). See below for specific values this field can have. 563*3d8817e4Smiod 564*3d8817e4Smiod@item fr_subtype 565*3d8817e4SmiodRelaxation substate. If the macro @code{md_relax_frag} isn't defined, this is 566*3d8817e4Smiodassumed to be an index into @code{TC_GENERIC_RELAX_TABLE} for the generic 567*3d8817e4Smiodrelaxation code to process (@pxref{Relaxation}). If @code{md_relax_frag} is 568*3d8817e4Smioddefined, this field is available for any use by the CPU-specific code. 569*3d8817e4Smiod 570*3d8817e4Smiod@item fr_symbol 571*3d8817e4SmiodThis normally indicates the symbol to use when relaxing the frag according to 572*3d8817e4Smiod@code{fr_type}. 573*3d8817e4Smiod 574*3d8817e4Smiod@item fr_opcode 575*3d8817e4SmiodPoints to the lowest-addressed byte of the opcode, for use in relaxation. 576*3d8817e4Smiod 577*3d8817e4Smiod@item tc_frag_data 578*3d8817e4SmiodTarget specific fragment data of type TC_FRAG_TYPE. 579*3d8817e4SmiodOnly present if @code{TC_FRAG_TYPE} is defined. 580*3d8817e4Smiod 581*3d8817e4Smiod@item fr_file 582*3d8817e4Smiod@itemx fr_line 583*3d8817e4SmiodThe file and line where this frag was last modified. 584*3d8817e4Smiod 585*3d8817e4Smiod@item fr_literal 586*3d8817e4SmiodDeclared as a one-character array, this last field grows arbitrarily large to 587*3d8817e4Smiodhold the actual contents of the frag. 588*3d8817e4Smiod@end table 589*3d8817e4Smiod 590*3d8817e4SmiodThese are the possible relaxation states, provided in the enumeration type 591*3d8817e4Smiod@code{relax_stateT}, and the interpretations they represent for the other 592*3d8817e4Smiodfields: 593*3d8817e4Smiod 594*3d8817e4Smiod@table @code 595*3d8817e4Smiod@item rs_align 596*3d8817e4Smiod@itemx rs_align_code 597*3d8817e4SmiodThe start of the following frag should be aligned on some boundary. In this 598*3d8817e4Smiodfrag, @code{fr_offset} is the logarithm (base 2) of the alignment in bytes. 599*3d8817e4Smiod(For example, if alignment on an 8-byte boundary were desired, @code{fr_offset} 600*3d8817e4Smiodwould have a value of 3.) The variable characters indicate the fill pattern to 601*3d8817e4Smiodbe used. The @code{fr_subtype} field holds the maximum number of bytes to skip 602*3d8817e4Smiodwhen doing this alignment. If more bytes are needed, the alignment is not 603*3d8817e4Smioddone. An @code{fr_subtype} value of 0 means no maximum, which is the normal 604*3d8817e4Smiodcase. Target backends can use @code{rs_align_code} to handle certain types of 605*3d8817e4Smiodalignment differently. 606*3d8817e4Smiod 607*3d8817e4Smiod@item rs_broken_word 608*3d8817e4SmiodThis indicates that ``broken word'' processing should be done (@pxref{Broken 609*3d8817e4Smiodwords}). If broken word processing is not necessary on the target machine, 610*3d8817e4Smiodthis enumerator value will not be defined. 611*3d8817e4Smiod 612*3d8817e4Smiod@item rs_cfa 613*3d8817e4SmiodThis state is used to implement exception frame optimizations. The 614*3d8817e4Smiod@code{fr_symbol} is an expression symbol for the subtraction which may be 615*3d8817e4Smiodrelaxed. The @code{fr_opcode} field holds the frag for the preceding command 616*3d8817e4Smiodbyte. The @code{fr_offset} field holds the offset within that frag. The 617*3d8817e4Smiod@code{fr_subtype} field is used during relaxation to hold the current size of 618*3d8817e4Smiodthe frag. 619*3d8817e4Smiod 620*3d8817e4Smiod@item rs_fill 621*3d8817e4SmiodThe variable characters are to be repeated @code{fr_offset} times. If 622*3d8817e4Smiod@code{fr_offset} is 0, this frag has a length of @code{fr_fix}. Most frags 623*3d8817e4Smiodhave this type. 624*3d8817e4Smiod 625*3d8817e4Smiod@item rs_leb128 626*3d8817e4SmiodThis state is used to implement the DWARF ``little endian base 128'' 627*3d8817e4Smiodvariable length number format. The @code{fr_symbol} is always an expression 628*3d8817e4Smiodsymbol, as constant expressions are emitted directly. The @code{fr_offset} 629*3d8817e4Smiodfield is used during relaxation to hold the previous size of the number so 630*3d8817e4Smiodthat we can determine if the fragment changed size. 631*3d8817e4Smiod 632*3d8817e4Smiod@item rs_machine_dependent 633*3d8817e4SmiodDisplacement relaxation is to be done on this frag. The target is indicated by 634*3d8817e4Smiod@code{fr_symbol} and @code{fr_offset}, and @code{fr_subtype} indicates the 635*3d8817e4Smiodparticular machine-specific addressing mode desired. @xref{Relaxation}. 636*3d8817e4Smiod 637*3d8817e4Smiod@item rs_org 638*3d8817e4SmiodThe start of the following frag should be pushed back to some specific offset 639*3d8817e4Smiodwithin the section. (Some assemblers use the value as an absolute address; GAS 640*3d8817e4Smioddoes not handle final absolute addresses, but rather requires that the linker 641*3d8817e4Smiodset them.) The offset is given by @code{fr_symbol} and @code{fr_offset}; one 642*3d8817e4Smiodcharacter from the variable-length tail is used as the fill character. 643*3d8817e4Smiod@end table 644*3d8817e4Smiod 645*3d8817e4Smiod@cindex frchainS structure 646*3d8817e4SmiodA chain of frags is built up for each subsection. The data structure 647*3d8817e4Smioddescribing a chain is called a @code{frchainS}, and contains the following 648*3d8817e4Smiodfields: 649*3d8817e4Smiod 650*3d8817e4Smiod@table @code 651*3d8817e4Smiod@item frch_root 652*3d8817e4SmiodPoints to the first frag in the chain. May be NULL if there are no frags in 653*3d8817e4Smiodthis chain. 654*3d8817e4Smiod@item frch_last 655*3d8817e4SmiodPoints to the last frag in the chain, or NULL if there are none. 656*3d8817e4Smiod@item frch_next 657*3d8817e4SmiodNext in the list of @code{frchainS} structures. 658*3d8817e4Smiod@item frch_seg 659*3d8817e4SmiodIndicates the section this frag chain belongs to. 660*3d8817e4Smiod@item frch_subseg 661*3d8817e4SmiodSubsection (subsegment) number of this frag chain. 662*3d8817e4Smiod@item fix_root, fix_tail 663*3d8817e4SmiodPoint to first and last @code{fixS} structures associated with this subsection. 664*3d8817e4Smiod@item frch_obstack 665*3d8817e4SmiodNot currently used. Intended to be used for frag allocation for this 666*3d8817e4Smiodsubsection. This should reduce frag generation caused by switching sections. 667*3d8817e4Smiod@item frch_frag_now 668*3d8817e4SmiodThe current frag for this subsegment. 669*3d8817e4Smiod@end table 670*3d8817e4Smiod 671*3d8817e4SmiodA @code{frchainS} corresponds to a subsection; each section has a list of 672*3d8817e4Smiod@code{frchainS} records associated with it. In most cases, only one subsection 673*3d8817e4Smiodof each section is used, so the list will only be one element long, but any 674*3d8817e4Smiodprocessing of frag chains should be prepared to deal with multiple chains per 675*3d8817e4Smiodsection. 676*3d8817e4Smiod 677*3d8817e4SmiodAfter the input files have been completely processed, and no more frags are to 678*3d8817e4Smiodbe generated, the frag chains are joined into one per section for further 679*3d8817e4Smiodprocessing. After this point, it is safe to operate on one chain per section. 680*3d8817e4Smiod 681*3d8817e4SmiodThe assembler always has a current frag, named @code{frag_now}. More space is 682*3d8817e4Smiodallocated for the current frag using the @code{frag_more} function; this 683*3d8817e4Smiodreturns a pointer to the amount of requested space. The function 684*3d8817e4Smiod@code{frag_room} says by how much the current frag can be extended. 685*3d8817e4SmiodRelaxing is done using variant frags allocated by @code{frag_var} 686*3d8817e4Smiodor @code{frag_variant} (@pxref{Relaxation}). 687*3d8817e4Smiod 688*3d8817e4Smiod@node GAS processing 689*3d8817e4Smiod@section What GAS does when it runs 690*3d8817e4Smiod@cindex internals, overview 691*3d8817e4Smiod 692*3d8817e4SmiodThis is a quick look at what an assembler run looks like. 693*3d8817e4Smiod 694*3d8817e4Smiod@itemize @bullet 695*3d8817e4Smiod@item 696*3d8817e4SmiodThe assembler initializes itself by calling various init routines. 697*3d8817e4Smiod 698*3d8817e4Smiod@item 699*3d8817e4SmiodFor each source file, the @code{read_a_source_file} function reads in the file 700*3d8817e4Smiodand parses it. The global variable @code{input_line_pointer} points to the 701*3d8817e4Smiodcurrent text; it is guaranteed to be correct up to the end of the line, but not 702*3d8817e4Smiodfarther. 703*3d8817e4Smiod 704*3d8817e4Smiod@item 705*3d8817e4SmiodFor each line, the assembler passes labels to the @code{colon} function, and 706*3d8817e4Smiodisolates the first word. If it looks like a pseudo-op, the word is looked up 707*3d8817e4Smiodin the pseudo-op hash table @code{po_hash} and dispatched to a pseudo-op 708*3d8817e4Smiodroutine. Otherwise, the target dependent @code{md_assemble} routine is called 709*3d8817e4Smiodto parse the instruction. 710*3d8817e4Smiod 711*3d8817e4Smiod@item 712*3d8817e4SmiodWhen pseudo-ops or instructions output data, they add it to a frag, calling 713*3d8817e4Smiod@code{frag_more} to get space to store it in. 714*3d8817e4Smiod 715*3d8817e4Smiod@item 716*3d8817e4SmiodPseudo-ops and instructions can also output fixups created by @code{fix_new} or 717*3d8817e4Smiod@code{fix_new_exp}. 718*3d8817e4Smiod 719*3d8817e4Smiod@item 720*3d8817e4SmiodFor certain targets, instructions can create variant frags which are used to 721*3d8817e4Smiodstore relaxation information (@pxref{Relaxation}). 722*3d8817e4Smiod 723*3d8817e4Smiod@item 724*3d8817e4SmiodWhen the input file is finished, the @code{write_object_file} routine is 725*3d8817e4Smiodcalled. It assigns addresses to all the frags (@code{relax_segment}), resolves 726*3d8817e4Smiodall the fixups (@code{fixup_segment}), resolves all the symbol values (using 727*3d8817e4Smiod@code{resolve_symbol_value}), and finally writes out the file. 728*3d8817e4Smiod@end itemize 729*3d8817e4Smiod 730*3d8817e4Smiod@node Porting GAS 731*3d8817e4Smiod@section Porting GAS 732*3d8817e4Smiod@cindex porting 733*3d8817e4Smiod 734*3d8817e4SmiodEach GAS target specifies two main things: the CPU file and the object format 735*3d8817e4Smiodfile. Two main switches in the @file{configure.in} file handle this. The 736*3d8817e4Smiodfirst switches on CPU type to set the shell variable @code{cpu_type}. The 737*3d8817e4Smiodsecond switches on the entire target to set the shell variable @code{fmt}. 738*3d8817e4Smiod 739*3d8817e4SmiodThe configure script uses the value of @code{cpu_type} to select two files in 740*3d8817e4Smiodthe @file{config} directory: @file{tc-@var{CPU}.c} and @file{tc-@var{CPU}.h}. 741*3d8817e4SmiodThe configuration process will create a file named @file{targ-cpu.h} in the 742*3d8817e4Smiodbuild directory which includes @file{tc-@var{CPU}.h}. 743*3d8817e4Smiod 744*3d8817e4SmiodThe configure script also uses the value of @code{fmt} to select two files: 745*3d8817e4Smiod@file{obj-@var{fmt}.c} and @file{obj-@var{fmt}.h}. The configuration process 746*3d8817e4Smiodwill create a file named @file{obj-format.h} in the build directory which 747*3d8817e4Smiodincludes @file{obj-@var{fmt}.h}. 748*3d8817e4Smiod 749*3d8817e4SmiodYou can also set the emulation in the configure script by setting the @code{em} 750*3d8817e4Smiodvariable. Normally the default value of @samp{generic} is fine. The 751*3d8817e4Smiodconfiguration process will create a file named @file{targ-env.h} in the build 752*3d8817e4Smioddirectory which includes @file{te-@var{em}.h}. 753*3d8817e4Smiod 754*3d8817e4SmiodThere is a special case for COFF. For historical reason, the GNU COFF 755*3d8817e4Smiodassembler doesn't follow the documented behavior on certain debug symbols for 756*3d8817e4Smiodthe compatibility with other COFF assemblers. A port can define 757*3d8817e4Smiod@code{STRICTCOFF} in the configure script to make the GNU COFF assembler 758*3d8817e4Smiodto follow the documented behavior. 759*3d8817e4Smiod 760*3d8817e4SmiodPorting GAS to a new CPU requires writing the @file{tc-@var{CPU}} files. 761*3d8817e4SmiodPorting GAS to a new object file format requires writing the 762*3d8817e4Smiod@file{obj-@var{fmt}} files. There is sometimes some interaction between these 763*3d8817e4Smiodtwo files, but it is normally minimal. 764*3d8817e4Smiod 765*3d8817e4SmiodThe best approach is, of course, to copy existing files. The documentation 766*3d8817e4Smiodbelow assumes that you are looking at existing files to see usage details. 767*3d8817e4Smiod 768*3d8817e4SmiodThese interfaces have grown over time, and have never been carefully thought 769*3d8817e4Smiodout or designed. Nothing about the interfaces described here is cast in stone. 770*3d8817e4SmiodIt is possible that they will change from one version of the assembler to the 771*3d8817e4Smiodnext. Also, new macros are added all the time as they are needed. 772*3d8817e4Smiod 773*3d8817e4Smiod@menu 774*3d8817e4Smiod* CPU backend:: Writing a CPU backend 775*3d8817e4Smiod* Object format backend:: Writing an object format backend 776*3d8817e4Smiod* Emulations:: Writing emulation files 777*3d8817e4Smiod@end menu 778*3d8817e4Smiod 779*3d8817e4Smiod@node CPU backend 780*3d8817e4Smiod@subsection Writing a CPU backend 781*3d8817e4Smiod@cindex CPU backend 782*3d8817e4Smiod@cindex @file{tc-@var{CPU}} 783*3d8817e4Smiod 784*3d8817e4SmiodThe CPU backend files are the heart of the assembler. They are the only parts 785*3d8817e4Smiodof the assembler which actually know anything about the instruction set of the 786*3d8817e4Smiodprocessor. 787*3d8817e4Smiod 788*3d8817e4SmiodYou must define a reasonably small list of macros and functions in the CPU 789*3d8817e4Smiodbackend files. You may define a large number of additional macros in the CPU 790*3d8817e4Smiodbackend files, not all of which are documented here. You must, of course, 791*3d8817e4Smioddefine macros in the @file{.h} file, which is included by every assembler 792*3d8817e4Smiodsource file. You may define the functions as macros in the @file{.h} file, or 793*3d8817e4Smiodas functions in the @file{.c} file. 794*3d8817e4Smiod 795*3d8817e4Smiod@table @code 796*3d8817e4Smiod@item TC_@var{CPU} 797*3d8817e4Smiod@cindex TC_@var{CPU} 798*3d8817e4SmiodBy convention, you should define this macro in the @file{.h} file. For 799*3d8817e4Smiodexample, @file{tc-m68k.h} defines @code{TC_M68K}. You might have to use this 800*3d8817e4Smiodif it is necessary to add CPU specific code to the object format file. 801*3d8817e4Smiod 802*3d8817e4Smiod@item TARGET_FORMAT 803*3d8817e4SmiodThis macro is the BFD target name to use when creating the output file. This 804*3d8817e4Smiodwill normally depend upon the @code{OBJ_@var{FMT}} macro. 805*3d8817e4Smiod 806*3d8817e4Smiod@item TARGET_ARCH 807*3d8817e4SmiodThis macro is the BFD architecture to pass to @code{bfd_set_arch_mach}. 808*3d8817e4Smiod 809*3d8817e4Smiod@item TARGET_MACH 810*3d8817e4SmiodThis macro is the BFD machine number to pass to @code{bfd_set_arch_mach}. If 811*3d8817e4Smiodit is not defined, GAS will use 0. 812*3d8817e4Smiod 813*3d8817e4Smiod@item TARGET_BYTES_BIG_ENDIAN 814*3d8817e4SmiodYou should define this macro to be non-zero if the target is big endian, and 815*3d8817e4Smiodzero if the target is little endian. 816*3d8817e4Smiod 817*3d8817e4Smiod@item md_shortopts 818*3d8817e4Smiod@itemx md_longopts 819*3d8817e4Smiod@itemx md_longopts_size 820*3d8817e4Smiod@itemx md_parse_option 821*3d8817e4Smiod@itemx md_show_usage 822*3d8817e4Smiod@itemx md_after_parse_args 823*3d8817e4Smiod@cindex md_shortopts 824*3d8817e4Smiod@cindex md_longopts 825*3d8817e4Smiod@cindex md_longopts_size 826*3d8817e4Smiod@cindex md_parse_option 827*3d8817e4Smiod@cindex md_show_usage 828*3d8817e4Smiod@cindex md_after_parse_args 829*3d8817e4SmiodGAS uses these variables and functions during option processing. 830*3d8817e4Smiod@code{md_shortopts} is a @code{const char *} which GAS adds to the machine 831*3d8817e4Smiodindependent string passed to @code{getopt}. @code{md_longopts} is a 832*3d8817e4Smiod@code{struct option []} which GAS adds to the machine independent long options 833*3d8817e4Smiodpassed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in 834*3d8817e4Smiod@file{as.h}, as the start of a set of long option indices, if necessary. 835*3d8817e4Smiod@code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}. 836*3d8817e4Smiod 837*3d8817e4SmiodGAS will call @code{md_parse_option} whenever @code{getopt} returns an 838*3d8817e4Smiodunrecognized code, presumably indicating a special code value which appears in 839*3d8817e4Smiod@code{md_longopts}. This function should return non-zero if it handled the 840*3d8817e4Smiodoption and zero otherwise. There is no need to print a message about an option 841*3d8817e4Smiodnot being recognised. This will be handled by the generic code. 842*3d8817e4Smiod 843*3d8817e4SmiodGAS will call @code{md_show_usage} when a usage message is printed; it should 844*3d8817e4Smiodprint a description of the machine specific options. @code{md_after_pase_args}, 845*3d8817e4Smiodif defined, is called after all options are processed, to let the backend 846*3d8817e4Smiodoverride settings done by the generic option parsing. 847*3d8817e4Smiod 848*3d8817e4Smiod@item md_begin 849*3d8817e4Smiod@cindex md_begin 850*3d8817e4SmiodGAS will call this function at the start of the assembly, after the command 851*3d8817e4Smiodline arguments have been parsed and all the machine independent initializations 852*3d8817e4Smiodhave been completed. 853*3d8817e4Smiod 854*3d8817e4Smiod@item md_cleanup 855*3d8817e4Smiod@cindex md_cleanup 856*3d8817e4SmiodIf you define this macro, GAS will call it at the end of each input file. 857*3d8817e4Smiod 858*3d8817e4Smiod@item md_assemble 859*3d8817e4Smiod@cindex md_assemble 860*3d8817e4SmiodGAS will call this function for each input line which does not contain a 861*3d8817e4Smiodpseudo-op. The argument is a null terminated string. The function should 862*3d8817e4Smiodassemble the string as an instruction with operands. Normally 863*3d8817e4Smiod@code{md_assemble} will do this by calling @code{frag_more} and writing out 864*3d8817e4Smiodsome bytes (@pxref{Frags}). @code{md_assemble} will call @code{fix_new} to 865*3d8817e4Smiodcreate fixups as needed (@pxref{Fixups}). Targets which need to do special 866*3d8817e4Smiodpurpose relaxation will call @code{frag_var}. 867*3d8817e4Smiod 868*3d8817e4Smiod@item md_pseudo_table 869*3d8817e4Smiod@cindex md_pseudo_table 870*3d8817e4SmiodThis is a const array of type @code{pseudo_typeS}. It is a mapping from 871*3d8817e4Smiodpseudo-op names to functions. You should use this table to implement 872*3d8817e4Smiodpseudo-ops which are specific to the CPU. 873*3d8817e4Smiod 874*3d8817e4Smiod@item tc_conditional_pseudoop 875*3d8817e4Smiod@cindex tc_conditional_pseudoop 876*3d8817e4SmiodIf this macro is defined, GAS will call it with a @code{pseudo_typeS} argument. 877*3d8817e4SmiodIt should return non-zero if the pseudo-op is a conditional which controls 878*3d8817e4Smiodwhether code is assembled, such as @samp{.if}. GAS knows about the normal 879*3d8817e4Smiodconditional pseudo-ops, and you should normally not have to define this macro. 880*3d8817e4Smiod 881*3d8817e4Smiod@item comment_chars 882*3d8817e4Smiod@cindex comment_chars 883*3d8817e4SmiodThis is a null terminated @code{const char} array of characters which start a 884*3d8817e4Smiodcomment. 885*3d8817e4Smiod 886*3d8817e4Smiod@item tc_comment_chars 887*3d8817e4Smiod@cindex tc_comment_chars 888*3d8817e4SmiodIf this macro is defined, GAS will use it instead of @code{comment_chars}. 889*3d8817e4Smiod 890*3d8817e4Smiod@item tc_symbol_chars 891*3d8817e4Smiod@cindex tc_symbol_chars 892*3d8817e4SmiodIf this macro is defined, it is a pointer to a null terminated list of 893*3d8817e4Smiodcharacters which may appear in an operand. GAS already assumes that all 894*3d8817e4Smiodalphanumberic characters, and @samp{$}, @samp{.}, and @samp{_} may appear in an 895*3d8817e4Smiodoperand (see @samp{symbol_chars} in @file{app.c}). This macro may be defined 896*3d8817e4Smiodto treat additional characters as appearing in an operand. This affects the 897*3d8817e4Smiodway in which GAS removes whitespace before passing the string to 898*3d8817e4Smiod@samp{md_assemble}. 899*3d8817e4Smiod 900*3d8817e4Smiod@item line_comment_chars 901*3d8817e4Smiod@cindex line_comment_chars 902*3d8817e4SmiodThis is a null terminated @code{const char} array of characters which start a 903*3d8817e4Smiodcomment when they appear at the start of a line. 904*3d8817e4Smiod 905*3d8817e4Smiod@item line_separator_chars 906*3d8817e4Smiod@cindex line_separator_chars 907*3d8817e4SmiodThis is a null terminated @code{const char} array of characters which separate 908*3d8817e4Smiodlines (null and newline are such characters by default, and need not be 909*3d8817e4Smiodlisted in this array). Note that line_separator_chars do not separate lines 910*3d8817e4Smiodif found in a comment, such as after a character in line_comment_chars or 911*3d8817e4Smiodcomment_chars. 912*3d8817e4Smiod 913*3d8817e4Smiod@item EXP_CHARS 914*3d8817e4Smiod@cindex EXP_CHARS 915*3d8817e4SmiodThis is a null terminated @code{const char} array of characters which may be 916*3d8817e4Smiodused as the exponent character in a floating point number. This is normally 917*3d8817e4Smiod@code{"eE"}. 918*3d8817e4Smiod 919*3d8817e4Smiod@item FLT_CHARS 920*3d8817e4Smiod@cindex FLT_CHARS 921*3d8817e4SmiodThis is a null terminated @code{const char} array of characters which may be 922*3d8817e4Smiodused to indicate a floating point constant. A zero followed by one of these 923*3d8817e4Smiodcharacters is assumed to be followed by a floating point number; thus they 924*3d8817e4Smiodoperate the way that @code{0x} is used to indicate a hexadecimal constant. 925*3d8817e4SmiodUsually this includes @samp{r} and @samp{f}. 926*3d8817e4Smiod 927*3d8817e4Smiod@item LEX_AT 928*3d8817e4Smiod@cindex LEX_AT 929*3d8817e4SmiodYou may define this macro to the lexical type of the @kbd{@@} character. The 930*3d8817e4Smioddefault is zero. 931*3d8817e4Smiod 932*3d8817e4SmiodLexical types are a combination of @code{LEX_NAME} and @code{LEX_BEGIN_NAME}, 933*3d8817e4Smiodboth defined in @file{read.h}. @code{LEX_NAME} indicates that the character 934*3d8817e4Smiodmay appear in a name. @code{LEX_BEGIN_NAME} indicates that the character may 935*3d8817e4Smiodappear at the beginning of a name. 936*3d8817e4Smiod 937*3d8817e4Smiod@item LEX_BR 938*3d8817e4Smiod@cindex LEX_BR 939*3d8817e4SmiodYou may define this macro to the lexical type of the brace characters @kbd{@{}, 940*3d8817e4Smiod@kbd{@}}, @kbd{[}, and @kbd{]}. The default value is zero. 941*3d8817e4Smiod 942*3d8817e4Smiod@item LEX_PCT 943*3d8817e4Smiod@cindex LEX_PCT 944*3d8817e4SmiodYou may define this macro to the lexical type of the @kbd{%} character. The 945*3d8817e4Smioddefault value is zero. 946*3d8817e4Smiod 947*3d8817e4Smiod@item LEX_QM 948*3d8817e4Smiod@cindex LEX_QM 949*3d8817e4SmiodYou may define this macro to the lexical type of the @kbd{?} character. The 950*3d8817e4Smioddefault value it zero. 951*3d8817e4Smiod 952*3d8817e4Smiod@item LEX_DOLLAR 953*3d8817e4Smiod@cindex LEX_DOLLAR 954*3d8817e4SmiodYou may define this macro to the lexical type of the @kbd{$} character. The 955*3d8817e4Smioddefault value is @code{LEX_NAME | LEX_BEGIN_NAME}. 956*3d8817e4Smiod 957*3d8817e4Smiod@item NUMBERS_WITH_SUFFIX 958*3d8817e4Smiod@cindex NUMBERS_WITH_SUFFIX 959*3d8817e4SmiodWhen this macro is defined to be non-zero, the parser allows the radix of a 960*3d8817e4Smiodconstant to be indicated with a suffix. Valid suffixes are binary (B), 961*3d8817e4Smiodoctal (Q), and hexadecimal (H). Case is not significant. 962*3d8817e4Smiod 963*3d8817e4Smiod@item SINGLE_QUOTE_STRINGS 964*3d8817e4Smiod@cindex SINGLE_QUOTE_STRINGS 965*3d8817e4SmiodIf you define this macro, GAS will treat single quotes as string delimiters. 966*3d8817e4SmiodNormally only double quotes are accepted as string delimiters. 967*3d8817e4Smiod 968*3d8817e4Smiod@item NO_STRING_ESCAPES 969*3d8817e4Smiod@cindex NO_STRING_ESCAPES 970*3d8817e4SmiodIf you define this macro, GAS will not permit escape sequences in a string. 971*3d8817e4Smiod 972*3d8817e4Smiod@item ONLY_STANDARD_ESCAPES 973*3d8817e4Smiod@cindex ONLY_STANDARD_ESCAPES 974*3d8817e4SmiodIf you define this macro, GAS will warn about the use of nonstandard escape 975*3d8817e4Smiodsequences in a string. 976*3d8817e4Smiod 977*3d8817e4Smiod@item md_start_line_hook 978*3d8817e4Smiod@cindex md_start_line_hook 979*3d8817e4SmiodIf you define this macro, GAS will call it at the start of each line. 980*3d8817e4Smiod 981*3d8817e4Smiod@item LABELS_WITHOUT_COLONS 982*3d8817e4Smiod@cindex LABELS_WITHOUT_COLONS 983*3d8817e4SmiodIf you define this macro, GAS will assume that any text at the start of a line 984*3d8817e4Smiodis a label, even if it does not have a colon. 985*3d8817e4Smiod 986*3d8817e4Smiod@item TC_START_LABEL 987*3d8817e4Smiod@itemx TC_START_LABEL_WITHOUT_COLON 988*3d8817e4Smiod@cindex TC_START_LABEL 989*3d8817e4SmiodYou may define this macro to control what GAS considers to be a label. The 990*3d8817e4Smioddefault definition is to accept any name followed by a colon character. 991*3d8817e4Smiod 992*3d8817e4Smiod@item TC_START_LABEL_WITHOUT_COLON 993*3d8817e4Smiod@cindex TC_START_LABEL_WITHOUT_COLON 994*3d8817e4SmiodSame as TC_START_LABEL, but should be used instead of TC_START_LABEL when 995*3d8817e4SmiodLABELS_WITHOUT_COLONS is defined. 996*3d8817e4Smiod 997*3d8817e4Smiod@item TC_FAKE_LABEL 998*3d8817e4Smiod@cindex TC_FAKE_LABEL 999*3d8817e4SmiodYou may define this macro to control what GAS considers to be a fake 1000*3d8817e4Smiodlabel. The default fake label is FAKE_LABEL_NAME. 1001*3d8817e4Smiod 1002*3d8817e4Smiod@item NO_PSEUDO_DOT 1003*3d8817e4Smiod@cindex NO_PSEUDO_DOT 1004*3d8817e4SmiodIf you define this macro, GAS will not require pseudo-ops to start with a 1005*3d8817e4Smiod@kbd{.} character. 1006*3d8817e4Smiod 1007*3d8817e4Smiod@item TC_EQUAL_IN_INSN 1008*3d8817e4Smiod@cindex TC_EQUAL_IN_INSN 1009*3d8817e4SmiodIf you define this macro, it should return nonzero if the instruction is 1010*3d8817e4Smiodpermitted to contain an @kbd{=} character. GAS will call it with two 1011*3d8817e4Smiodarguments, the character before the @kbd{=} character, and the value of 1012*3d8817e4Smiodthe string preceding the equal sign. GAS uses this macro to decide if a 1013*3d8817e4Smiod@kbd{=} is an assignment or an instruction. 1014*3d8817e4Smiod 1015*3d8817e4Smiod@item TC_EOL_IN_INSN 1016*3d8817e4Smiod@cindex TC_EOL_IN_INSN 1017*3d8817e4SmiodIf you define this macro, it should return nonzero if the current input line 1018*3d8817e4Smiodpointer should be treated as the end of a line. 1019*3d8817e4Smiod 1020*3d8817e4Smiod@item TC_CASE_SENSITIVE 1021*3d8817e4Smiod@cindex TC_CASE_SENSITIVE 1022*3d8817e4SmiodDefine this macro if instruction mnemonics and pseudos are case sensitive. 1023*3d8817e4SmiodThe default is to have it undefined giving case insensitive names. 1024*3d8817e4Smiod 1025*3d8817e4Smiod@item md_parse_name 1026*3d8817e4Smiod@cindex md_parse_name 1027*3d8817e4SmiodIf this macro is defined, GAS will call it for any symbol found in an 1028*3d8817e4Smiodexpression. You can define this to handle special symbols in a special way. 1029*3d8817e4SmiodIf a symbol always has a certain value, you should normally enter it in the 1030*3d8817e4Smiodsymbol table, perhaps using @code{reg_section}. 1031*3d8817e4Smiod 1032*3d8817e4Smiod@item md_undefined_symbol 1033*3d8817e4Smiod@cindex md_undefined_symbol 1034*3d8817e4SmiodGAS will call this function when a symbol table lookup fails, before it 1035*3d8817e4Smiodcreates a new symbol. Typically this would be used to supply symbols whose 1036*3d8817e4Smiodname or value changes dynamically, possibly in a context sensitive way. 1037*3d8817e4SmiodPredefined symbols with fixed values, such as register names or condition 1038*3d8817e4Smiodcodes, are typically entered directly into the symbol table when @code{md_begin} 1039*3d8817e4Smiodis called. One argument is passed, a @code{char *} for the symbol. 1040*3d8817e4Smiod 1041*3d8817e4Smiod@item md_operand 1042*3d8817e4Smiod@cindex md_operand 1043*3d8817e4SmiodGAS will call this function with one argument, an @code{expressionS} 1044*3d8817e4Smiodpointer, for any expression that can not be recognized. When the function 1045*3d8817e4Smiodis called, @code{input_line_pointer} will point to the start of the 1046*3d8817e4Smiodexpression. 1047*3d8817e4Smiod 1048*3d8817e4Smiod@item tc_unrecognized_line 1049*3d8817e4Smiod@cindex tc_unrecognized_line 1050*3d8817e4SmiodIf you define this macro, GAS will call it when it finds a line that it can not 1051*3d8817e4Smiodparse. 1052*3d8817e4Smiod 1053*3d8817e4Smiod@item md_do_align 1054*3d8817e4Smiod@cindex md_do_align 1055*3d8817e4SmiodYou may define this macro to handle an alignment directive. GAS will call it 1056*3d8817e4Smiodwhen the directive is seen in the input file. For example, the i386 backend 1057*3d8817e4Smioduses this to generate efficient nop instructions of varying lengths, depending 1058*3d8817e4Smiodupon the number of bytes that the alignment will skip. 1059*3d8817e4Smiod 1060*3d8817e4Smiod@item HANDLE_ALIGN 1061*3d8817e4Smiod@cindex HANDLE_ALIGN 1062*3d8817e4SmiodYou may define this macro to do special handling for an alignment directive. 1063*3d8817e4SmiodGAS will call it at the end of the assembly. 1064*3d8817e4Smiod 1065*3d8817e4Smiod@item TC_IMPLICIT_LCOMM_ALIGNMENT (@var{size}, @var{p2var}) 1066*3d8817e4Smiod@cindex TC_IMPLICIT_LCOMM_ALIGNMENT 1067*3d8817e4SmiodAn @code{.lcomm} directive with no explicit alignment parameter will use this 1068*3d8817e4Smiodmacro to set @var{p2var} to the alignment that a request for @var{size} bytes 1069*3d8817e4Smiodwill have. The alignment is expressed as a power of two. If no alignment 1070*3d8817e4Smiodshould take place, the macro definition should do nothing. Some targets define 1071*3d8817e4Smioda @code{.bss} directive that is also affected by this macro. The default 1072*3d8817e4Smioddefinition will set @var{p2var} to the truncated power of two of sizes up to 1073*3d8817e4Smiodeight bytes. 1074*3d8817e4Smiod 1075*3d8817e4Smiod@item md_flush_pending_output 1076*3d8817e4Smiod@cindex md_flush_pending_output 1077*3d8817e4SmiodIf you define this macro, GAS will call it each time it skips any space because of a 1078*3d8817e4Smiodspace filling or alignment or data allocation pseudo-op. 1079*3d8817e4Smiod 1080*3d8817e4Smiod@item TC_PARSE_CONS_EXPRESSION 1081*3d8817e4Smiod@cindex TC_PARSE_CONS_EXPRESSION 1082*3d8817e4SmiodYou may define this macro to parse an expression used in a data allocation 1083*3d8817e4Smiodpseudo-op such as @code{.word}. You can use this to recognize relocation 1084*3d8817e4Smioddirectives that may appear in such directives. 1085*3d8817e4Smiod 1086*3d8817e4Smiod@item BITFIELD_CONS_EXPRESSION 1087*3d8817e4Smiod@cindex BITFIELD_CONS_EXPRESSION 1088*3d8817e4SmiodIf you define this macro, GAS will recognize bitfield instructions in data 1089*3d8817e4Smiodallocation pseudo-ops, as used on the i960. 1090*3d8817e4Smiod 1091*3d8817e4Smiod@item REPEAT_CONS_EXPRESSION 1092*3d8817e4Smiod@cindex REPEAT_CONS_EXPRESSION 1093*3d8817e4SmiodIf you define this macro, GAS will recognize repeat counts in data allocation 1094*3d8817e4Smiodpseudo-ops, as used on the MIPS. 1095*3d8817e4Smiod 1096*3d8817e4Smiod@item md_cons_align 1097*3d8817e4Smiod@cindex md_cons_align 1098*3d8817e4SmiodYou may define this macro to do any special alignment before a data allocation 1099*3d8817e4Smiodpseudo-op. 1100*3d8817e4Smiod 1101*3d8817e4Smiod@item TC_CONS_FIX_NEW 1102*3d8817e4Smiod@cindex TC_CONS_FIX_NEW 1103*3d8817e4SmiodYou may define this macro to generate a fixup for a data allocation pseudo-op. 1104*3d8817e4Smiod 1105*3d8817e4Smiod@item TC_ADDRESS_BYTES 1106*3d8817e4Smiod@cindex TC_ADDRESS_BYTES 1107*3d8817e4SmiodDefine this macro to specify the number of bytes used to store an address. 1108*3d8817e4SmiodUsed to implement @code{dc.a}. The target must have a reloc for this size. 1109*3d8817e4Smiod 1110*3d8817e4Smiod@item TC_INIT_FIX_DATA (@var{fixp}) 1111*3d8817e4Smiod@cindex TC_INIT_FIX_DATA 1112*3d8817e4SmiodA C statement to initialize the target specific fields of fixup @var{fixp}. 1113*3d8817e4SmiodThese fields are defined with the @code{TC_FIX_TYPE} macro. 1114*3d8817e4Smiod 1115*3d8817e4Smiod@item TC_FIX_DATA_PRINT (@var{stream}, @var{fixp}) 1116*3d8817e4Smiod@cindex TC_FIX_DATA_PRINT 1117*3d8817e4SmiodA C statement to output target specific debugging information for 1118*3d8817e4Smiodfixup @var{fixp} to @var{stream}. This macro is called by @code{print_fixup}. 1119*3d8817e4Smiod 1120*3d8817e4Smiod@item TC_FRAG_INIT (@var{fragp}) 1121*3d8817e4Smiod@cindex TC_FRAG_INIT 1122*3d8817e4SmiodA C statement to initialize the target specific fields of frag @var{fragp}. 1123*3d8817e4SmiodThese fields are defined with the @code{TC_FRAG_TYPE} macro. 1124*3d8817e4Smiod 1125*3d8817e4Smiod@item md_number_to_chars 1126*3d8817e4Smiod@cindex md_number_to_chars 1127*3d8817e4SmiodThis should just call either @code{number_to_chars_bigendian} or 1128*3d8817e4Smiod@code{number_to_chars_littleendian}, whichever is appropriate. On targets like 1129*3d8817e4Smiodthe MIPS which support options to change the endianness, which function to call 1130*3d8817e4Smiodis a runtime decision. On other targets, @code{md_number_to_chars} can be a 1131*3d8817e4Smiodsimple macro. 1132*3d8817e4Smiod 1133*3d8817e4Smiod@item md_atof (@var{type},@var{litP},@var{sizeP}) 1134*3d8817e4Smiod@cindex md_atof 1135*3d8817e4SmiodThis function is called to convert an ASCII string into a floating point value 1136*3d8817e4Smiodin format used by the CPU. It takes three arguments. The first is @var{type} 1137*3d8817e4Smiodwhich is a byte describing the type of floating point number to be created. 1138*3d8817e4SmiodPossible values are @var{'f'} or @var{'s'} for single precision, @var{'d'} or 1139*3d8817e4Smiod@var{'r'} for double precision and @var{'x'} or @var{'p'} for extended 1140*3d8817e4Smiodprecision. Either lower or upper case versions of these letters can be used. 1141*3d8817e4Smiod 1142*3d8817e4SmiodThe second parameter is @var{litP} which is a pointer to a byte array where the 1143*3d8817e4Smiodconverted value should be stored. The third argument is @var{sizeP}, which is 1144*3d8817e4Smioda pointer to a integer that should be filled in with the number of 1145*3d8817e4Smiod@var{LITTLENUM}s emitted into the byte array. (@var{LITTLENUM} is defined in 1146*3d8817e4Smiodgas/bignum.h). The function should return NULL upon success or an error string 1147*3d8817e4Smiodupon failure. 1148*3d8817e4Smiod 1149*3d8817e4Smiod@item TC_LARGEST_EXPONENT_IS_NORMAL 1150*3d8817e4Smiod@cindex TC_LARGEST_EXPONENT_IS_NORMAL (@var{precision}) 1151*3d8817e4SmiodThis macro is used only by @file{atof-ieee.c}. It should evaluate to true 1152*3d8817e4Smiodif floats of the given precision use the largest exponent for normal numbers 1153*3d8817e4Smiodinstead of NaNs and infinities. @var{precision} is @samp{F_PRECISION} for 1154*3d8817e4Smiodsingle precision, @samp{D_PRECISION} for double precision, or 1155*3d8817e4Smiod@samp{X_PRECISION} for extended double precision. 1156*3d8817e4Smiod 1157*3d8817e4SmiodThe macro has a default definition which returns 0 for all cases. 1158*3d8817e4Smiod 1159*3d8817e4Smiod@item WORKING_DOT_WORD 1160*3d8817e4Smiod@itemx md_short_jump_size 1161*3d8817e4Smiod@itemx md_long_jump_size 1162*3d8817e4Smiod@itemx md_create_short_jump 1163*3d8817e4Smiod@itemx md_create_long_jump 1164*3d8817e4Smiod@itemx TC_CHECK_ADJUSTED_BROKEN_DOT_WORD 1165*3d8817e4Smiod@cindex WORKING_DOT_WORD 1166*3d8817e4Smiod@cindex md_short_jump_size 1167*3d8817e4Smiod@cindex md_long_jump_size 1168*3d8817e4Smiod@cindex md_create_short_jump 1169*3d8817e4Smiod@cindex md_create_long_jump 1170*3d8817e4Smiod@cindex TC_CHECK_ADJUSTED_BROKEN_DOT_WORD 1171*3d8817e4SmiodIf @code{WORKING_DOT_WORD} is defined, GAS will not do broken word processing 1172*3d8817e4Smiod(@pxref{Broken words}). Otherwise, you should set @code{md_short_jump_size} to 1173*3d8817e4Smiodthe size of a short jump (a jump that is just long enough to jump around a 1174*3d8817e4Smiodnumber of long jumps) and @code{md_long_jump_size} to the size of a long jump 1175*3d8817e4Smiod(a jump that can go anywhere in the function). You should define 1176*3d8817e4Smiod@code{md_create_short_jump} to create a short jump around a number of long 1177*3d8817e4Smiodjumps, and define @code{md_create_long_jump} to create a long jump. 1178*3d8817e4SmiodIf defined, the macro TC_CHECK_ADJUSTED_BROKEN_DOT_WORD will be called for each 1179*3d8817e4Smiodadjusted word just before the word is output. The macro takes two arguments, 1180*3d8817e4Smiodan @code{addressT} with the adjusted word and a pointer to the current 1181*3d8817e4Smiod@code{struct broken_word}. 1182*3d8817e4Smiod 1183*3d8817e4Smiod@item md_estimate_size_before_relax 1184*3d8817e4Smiod@cindex md_estimate_size_before_relax 1185*3d8817e4SmiodThis function returns an estimate of the size of a @code{rs_machine_dependent} 1186*3d8817e4Smiodfrag before any relaxing is done. It may also create any necessary 1187*3d8817e4Smiodrelocations. 1188*3d8817e4Smiod 1189*3d8817e4Smiod@item md_relax_frag 1190*3d8817e4Smiod@cindex md_relax_frag 1191*3d8817e4SmiodThis macro may be defined to relax a frag. GAS will call this with the 1192*3d8817e4Smiodsegment, the frag, and the change in size of all previous frags; 1193*3d8817e4Smiod@code{md_relax_frag} should return the change in size of the frag. 1194*3d8817e4Smiod@xref{Relaxation}. 1195*3d8817e4Smiod 1196*3d8817e4Smiod@item TC_GENERIC_RELAX_TABLE 1197*3d8817e4Smiod@cindex TC_GENERIC_RELAX_TABLE 1198*3d8817e4SmiodIf you do not define @code{md_relax_frag}, you may define 1199*3d8817e4Smiod@code{TC_GENERIC_RELAX_TABLE} as a table of @code{relax_typeS} structures. The 1200*3d8817e4Smiodmachine independent code knows how to use such a table to relax PC relative 1201*3d8817e4Smiodreferences. See @file{tc-m68k.c} for an example. @xref{Relaxation}. 1202*3d8817e4Smiod 1203*3d8817e4Smiod@item md_prepare_relax_scan 1204*3d8817e4Smiod@cindex md_prepare_relax_scan 1205*3d8817e4SmiodIf defined, it is a C statement that is invoked prior to scanning 1206*3d8817e4Smiodthe relax table. 1207*3d8817e4Smiod 1208*3d8817e4Smiod@item LINKER_RELAXING_SHRINKS_ONLY 1209*3d8817e4Smiod@cindex LINKER_RELAXING_SHRINKS_ONLY 1210*3d8817e4SmiodIf you define this macro, and the global variable @samp{linkrelax} is set 1211*3d8817e4Smiod(because of a command line option, or unconditionally in @code{md_begin}), a 1212*3d8817e4Smiod@samp{.align} directive will cause extra space to be allocated. The linker can 1213*3d8817e4Smiodthen discard this space when relaxing the section. 1214*3d8817e4Smiod 1215*3d8817e4Smiod@item TC_LINKRELAX_FIXUP (@var{segT}) 1216*3d8817e4Smiod@cindex TC_LINKRELAX_FIXUP 1217*3d8817e4SmiodIf defined, this macro allows control over whether fixups for a 1218*3d8817e4Smiodgiven section will be processed when the @var{linkrelax} variable is 1219*3d8817e4Smiodset. The macro is given the N_TYPE bits for the section in its 1220*3d8817e4Smiod@var{segT} argument. If the macro evaluates to a non-zero value 1221*3d8817e4Smiodthen the fixups will be converted into relocs, otherwise they will 1222*3d8817e4Smiodbe passed to @var{md_apply_fix} as normal. 1223*3d8817e4Smiod 1224*3d8817e4Smiod@item md_convert_frag 1225*3d8817e4Smiod@cindex md_convert_frag 1226*3d8817e4SmiodGAS will call this for each rs_machine_dependent fragment. 1227*3d8817e4SmiodThe instruction is completed using the data from the relaxation pass. 1228*3d8817e4SmiodIt may also create any necessary relocations. 1229*3d8817e4Smiod@xref{Relaxation}. 1230*3d8817e4Smiod 1231*3d8817e4Smiod@item TC_FINALIZE_SYMS_BEFORE_SIZE_SEG 1232*3d8817e4Smiod@cindex TC_FINALIZE_SYMS_BEFORE_SIZE_SEG 1233*3d8817e4SmiodSpecifies the value to be assigned to @code{finalize_syms} before the function 1234*3d8817e4Smiod@code{size_segs} is called. Since @code{size_segs} calls @code{cvt_frag_to_fill} 1235*3d8817e4Smiodwhich can call @code{md_convert_frag}, this constant governs whether the symbols 1236*3d8817e4Smiodaccessed in @code{md_convert_frag} will be fully resolved. In particular it 1237*3d8817e4Smiodgoverns whether local symbols will have been resolved, and had their frag 1238*3d8817e4Smiodinformation removed. Depending upon the processing performed by 1239*3d8817e4Smiod@code{md_convert_frag} the frag information may or may not be necessary, as may 1240*3d8817e4Smiodthe resolved values of the symbols. The default value is 1. 1241*3d8817e4Smiod 1242*3d8817e4Smiod@item TC_VALIDATE_FIX (@var{fixP}, @var{seg}, @var{skip}) 1243*3d8817e4Smiod@cindex TC_VALIDATE_FIX 1244*3d8817e4SmiodThis macro is evaluated for each fixup (when @var{linkrelax} is not set). 1245*3d8817e4SmiodIt may be used to change the fixup in @code{struct fix *@var{fixP}} before 1246*3d8817e4Smiodthe generic code sees it, or to fully process the fixup. In the latter case, 1247*3d8817e4Smioda @code{goto @var{skip}} will bypass the generic code. 1248*3d8817e4Smiod 1249*3d8817e4Smiod@item md_apply_fix (@var{fixP}, @var{valP}, @var{seg}) 1250*3d8817e4Smiod@cindex md_apply_fix 1251*3d8817e4SmiodGAS will call this for each fixup that passes the @code{TC_VALIDATE_FIX} test 1252*3d8817e4Smiodwhen @var{linkrelax} is not set. It should store the correct value in the 1253*3d8817e4Smiodobject file. @code{struct fix *@var{fixP}} is the fixup @code{md_apply_fix} 1254*3d8817e4Smiodis operating on. @code{valueT *@var{valP}} is the value to store into the 1255*3d8817e4Smiodobject files, or at least is the generic code's best guess. Specifically, 1256*3d8817e4Smiod*@var{valP} is the value of the fixup symbol, perhaps modified by 1257*3d8817e4Smiod@code{MD_APPLY_SYM_VALUE}, plus @code{@var{fixP}->fx_offset} (symbol addend), 1258*3d8817e4Smiodless @code{MD_PCREL_FROM_SECTION} for pc-relative fixups. 1259*3d8817e4Smiod@code{segT @var{seg}} is the section the fix is in. 1260*3d8817e4Smiod@code{fixup_segment} performs a generic overflow check on *@var{valP} after 1261*3d8817e4Smiod@code{md_apply_fix} returns. If the overflow check is relevant for the target 1262*3d8817e4Smiodmachine, then @code{md_apply_fix} should modify *@var{valP}, typically to the 1263*3d8817e4Smiodvalue stored in the object file. 1264*3d8817e4Smiod 1265*3d8817e4Smiod@item TC_FORCE_RELOCATION (@var{fix}) 1266*3d8817e4Smiod@cindex TC_FORCE_RELOCATION 1267*3d8817e4SmiodIf this macro returns non-zero, it guarantees that a relocation will be emitted 1268*3d8817e4Smiodeven when the value can be resolved locally, as @code{fixup_segment} tries to 1269*3d8817e4Smiodreduce the number of relocations emitted. For example, a fixup expression 1270*3d8817e4Smiodagainst an absolute symbol will normally not require a reloc. If undefined, 1271*3d8817e4Smioda default of @w{@code{(S_FORCE_RELOC ((@var{fix})->fx_addsy))}} is used. 1272*3d8817e4Smiod 1273*3d8817e4Smiod@item TC_FORCE_RELOCATION_ABS (@var{fix}) 1274*3d8817e4Smiod@cindex TC_FORCE_RELOCATION_ABS 1275*3d8817e4SmiodLike @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against an 1276*3d8817e4Smiodabsolute symbol. If undefined, @code{TC_FORCE_RELOCATION} will be used. 1277*3d8817e4Smiod 1278*3d8817e4Smiod@item TC_FORCE_RELOCATION_LOCAL (@var{fix}) 1279*3d8817e4Smiod@cindex TC_FORCE_RELOCATION_LOCAL 1280*3d8817e4SmiodLike @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against a 1281*3d8817e4Smiodsymbol in the current section. If undefined, fixups that are not 1282*3d8817e4Smiod@code{fx_pcrel} or @code{fx_plt} or for which @code{TC_FORCE_RELOCATION} 1283*3d8817e4Smiodreturns non-zero, will emit relocs. 1284*3d8817e4Smiod 1285*3d8817e4Smiod@item TC_FORCE_RELOCATION_SUB_SAME (@var{fix}, @var{seg}) 1286*3d8817e4Smiod@cindex TC_FORCE_RELOCATION_SUB_SAME 1287*3d8817e4SmiodThis macro controls resolution of fixup expressions involving the 1288*3d8817e4Smioddifference of two symbols in the same section. If this macro returns zero, 1289*3d8817e4Smiodthe subtrahend will be resolved and @code{fx_subsy} set to @code{NULL} for 1290*3d8817e4Smiod@code{md_apply_fix}. If undefined, the default of 1291*3d8817e4Smiod@w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will 1292*3d8817e4Smiodbe used. 1293*3d8817e4Smiod 1294*3d8817e4Smiod@item TC_FORCE_RELOCATION_SUB_ABS (@var{fix}) 1295*3d8817e4Smiod@cindex TC_FORCE_RELOCATION_SUB_ABS 1296*3d8817e4SmiodLike @code{TC_FORCE_RELOCATION_SUB_SAME}, but used when the subtrahend is an 1297*3d8817e4Smiodabsolute symbol. If the macro is undefined a default of @code{0} is used. 1298*3d8817e4Smiod 1299*3d8817e4Smiod@item TC_FORCE_RELOCATION_SUB_LOCAL (@var{fix}) 1300*3d8817e4Smiod@cindex TC_FORCE_RELOCATION_SUB_LOCAL 1301*3d8817e4SmiodLike @code{TC_FORCE_RELOCATION_SUB_ABS}, but the subtrahend is a symbol in the 1302*3d8817e4Smiodsame section as the fixup. 1303*3d8817e4Smiod 1304*3d8817e4Smiod@item TC_VALIDATE_FIX_SUB (@var{fix}) 1305*3d8817e4Smiod@cindex TC_VALIDATE_FIX_SUB 1306*3d8817e4SmiodThis macro is evaluated for any fixup with a @code{fx_subsy} that 1307*3d8817e4Smiod@code{fixup_segment} cannot reduce to a number. If the macro returns 1308*3d8817e4Smiod@code{false} an error will be reported. 1309*3d8817e4Smiod 1310*3d8817e4Smiod@item MD_APPLY_SYM_VALUE (@var{fix}) 1311*3d8817e4Smiod@cindex MD_APPLY_SYM_VALUE 1312*3d8817e4SmiodThis macro controls whether the symbol value becomes part of the value passed 1313*3d8817e4Smiodto @code{md_apply_fix}. If the macro is undefined, or returns non-zero, the 1314*3d8817e4Smiodsymbol value will be included. For ELF, a suitable definition might simply be 1315*3d8817e4Smiod@code{0}, because ELF relocations don't include the symbol value in the addend. 1316*3d8817e4Smiod 1317*3d8817e4Smiod@item S_FORCE_RELOC (@var{sym}, @var{strict}) 1318*3d8817e4Smiod@cindex S_FORCE_RELOC 1319*3d8817e4SmiodThis function returns true for symbols 1320*3d8817e4Smiodthat should not be reduced to section symbols or eliminated from expressions, 1321*3d8817e4Smiodbecause they may be overridden by the linker. ie. for symbols that are 1322*3d8817e4Smiodundefined or common, and when @var{strict} is set, weak, or global (for ELF 1323*3d8817e4Smiodassemblers that support ELF shared library linking semantics). 1324*3d8817e4Smiod 1325*3d8817e4Smiod@item EXTERN_FORCE_RELOC 1326*3d8817e4Smiod@cindex EXTERN_FORCE_RELOC 1327*3d8817e4SmiodThis macro controls whether @code{S_FORCE_RELOC} returns true for global 1328*3d8817e4Smiodsymbols. If undefined, the default is @code{true} for ELF assemblers, and 1329*3d8817e4Smiod@code{false} for non-ELF. 1330*3d8817e4Smiod 1331*3d8817e4Smiod@item tc_gen_reloc 1332*3d8817e4Smiod@cindex tc_gen_reloc 1333*3d8817e4SmiodGAS will call this to generate a reloc. GAS will pass 1334*3d8817e4Smiodthe resulting reloc to @code{bfd_install_relocation}. This currently works 1335*3d8817e4Smiodpoorly, as @code{bfd_install_relocation} often does the wrong thing, and 1336*3d8817e4Smiodinstances of @code{tc_gen_reloc} have been written to work around the problems, 1337*3d8817e4Smiodwhich in turns makes it difficult to fix @code{bfd_install_relocation}. 1338*3d8817e4Smiod 1339*3d8817e4Smiod@item RELOC_EXPANSION_POSSIBLE 1340*3d8817e4Smiod@cindex RELOC_EXPANSION_POSSIBLE 1341*3d8817e4SmiodIf you define this macro, it means that @code{tc_gen_reloc} may return multiple 1342*3d8817e4Smiodrelocation entries for a single fixup. In this case, the return value of 1343*3d8817e4Smiod@code{tc_gen_reloc} is a pointer to a null terminated array. 1344*3d8817e4Smiod 1345*3d8817e4Smiod@item MAX_RELOC_EXPANSION 1346*3d8817e4Smiod@cindex MAX_RELOC_EXPANSION 1347*3d8817e4SmiodYou must define this if @code{RELOC_EXPANSION_POSSIBLE} is defined; it 1348*3d8817e4Smiodindicates the largest number of relocs which @code{tc_gen_reloc} may return for 1349*3d8817e4Smioda single fixup. 1350*3d8817e4Smiod 1351*3d8817e4Smiod@item tc_fix_adjustable 1352*3d8817e4Smiod@cindex tc_fix_adjustable 1353*3d8817e4SmiodYou may define this macro to indicate whether a fixup against a locally defined 1354*3d8817e4Smiodsymbol should be adjusted to be against the section symbol. It should return a 1355*3d8817e4Smiodnon-zero value if the adjustment is acceptable. 1356*3d8817e4Smiod 1357*3d8817e4Smiod@item MD_PCREL_FROM_SECTION (@var{fixp}, @var{section}) 1358*3d8817e4Smiod@cindex MD_PCREL_FROM_SECTION 1359*3d8817e4SmiodIf you define this macro, it should return the position from which the PC 1360*3d8817e4Smiodrelative adjustment for a PC relative fixup should be made. On many 1361*3d8817e4Smiodprocessors, the base of a PC relative instruction is the next instruction, 1362*3d8817e4Smiodso this macro would return the length of an instruction, plus the address of 1363*3d8817e4Smiodthe PC relative fixup. The latter can be calculated as 1364*3d8817e4Smiod@var{fixp}->fx_where + @var{fixp}->fx_frag->fr_address . 1365*3d8817e4Smiod 1366*3d8817e4Smiod@item md_pcrel_from 1367*3d8817e4Smiod@cindex md_pcrel_from 1368*3d8817e4SmiodThis is the default value of @code{MD_PCREL_FROM_SECTION}. The difference is 1369*3d8817e4Smiodthat @code{md_pcrel_from} does not take a section argument. 1370*3d8817e4Smiod 1371*3d8817e4Smiod@item tc_frob_label 1372*3d8817e4Smiod@cindex tc_frob_label 1373*3d8817e4SmiodIf you define this macro, GAS will call it each time a label is defined. 1374*3d8817e4Smiod 1375*3d8817e4Smiod@item md_section_align 1376*3d8817e4Smiod@cindex md_section_align 1377*3d8817e4SmiodGAS will call this function for each section at the end of the assembly, to 1378*3d8817e4Smiodpermit the CPU backend to adjust the alignment of a section. The function 1379*3d8817e4Smiodmust take two arguments, a @code{segT} for the section and a @code{valueT} 1380*3d8817e4Smiodfor the size of the section, and return a @code{valueT} for the rounded 1381*3d8817e4Smiodsize. 1382*3d8817e4Smiod 1383*3d8817e4Smiod@item md_macro_start 1384*3d8817e4Smiod@cindex md_macro_start 1385*3d8817e4SmiodIf defined, GAS will call this macro when it starts to include a macro 1386*3d8817e4Smiodexpansion. @code{macro_nest} indicates the current macro nesting level, which 1387*3d8817e4Smiodincludes the one being expanded. 1388*3d8817e4Smiod 1389*3d8817e4Smiod@item md_macro_info 1390*3d8817e4Smiod@cindex md_macro_info 1391*3d8817e4SmiodIf defined, GAS will call this macro after the macro expansion has been 1392*3d8817e4Smiodincluded in the input and after parsing the macro arguments. The single 1393*3d8817e4Smiodargument is a pointer to the macro processing's internal representation of the 1394*3d8817e4Smiodmacro (macro_entry *), which includes expansion of the formal arguments. 1395*3d8817e4Smiod 1396*3d8817e4Smiod@item md_macro_end 1397*3d8817e4Smiod@cindex md_macro_end 1398*3d8817e4SmiodComplement to md_macro_start. If defined, it is called when finished 1399*3d8817e4Smiodprocessing an inserted macro expansion, just before decrementing macro_nest. 1400*3d8817e4Smiod 1401*3d8817e4Smiod@item DOUBLEBAR_PARALLEL 1402*3d8817e4Smiod@cindex DOUBLEBAR_PARALLEL 1403*3d8817e4SmiodAffects the preprocessor so that lines containing '||' don't have their 1404*3d8817e4Smiodwhitespace stripped following the double bar. This is useful for targets that 1405*3d8817e4Smiodimplement parallel instructions. 1406*3d8817e4Smiod 1407*3d8817e4Smiod@item KEEP_WHITE_AROUND_COLON 1408*3d8817e4Smiod@cindex KEEP_WHITE_AROUND_COLON 1409*3d8817e4SmiodNormally, whitespace is compressed and removed when, in the presence of the 1410*3d8817e4Smiodcolon, the adjoining tokens can be distinguished. This option affects the 1411*3d8817e4Smiodpreprocessor so that whitespace around colons is preserved. This is useful 1412*3d8817e4Smiodwhen colons might be removed from the input after preprocessing but before 1413*3d8817e4Smiodassembling, so that adjoining tokens can still be distinguished if there is 1414*3d8817e4Smiodwhitespace, or concatenated if there is not. 1415*3d8817e4Smiod 1416*3d8817e4Smiod@item tc_frob_section 1417*3d8817e4Smiod@cindex tc_frob_section 1418*3d8817e4SmiodIf you define this macro, GAS will call it for each 1419*3d8817e4Smiodsection at the end of the assembly. 1420*3d8817e4Smiod 1421*3d8817e4Smiod@item tc_frob_file_before_adjust 1422*3d8817e4Smiod@cindex tc_frob_file_before_adjust 1423*3d8817e4SmiodIf you define this macro, GAS will call it after the symbol values are 1424*3d8817e4Smiodresolved, but before the fixups have been changed from local symbols to section 1425*3d8817e4Smiodsymbols. 1426*3d8817e4Smiod 1427*3d8817e4Smiod@item tc_frob_symbol 1428*3d8817e4Smiod@cindex tc_frob_symbol 1429*3d8817e4SmiodIf you define this macro, GAS will call it for each symbol. You can indicate 1430*3d8817e4Smiodthat the symbol should not be included in the object file by defining this 1431*3d8817e4Smiodmacro to set its second argument to a non-zero value. 1432*3d8817e4Smiod 1433*3d8817e4Smiod@item tc_frob_file 1434*3d8817e4Smiod@cindex tc_frob_file 1435*3d8817e4SmiodIf you define this macro, GAS will call it after the symbol table has been 1436*3d8817e4Smiodcompleted, but before the relocations have been generated. 1437*3d8817e4Smiod 1438*3d8817e4Smiod@item tc_frob_file_after_relocs 1439*3d8817e4SmiodIf you define this macro, GAS will call it after the relocs have been 1440*3d8817e4Smiodgenerated. 1441*3d8817e4Smiod 1442*3d8817e4Smiod@item md_post_relax_hook 1443*3d8817e4SmiodIf you define this macro, GAS will call it after relaxing and sizing the 1444*3d8817e4Smiodsegments. 1445*3d8817e4Smiod 1446*3d8817e4Smiod@item LISTING_HEADER 1447*3d8817e4SmiodA string to use on the header line of a listing. The default value is simply 1448*3d8817e4Smiod@code{"GAS LISTING"}. 1449*3d8817e4Smiod 1450*3d8817e4Smiod@item LISTING_WORD_SIZE 1451*3d8817e4SmiodThe number of bytes to put into a word in a listing. This affects the way the 1452*3d8817e4Smiodbytes are clumped together in the listing. For example, a value of 2 might 1453*3d8817e4Smiodprint @samp{1234 5678} where a value of 1 would print @samp{12 34 56 78}. The 1454*3d8817e4Smioddefault value is 4. 1455*3d8817e4Smiod 1456*3d8817e4Smiod@item LISTING_LHS_WIDTH 1457*3d8817e4SmiodThe number of words of data to print on the first line of a listing for a 1458*3d8817e4Smiodparticular source line, where each word is @code{LISTING_WORD_SIZE} bytes. The 1459*3d8817e4Smioddefault value is 1. 1460*3d8817e4Smiod 1461*3d8817e4Smiod@item LISTING_LHS_WIDTH_SECOND 1462*3d8817e4SmiodLike @code{LISTING_LHS_WIDTH}, but applying to the second and subsequent line 1463*3d8817e4Smiodof the data printed for a particular source line. The default value is 1. 1464*3d8817e4Smiod 1465*3d8817e4Smiod@item LISTING_LHS_CONT_LINES 1466*3d8817e4SmiodThe maximum number of continuation lines to print in a listing for a particular 1467*3d8817e4Smiodsource line. The default value is 4. 1468*3d8817e4Smiod 1469*3d8817e4Smiod@item LISTING_RHS_WIDTH 1470*3d8817e4SmiodThe maximum number of characters to print from one line of the input file. The 1471*3d8817e4Smioddefault value is 100. 1472*3d8817e4Smiod 1473*3d8817e4Smiod@item TC_COFF_SECTION_DEFAULT_ATTRIBUTES 1474*3d8817e4Smiod@cindex TC_COFF_SECTION_DEFAULT_ATTRIBUTES 1475*3d8817e4SmiodThe COFF @code{.section} directive will use the value of this macro to set 1476*3d8817e4Smioda new section's attributes when a directive has no valid flags or when the 1477*3d8817e4Smiodflag is @code{w}. The default value of the macro is @code{SEC_LOAD | SEC_DATA}. 1478*3d8817e4Smiod 1479*3d8817e4Smiod@item DWARF2_FORMAT () 1480*3d8817e4Smiod@cindex DWARF2_FORMAT 1481*3d8817e4SmiodIf you define this, it should return one of @code{dwarf2_format_32bit}, 1482*3d8817e4Smiod@code{dwarf2_format_64bit}, or @code{dwarf2_format_64bit_irix} to indicate 1483*3d8817e4Smiodthe size of internal DWARF section offsets and the format of the DWARF initial 1484*3d8817e4Smiodlength fields. When @code{dwarf2_format_32bit} is returned, the initial 1485*3d8817e4Smiodlength field will be 4 bytes long and section offsets are 32 bits in size. 1486*3d8817e4SmiodFor @code{dwarf2_format_64bit} and @code{dwarf2_format_64bit_irix}, section 1487*3d8817e4Smiodoffsets are 64 bits in size, but the initial length field differs. An 8 byte 1488*3d8817e4Smiodinitial length is indicated by @code{dwarf2_format_64bit_irix} and 1489*3d8817e4Smiod@code{dwarf2_format_64bit} indicates a 12 byte initial length field in 1490*3d8817e4Smiodwhich the first four bytes are 0xffffffff and the next 8 bytes are 1491*3d8817e4Smiodthe section's length. 1492*3d8817e4Smiod 1493*3d8817e4SmiodIf you don't define this, @code{dwarf2_format_32bit} will be used as 1494*3d8817e4Smiodthe default. 1495*3d8817e4Smiod 1496*3d8817e4SmiodThis define only affects @code{.debug_info} and @code{.debug_line} 1497*3d8817e4Smiodsections generated by the assembler. DWARF 2 sections generated by 1498*3d8817e4Smiodother tools will be unaffected by this setting. 1499*3d8817e4Smiod 1500*3d8817e4Smiod@item DWARF2_ADDR_SIZE (@var{bfd}) 1501*3d8817e4Smiod@cindex DWARF2_ADDR_SIZE 1502*3d8817e4SmiodIt should return the size of an address, as it should be represented in 1503*3d8817e4Smioddebugging info. If you don't define this macro, the default definition uses 1504*3d8817e4Smiodthe number of bits per address, as defined in @var{bfd}, divided by 8. 1505*3d8817e4Smiod 1506*3d8817e4Smiod@item MD_DEBUG_FORMAT_SELECTOR 1507*3d8817e4Smiod@cindex MD_DEBUG_FORMAT_SELECTOR 1508*3d8817e4SmiodIf defined this macro is the name of a function to be called when the 1509*3d8817e4Smiod@samp{--gen-debug} switch is detected on the assembler's command line. The 1510*3d8817e4Smiodprototype for the function looks like this: 1511*3d8817e4Smiod 1512*3d8817e4Smiod@smallexample 1513*3d8817e4Smiod enum debug_info_type MD_DEBUG_FORMAT_SELECTOR (int * use_gnu_extensions) 1514*3d8817e4Smiod@end smallexample 1515*3d8817e4Smiod 1516*3d8817e4SmiodThe function should return the debug format that is preferred by the CPU 1517*3d8817e4Smiodbackend. This format will be used when generating assembler specific debug 1518*3d8817e4Smiodinformation. 1519*3d8817e4Smiod 1520*3d8817e4Smiod@end table 1521*3d8817e4Smiod 1522*3d8817e4Smiod@node Object format backend 1523*3d8817e4Smiod@subsection Writing an object format backend 1524*3d8817e4Smiod@cindex object format backend 1525*3d8817e4Smiod@cindex @file{obj-@var{fmt}} 1526*3d8817e4Smiod 1527*3d8817e4SmiodAs with the CPU backend, the object format backend must define a few things, 1528*3d8817e4Smiodand may define some other things. The interface to the object format backend 1529*3d8817e4Smiodis generally simpler; most of the support for an object file format consists of 1530*3d8817e4Smioddefining a number of pseudo-ops. 1531*3d8817e4Smiod 1532*3d8817e4SmiodThe object format @file{.h} file must include @file{targ-cpu.h}. 1533*3d8817e4Smiod 1534*3d8817e4Smiod@table @code 1535*3d8817e4Smiod@item OBJ_@var{format} 1536*3d8817e4Smiod@cindex OBJ_@var{format} 1537*3d8817e4SmiodBy convention, you should define this macro in the @file{.h} file. For 1538*3d8817e4Smiodexample, @file{obj-elf.h} defines @code{OBJ_ELF}. You might have to use this 1539*3d8817e4Smiodif it is necessary to add object file format specific code to the CPU file. 1540*3d8817e4Smiod 1541*3d8817e4Smiod@item obj_begin 1542*3d8817e4SmiodIf you define this macro, GAS will call it at the start of the assembly, after 1543*3d8817e4Smiodthe command line arguments have been parsed and all the machine independent 1544*3d8817e4Smiodinitializations have been completed. 1545*3d8817e4Smiod 1546*3d8817e4Smiod@item obj_app_file 1547*3d8817e4Smiod@cindex obj_app_file 1548*3d8817e4SmiodIf you define this macro, GAS will invoke it when it sees a @code{.file} 1549*3d8817e4Smiodpseudo-op or a @samp{#} line as used by the C preprocessor. 1550*3d8817e4Smiod 1551*3d8817e4Smiod@item OBJ_COPY_SYMBOL_ATTRIBUTES 1552*3d8817e4Smiod@cindex OBJ_COPY_SYMBOL_ATTRIBUTES 1553*3d8817e4SmiodYou should define this macro to copy object format specific information from 1554*3d8817e4Smiodone symbol to another. GAS will call it when one symbol is equated to 1555*3d8817e4Smiodanother. 1556*3d8817e4Smiod 1557*3d8817e4Smiod@item obj_sec_sym_ok_for_reloc 1558*3d8817e4Smiod@cindex obj_sec_sym_ok_for_reloc 1559*3d8817e4SmiodYou may define this macro to indicate that it is OK to use a section symbol in 1560*3d8817e4Smioda relocation entry. If it is not, GAS will define a new symbol at the start 1561*3d8817e4Smiodof a section. 1562*3d8817e4Smiod 1563*3d8817e4Smiod@item EMIT_SECTION_SYMBOLS 1564*3d8817e4Smiod@cindex EMIT_SECTION_SYMBOLS 1565*3d8817e4SmiodYou should define this macro with a zero value if you do not want to include 1566*3d8817e4Smiodsection symbols in the output symbol table. The default value for this macro 1567*3d8817e4Smiodis one. 1568*3d8817e4Smiod 1569*3d8817e4Smiod@item obj_adjust_symtab 1570*3d8817e4Smiod@cindex obj_adjust_symtab 1571*3d8817e4SmiodIf you define this macro, GAS will invoke it just before setting the symbol 1572*3d8817e4Smiodtable of the output BFD. For example, the COFF support uses this macro to 1573*3d8817e4Smiodgenerate a @code{.file} symbol if none was generated previously. 1574*3d8817e4Smiod 1575*3d8817e4Smiod@item SEPARATE_STAB_SECTIONS 1576*3d8817e4Smiod@cindex SEPARATE_STAB_SECTIONS 1577*3d8817e4SmiodYou may define this macro to a nonzero value to indicate that stabs should be 1578*3d8817e4Smiodplaced in separate sections, as in ELF. 1579*3d8817e4Smiod 1580*3d8817e4Smiod@item INIT_STAB_SECTION 1581*3d8817e4Smiod@cindex INIT_STAB_SECTION 1582*3d8817e4SmiodYou may define this macro to initialize the stabs section in the output file. 1583*3d8817e4Smiod 1584*3d8817e4Smiod@item OBJ_PROCESS_STAB 1585*3d8817e4Smiod@cindex OBJ_PROCESS_STAB 1586*3d8817e4SmiodYou may define this macro to do specific processing on a stabs entry. 1587*3d8817e4Smiod 1588*3d8817e4Smiod@item obj_frob_section 1589*3d8817e4Smiod@cindex obj_frob_section 1590*3d8817e4SmiodIf you define this macro, GAS will call it for each section at the end of the 1591*3d8817e4Smiodassembly. 1592*3d8817e4Smiod 1593*3d8817e4Smiod@item obj_frob_file_before_adjust 1594*3d8817e4Smiod@cindex obj_frob_file_before_adjust 1595*3d8817e4SmiodIf you define this macro, GAS will call it after the symbol values are 1596*3d8817e4Smiodresolved, but before the fixups have been changed from local symbols to section 1597*3d8817e4Smiodsymbols. 1598*3d8817e4Smiod 1599*3d8817e4Smiod@item obj_frob_symbol 1600*3d8817e4Smiod@cindex obj_frob_symbol 1601*3d8817e4SmiodIf you define this macro, GAS will call it for each symbol. You can indicate 1602*3d8817e4Smiodthat the symbol should not be included in the object file by defining this 1603*3d8817e4Smiodmacro to set its second argument to a non-zero value. 1604*3d8817e4Smiod 1605*3d8817e4Smiod@item obj_set_weak_hook 1606*3d8817e4Smiod@cindex obj_set_weak_hook 1607*3d8817e4SmiodIf you define this macro, @code{S_SET_WEAK} will call it before modifying the 1608*3d8817e4Smiodsymbol's flags. 1609*3d8817e4Smiod 1610*3d8817e4Smiod@item obj_clear_weak_hook 1611*3d8817e4Smiod@cindex obj_clear_weak_hook 1612*3d8817e4SmiodIf you define this macro, @code{S_CLEAR_WEAKREFD} will call it after clearning 1613*3d8817e4Smiodthe @code{weakrefd} flag, but before modifying any other flags. 1614*3d8817e4Smiod 1615*3d8817e4Smiod@item obj_frob_file 1616*3d8817e4Smiod@cindex obj_frob_file 1617*3d8817e4SmiodIf you define this macro, GAS will call it after the symbol table has been 1618*3d8817e4Smiodcompleted, but before the relocations have been generated. 1619*3d8817e4Smiod 1620*3d8817e4Smiod@item obj_frob_file_after_relocs 1621*3d8817e4SmiodIf you define this macro, GAS will call it after the relocs have been 1622*3d8817e4Smiodgenerated. 1623*3d8817e4Smiod 1624*3d8817e4Smiod@item SET_SECTION_RELOCS (@var{sec}, @var{relocs}, @var{n}) 1625*3d8817e4Smiod@cindex SET_SECTION_RELOCS 1626*3d8817e4SmiodIf you define this, it will be called after the relocations have been set for 1627*3d8817e4Smiodthe section @var{sec}. The list of relocations is in @var{relocs}, and the 1628*3d8817e4Smiodnumber of relocations is in @var{n}. 1629*3d8817e4Smiod@end table 1630*3d8817e4Smiod 1631*3d8817e4Smiod@node Emulations 1632*3d8817e4Smiod@subsection Writing emulation files 1633*3d8817e4Smiod 1634*3d8817e4SmiodNormally you do not have to write an emulation file. You can just use 1635*3d8817e4Smiod@file{te-generic.h}. 1636*3d8817e4Smiod 1637*3d8817e4SmiodIf you do write your own emulation file, it must include @file{obj-format.h}. 1638*3d8817e4Smiod 1639*3d8817e4SmiodAn emulation file will often define @code{TE_@var{EM}}; this may then be used 1640*3d8817e4Smiodin other files to change the output. 1641*3d8817e4Smiod 1642*3d8817e4Smiod@node Relaxation 1643*3d8817e4Smiod@section Relaxation 1644*3d8817e4Smiod@cindex relaxation 1645*3d8817e4Smiod 1646*3d8817e4Smiod@dfn{Relaxation} is a generic term used when the size of some instruction or 1647*3d8817e4Smioddata depends upon the value of some symbol or other data. 1648*3d8817e4Smiod 1649*3d8817e4SmiodGAS knows to relax a particular type of PC relative relocation using a table. 1650*3d8817e4SmiodYou can also define arbitrarily complex forms of relaxation yourself. 1651*3d8817e4Smiod 1652*3d8817e4Smiod@menu 1653*3d8817e4Smiod* Relaxing with a table:: Relaxing with a table 1654*3d8817e4Smiod* General relaxing:: General relaxing 1655*3d8817e4Smiod@end menu 1656*3d8817e4Smiod 1657*3d8817e4Smiod@node Relaxing with a table 1658*3d8817e4Smiod@subsection Relaxing with a table 1659*3d8817e4Smiod 1660*3d8817e4SmiodIf you do not define @code{md_relax_frag}, and you do define 1661*3d8817e4Smiod@code{TC_GENERIC_RELAX_TABLE}, GAS will relax @code{rs_machine_dependent} frags 1662*3d8817e4Smiodbased on the frag subtype and the displacement to some specified target 1663*3d8817e4Smiodaddress. The basic idea is that several machines have different addressing 1664*3d8817e4Smiodmodes for instructions that can specify different ranges of values, with 1665*3d8817e4Smiodsuccessive modes able to access wider ranges, including the entirety of the 1666*3d8817e4Smiodprevious range. Smaller ranges are assumed to be more desirable (perhaps the 1667*3d8817e4Smiodinstruction requires one word instead of two or three); if this is not the 1668*3d8817e4Smiodcase, don't describe the smaller-range, inferior mode. 1669*3d8817e4Smiod 1670*3d8817e4SmiodThe @code{fr_subtype} field of a frag is an index into a CPU-specific 1671*3d8817e4Smiodrelaxation table. That table entry indicates the range of values that can be 1672*3d8817e4Smiodstored, the number of bytes that will have to be added to the frag to 1673*3d8817e4Smiodaccommodate the addressing mode, and the index of the next entry to examine if 1674*3d8817e4Smiodthe value to be stored is outside the range accessible by the current 1675*3d8817e4Smiodaddressing mode. The @code{fr_symbol} field of the frag indicates what symbol 1676*3d8817e4Smiodis to be accessed; the @code{fr_offset} field is added in. 1677*3d8817e4Smiod 1678*3d8817e4SmiodIf the @code{TC_PCREL_ADJUST} macro is defined, which currently should only happen 1679*3d8817e4Smiodfor the NS32k family, the @code{TC_PCREL_ADJUST} macro is called on the frag to 1680*3d8817e4Smiodcompute an adjustment to be made to the displacement. 1681*3d8817e4Smiod 1682*3d8817e4SmiodThe value fitted by the relaxation code is always assumed to be a displacement 1683*3d8817e4Smiodfrom the current frag. (More specifically, from @code{fr_fix} bytes into the 1684*3d8817e4Smiodfrag.) 1685*3d8817e4Smiod@ignore 1686*3d8817e4SmiodThis seems kinda silly. What about fitting small absolute values? I suppose 1687*3d8817e4Smiod@code{md_assemble} is supposed to take care of that, but if the operand is a 1688*3d8817e4Smioddifference between symbols, it might not be able to, if the difference was not 1689*3d8817e4Smiodcomputable yet. 1690*3d8817e4Smiod@end ignore 1691*3d8817e4Smiod 1692*3d8817e4SmiodThe end of the relaxation sequence is indicated by a ``next'' value of 0. This 1693*3d8817e4Smiodmeans that the first entry in the table can't be used. 1694*3d8817e4Smiod 1695*3d8817e4SmiodFor some configurations, the linker can do relaxing within a section of an 1696*3d8817e4Smiodobject file. If call instructions of various sizes exist, the linker can 1697*3d8817e4Smioddetermine which should be used in each instance, when a symbol's value is 1698*3d8817e4Smiodresolved. In order for the linker to avoid wasting space and having to insert 1699*3d8817e4Smiodno-op instructions, it must be able to expand or shrink the section contents 1700*3d8817e4Smiodwhile still preserving intra-section references and meeting alignment 1701*3d8817e4Smiodrequirements. 1702*3d8817e4Smiod 1703*3d8817e4SmiodFor the i960 using b.out format, no expansion is done; instead, each 1704*3d8817e4Smiod@samp{.align} directive causes extra space to be allocated, enough that when 1705*3d8817e4Smiodthe linker is relaxing a section and removing unneeded space, it can discard 1706*3d8817e4Smiodsome or all of this extra padding and cause the following data to be correctly 1707*3d8817e4Smiodaligned. 1708*3d8817e4Smiod 1709*3d8817e4SmiodFor the H8/300, I think the linker expands calls that can't reach, and doesn't 1710*3d8817e4Smiodworry about alignment issues; the cpu probably never needs any significant 1711*3d8817e4Smiodalignment beyond the instruction size. 1712*3d8817e4Smiod 1713*3d8817e4SmiodThe relaxation table type contains these fields: 1714*3d8817e4Smiod 1715*3d8817e4Smiod@table @code 1716*3d8817e4Smiod@item long rlx_forward 1717*3d8817e4SmiodForward reach, must be non-negative. 1718*3d8817e4Smiod@item long rlx_backward 1719*3d8817e4SmiodBackward reach, must be zero or negative. 1720*3d8817e4Smiod@item rlx_length 1721*3d8817e4SmiodLength in bytes of this addressing mode. 1722*3d8817e4Smiod@item rlx_more 1723*3d8817e4SmiodIndex of the next-longer relax state, or zero if there is no next relax state. 1724*3d8817e4Smiod@end table 1725*3d8817e4Smiod 1726*3d8817e4SmiodThe relaxation is done in @code{relax_segment} in @file{write.c}. The 1727*3d8817e4Smioddifference in the length fields between the original mode and the one finally 1728*3d8817e4Smiodchosen by the relaxing code is taken as the size by which the current frag will 1729*3d8817e4Smiodbe increased in size. For example, if the initial relaxing mode has a length 1730*3d8817e4Smiodof 2 bytes, and because of the size of the displacement, it gets upgraded to a 1731*3d8817e4Smiodmode with a size of 6 bytes, it is assumed that the frag will grow by 4 bytes. 1732*3d8817e4Smiod(The initial two bytes should have been part of the fixed portion of the frag, 1733*3d8817e4Smiodsince it is already known that they will be output.) This growth must be 1734*3d8817e4Smiodeffected by @code{md_convert_frag}; it should increase the @code{fr_fix} field 1735*3d8817e4Smiodby the appropriate size, and fill in the appropriate bytes of the frag. 1736*3d8817e4Smiod(Enough space for the maximum growth should have been allocated in the call to 1737*3d8817e4Smiodfrag_var as the second argument.) 1738*3d8817e4Smiod 1739*3d8817e4SmiodIf relocation records are needed, they should be emitted by 1740*3d8817e4Smiod@code{md_estimate_size_before_relax}. This function should examine the target 1741*3d8817e4Smiodsymbol of the supplied frag and correct the @code{fr_subtype} of the frag if 1742*3d8817e4Smiodneeded. When this function is called, if the symbol has not yet been defined, 1743*3d8817e4Smiodit will not become defined later; however, its value may still change if the 1744*3d8817e4Smiodsection it is in gets relaxed. 1745*3d8817e4Smiod 1746*3d8817e4SmiodUsually, if the symbol is in the same section as the frag (given by the 1747*3d8817e4Smiod@var{sec} argument), the narrowest likely relaxation mode is stored in 1748*3d8817e4Smiod@code{fr_subtype}, and that's that. 1749*3d8817e4Smiod 1750*3d8817e4SmiodIf the symbol is undefined, or in a different section (and therefore movable 1751*3d8817e4Smiodto an arbitrarily large distance), the largest available relaxation mode is 1752*3d8817e4Smiodspecified, @code{fix_new} is called to produce the relocation record, 1753*3d8817e4Smiod@code{fr_fix} is increased to include the relocated field (remember, this 1754*3d8817e4Smiodstorage was allocated when @code{frag_var} was called), and @code{frag_wane} is 1755*3d8817e4Smiodcalled to convert the frag to an @code{rs_fill} frag with no variant part. 1756*3d8817e4SmiodSometimes changing addressing modes may also require rewriting the instruction. 1757*3d8817e4SmiodIt can be accessed via @code{fr_opcode} or @code{fr_fix}. 1758*3d8817e4Smiod 1759*3d8817e4SmiodIf you generate frags separately for the basic insn opcode and any relaxable 1760*3d8817e4Smiodoperands, do not call @code{fix_new} thinking you can emit fixups for the 1761*3d8817e4Smiodopcode field from the relaxable frag. It is not guaranteed to be the same frag. 1762*3d8817e4SmiodIf you need to emit fixups for the opcode field from inspection of the 1763*3d8817e4Smiodrelaxable frag, then you need to generate a common frag for both the basic 1764*3d8817e4Smiodopcode and relaxable fields, or you need to provide the frag for the opcode to 1765*3d8817e4Smiodpass to @code{fix_new}. The latter can be done for example by defining 1766*3d8817e4Smiod@code{TC_FRAG_TYPE} to include a pointer to it and defining @code{TC_FRAG_INIT} 1767*3d8817e4Smiodto set the pointer. 1768*3d8817e4Smiod 1769*3d8817e4SmiodSometimes @code{fr_var} is increased instead, and @code{frag_wane} is not 1770*3d8817e4Smiodcalled. I'm not sure, but I think this is to keep @code{fr_fix} referring to 1771*3d8817e4Smiodan earlier byte, and @code{fr_subtype} set to @code{rs_machine_dependent} so 1772*3d8817e4Smiodthat @code{md_convert_frag} will get called. 1773*3d8817e4Smiod 1774*3d8817e4Smiod@node General relaxing 1775*3d8817e4Smiod@subsection General relaxing 1776*3d8817e4Smiod 1777*3d8817e4SmiodIf using a simple table is not suitable, you may implement arbitrarily complex 1778*3d8817e4Smiodrelaxation semantics yourself. For example, the MIPS backend uses this to emit 1779*3d8817e4Smioddifferent instruction sequences depending upon the size of the symbol being 1780*3d8817e4Smiodaccessed. 1781*3d8817e4Smiod 1782*3d8817e4SmiodWhen you assemble an instruction that may need relaxation, you should allocate 1783*3d8817e4Smioda frag using @code{frag_var} or @code{frag_variant} with a type of 1784*3d8817e4Smiod@code{rs_machine_dependent}. You should store some sort of information in the 1785*3d8817e4Smiod@code{fr_subtype} field so that you can figure out what to do with the frag 1786*3d8817e4Smiodlater. 1787*3d8817e4Smiod 1788*3d8817e4SmiodWhen GAS reaches the end of the input file, it will look through the frags and 1789*3d8817e4Smiodwork out their final sizes. 1790*3d8817e4Smiod 1791*3d8817e4SmiodGAS will first call @code{md_estimate_size_before_relax} on each 1792*3d8817e4Smiod@code{rs_machine_dependent} frag. This function must return an estimated size 1793*3d8817e4Smiodfor the frag. 1794*3d8817e4Smiod 1795*3d8817e4SmiodGAS will then loop over the frags, calling @code{md_relax_frag} on each 1796*3d8817e4Smiod@code{rs_machine_dependent} frag. This function should return the change in 1797*3d8817e4Smiodsize of the frag. GAS will keep looping over the frags until none of the frags 1798*3d8817e4Smiodchanges size. 1799*3d8817e4Smiod 1800*3d8817e4Smiod@node Broken words 1801*3d8817e4Smiod@section Broken words 1802*3d8817e4Smiod@cindex internals, broken words 1803*3d8817e4Smiod@cindex broken words 1804*3d8817e4Smiod 1805*3d8817e4SmiodSome compilers, including GCC, will sometimes emit switch tables specifying 1806*3d8817e4Smiod16-bit @code{.word} displacements to branch targets, and branch instructions 1807*3d8817e4Smiodthat load entries from that table to compute the target address. If this is 1808*3d8817e4Smioddone on a 32-bit machine, there is a chance (at least with really large 1809*3d8817e4Smiodfunctions) that the displacement will not fit in 16 bits. The assembler 1810*3d8817e4Smiodhandles this using a concept called @dfn{broken words}. This idea is well 1811*3d8817e4Smiodnamed, since there is an implied promise that the 16-bit field will in fact 1812*3d8817e4Smiodhold the specified displacement. 1813*3d8817e4Smiod 1814*3d8817e4SmiodIf broken word processing is enabled, and a situation like this is encountered, 1815*3d8817e4Smiodthe assembler will insert a jump instruction into the instruction stream, close 1816*3d8817e4Smiodenough to be reached with the 16-bit displacement. This jump instruction will 1817*3d8817e4Smiodtransfer to the real desired target address. Thus, as long as the @code{.word} 1818*3d8817e4Smiodvalue really is used as a displacement to compute an address to jump to, the 1819*3d8817e4Smiodnet effect will be correct (minus a very small efficiency cost). If 1820*3d8817e4Smiod@code{.word} directives with label differences for values are used for other 1821*3d8817e4Smiodpurposes, however, things may not work properly. For targets which use broken 1822*3d8817e4Smiodwords, the @samp{-K} option will warn when a broken word is discovered. 1823*3d8817e4Smiod 1824*3d8817e4SmiodThe broken word code is turned off by the @code{WORKING_DOT_WORD} macro. It 1825*3d8817e4Smiodisn't needed if @code{.word} emits a value large enough to contain an address 1826*3d8817e4Smiod(or, more correctly, any possible difference between two addresses). 1827*3d8817e4Smiod 1828*3d8817e4Smiod@node Internal functions 1829*3d8817e4Smiod@section Internal functions 1830*3d8817e4Smiod 1831*3d8817e4SmiodThis section describes basic internal functions used by GAS. 1832*3d8817e4Smiod 1833*3d8817e4Smiod@menu 1834*3d8817e4Smiod* Warning and error messages:: Warning and error messages 1835*3d8817e4Smiod* Hash tables:: Hash tables 1836*3d8817e4Smiod@end menu 1837*3d8817e4Smiod 1838*3d8817e4Smiod@node Warning and error messages 1839*3d8817e4Smiod@subsection Warning and error messages 1840*3d8817e4Smiod 1841*3d8817e4Smiod@deftypefun @{@} int had_warnings (void) 1842*3d8817e4Smiod@deftypefunx @{@} int had_errors (void) 1843*3d8817e4SmiodReturns non-zero if any warnings or errors, respectively, have been printed 1844*3d8817e4Smiodduring this invocation. 1845*3d8817e4Smiod@end deftypefun 1846*3d8817e4Smiod 1847*3d8817e4Smiod@deftypefun @{@} void as_perror (const char *@var{gripe}, const char *@var{filename}) 1848*3d8817e4SmiodDisplays a BFD or system error, then clears the error status. 1849*3d8817e4Smiod@end deftypefun 1850*3d8817e4Smiod 1851*3d8817e4Smiod@deftypefun @{@} void as_tsktsk (const char *@var{format}, ...) 1852*3d8817e4Smiod@deftypefunx @{@} void as_warn (const char *@var{format}, ...) 1853*3d8817e4Smiod@deftypefunx @{@} void as_bad (const char *@var{format}, ...) 1854*3d8817e4Smiod@deftypefunx @{@} void as_fatal (const char *@var{format}, ...) 1855*3d8817e4SmiodThese functions display messages about something amiss with the input file, or 1856*3d8817e4Smiodinternal problems in the assembler itself. The current file name and line 1857*3d8817e4Smiodnumber are printed, followed by the supplied message, formatted using 1858*3d8817e4Smiod@code{vfprintf}, and a final newline. 1859*3d8817e4Smiod 1860*3d8817e4SmiodAn error indicated by @code{as_bad} will result in a non-zero exit status when 1861*3d8817e4Smiodthe assembler has finished. Calling @code{as_fatal} will result in immediate 1862*3d8817e4Smiodtermination of the assembler process. 1863*3d8817e4Smiod@end deftypefun 1864*3d8817e4Smiod 1865*3d8817e4Smiod@deftypefun @{@} void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...) 1866*3d8817e4Smiod@deftypefunx @{@} void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...) 1867*3d8817e4SmiodThese variants permit specification of the file name and line number, and are 1868*3d8817e4Smiodused when problems are detected when reprocessing information saved away when 1869*3d8817e4Smiodprocessing some earlier part of the file. For example, fixups are processed 1870*3d8817e4Smiodafter all input has been read, but messages about fixups should refer to the 1871*3d8817e4Smiodoriginal filename and line number that they are applicable to. 1872*3d8817e4Smiod@end deftypefun 1873*3d8817e4Smiod 1874*3d8817e4Smiod@deftypefun @{@} void sprint_value (char *@var{buf}, valueT @var{val}) 1875*3d8817e4SmiodThis function is helpful for converting a @code{valueT} value into printable 1876*3d8817e4Smiodformat, in case it's wider than modes that @code{*printf} can handle. If the 1877*3d8817e4Smiodtype is narrow enough, a decimal number will be produced; otherwise, it will be 1878*3d8817e4Smiodin hexadecimal. The value itself is not examined to make this determination. 1879*3d8817e4Smiod@end deftypefun 1880*3d8817e4Smiod 1881*3d8817e4Smiod@node Hash tables 1882*3d8817e4Smiod@subsection Hash tables 1883*3d8817e4Smiod@cindex hash tables 1884*3d8817e4Smiod 1885*3d8817e4Smiod@deftypefun @{@} @{struct hash_control *@} hash_new (void) 1886*3d8817e4SmiodCreates the hash table control structure. 1887*3d8817e4Smiod@end deftypefun 1888*3d8817e4Smiod 1889*3d8817e4Smiod@deftypefun @{@} void hash_die (struct hash_control *) 1890*3d8817e4SmiodDestroy a hash table. 1891*3d8817e4Smiod@end deftypefun 1892*3d8817e4Smiod 1893*3d8817e4Smiod@deftypefun @{@} PTR hash_delete (struct hash_control *, const char *) 1894*3d8817e4SmiodDeletes entry from the hash table, returns the value it had. 1895*3d8817e4Smiod@end deftypefun 1896*3d8817e4Smiod 1897*3d8817e4Smiod@deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR) 1898*3d8817e4SmiodUpdates the value for an entry already in the table, returning the old value. 1899*3d8817e4SmiodIf no entry was found, just returns NULL. 1900*3d8817e4Smiod@end deftypefun 1901*3d8817e4Smiod 1902*3d8817e4Smiod@deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR) 1903*3d8817e4SmiodInserting a value already in the table is an error. 1904*3d8817e4SmiodReturns an error message or NULL. 1905*3d8817e4Smiod@end deftypefun 1906*3d8817e4Smiod 1907*3d8817e4Smiod@deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR) 1908*3d8817e4SmiodInserts if the value isn't already present, updates it if it is. 1909*3d8817e4Smiod@end deftypefun 1910*3d8817e4Smiod 1911*3d8817e4Smiod@node Test suite 1912*3d8817e4Smiod@section Test suite 1913*3d8817e4Smiod@cindex test suite 1914*3d8817e4Smiod 1915*3d8817e4SmiodThe test suite is kind of lame for most processors. Often it only checks to 1916*3d8817e4Smiodsee if a couple of files can be assembled without the assembler reporting any 1917*3d8817e4Smioderrors. For more complete testing, write a test which either examines the 1918*3d8817e4Smiodassembler listing, or runs @code{objdump} and examines its output. For the 1919*3d8817e4Smiodlatter, the TCL procedure @code{run_dump_test} may come in handy. It takes the 1920*3d8817e4Smiodbase name of a file, and looks for @file{@var{file}.d}. This file should 1921*3d8817e4Smiodcontain as its initial lines a set of variable settings in @samp{#} comments, 1922*3d8817e4Smiodin the form: 1923*3d8817e4Smiod 1924*3d8817e4Smiod@example 1925*3d8817e4Smiod #@var{varname}: @var{value} 1926*3d8817e4Smiod@end example 1927*3d8817e4Smiod 1928*3d8817e4SmiodThe @var{varname} may be @code{objdump}, @code{nm}, or @code{as}, in which case 1929*3d8817e4Smiodit specifies the options to be passed to the specified programs. Exactly one 1930*3d8817e4Smiodof @code{objdump} or @code{nm} must be specified, as that also specifies which 1931*3d8817e4Smiodprogram to run after the assembler has finished. If @var{varname} is 1932*3d8817e4Smiod@code{source}, it specifies the name of the source file; otherwise, 1933*3d8817e4Smiod@file{@var{file}.s} is used. If @var{varname} is @code{name}, it specifies the 1934*3d8817e4Smiodname of the test to be used in the @code{pass} or @code{fail} messages. 1935*3d8817e4Smiod 1936*3d8817e4SmiodThe non-commented parts of the file are interpreted as regular expressions, one 1937*3d8817e4Smiodper line. Blank lines in the @code{objdump} or @code{nm} output are skipped, 1938*3d8817e4Smiodas are blank lines in the @code{.d} file; the other lines are tested to see if 1939*3d8817e4Smiodthe regular expression matches the program output. If it does not, the test 1940*3d8817e4Smiodfails. 1941*3d8817e4Smiod 1942*3d8817e4SmiodNote that this means the tests must be modified if the @code{objdump} output 1943*3d8817e4Smiodstyle is changed. 1944*3d8817e4Smiod 1945*3d8817e4Smiod@bye 1946*3d8817e4Smiod@c Local Variables: 1947*3d8817e4Smiod@c fill-column: 79 1948*3d8817e4Smiod@c End: 1949