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