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