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