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