internals.texi revision 38889
168349Sobrien\input texinfo 268349Sobrien@setfilename internals.info 368349Sobrien@node Top 468349Sobrien@top Assembler Internals 568349Sobrien@raisesections 668349Sobrien@cindex internals 768349Sobrien 868349SobrienThis chapter describes the internals of the assembler. It is incomplete, but 968349Sobrienit may help a bit. 1068349Sobrien 1168349SobrienThis chapter was last modified on $Date: 1998/02/06 03:42:57 $. It is not updated regularly, and it 1268349Sobrienmay be out of date. 1368349Sobrien 1468349Sobrien@menu 1568349Sobrien* GAS versions:: GAS versions 1668349Sobrien* Data types:: Data types 1768349Sobrien* GAS processing:: What GAS does when it runs 1868349Sobrien* Porting GAS:: Porting GAS 1968349Sobrien* Relaxation:: Relaxation 2068349Sobrien* Broken words:: Broken words 2168349Sobrien* Internal functions:: Internal functions 2268349Sobrien* Test suite:: Test suite 2368349Sobrien@end menu 2468349Sobrien 2568349Sobrien@node GAS versions 2668349Sobrien@section GAS versions 2768349Sobrien 2868349SobrienGAS has acquired layers of code over time. The original GAS only supported the 2968349Sobriena.out object file format, with three sections. Support for multiple sections 3068349Sobrienhas been added in two different ways. 3168349Sobrien 3268349SobrienThe preferred approach is to use the version of GAS created when the symbol 3368349Sobrien@code{BFD_ASSEMBLER} is defined. The other versions of GAS are documented for 3468349Sobrienhistorical purposes, and to help anybody who has to debug code written for 3568349Sobrienthem. 3668349Sobrien 3768349SobrienThe type @code{segT} is used to represent a section in code which must work 3868349Sobrienwith all versions of GAS. 3968349Sobrien 4068349Sobrien@menu 4168349Sobrien* Original GAS:: Original GAS version 4268349Sobrien* MANY_SEGMENTS:: MANY_SEGMENTS gas version 4368349Sobrien* BFD_ASSEMBLER:: BFD_ASSEMBLER gas version 4468349Sobrien@end menu 4568349Sobrien 4668349Sobrien@node Original GAS 4768349Sobrien@subsection Original GAS 4868349Sobrien 4968349SobrienThe original GAS only supported the a.out object file format with three 5068349Sobriensections: @samp{.text}, @samp{.data}, and @samp{.bss}. This is the version of 5168349SobrienGAS that is compiled if neither @code{BFD_ASSEMBLER} nor @code{MANY_SEGMENTS} 5268349Sobrienis defined. This version of GAS is still used for the m68k-aout target, and 5368349Sobrienperhaps others. 5468349Sobrien 5568349SobrienThis version of GAS should not be used for any new development. 5668349Sobrien 5768349SobrienThere is still code that is specific to this version of GAS, notably in 5868349Sobrien@file{write.c}. There is no way for this code to loop through all the 5968349Sobriensections; it simply looks at global variables like @code{text_frag_root} and 6068349Sobrien@code{data_frag_root}. 6168349Sobrien 6268349SobrienThe type @code{segT} is an enum. 6368349Sobrien 6468349Sobrien@node MANY_SEGMENTS 6568349Sobrien@subsection MANY_SEGMENTS gas version 6668349Sobrien@cindex MANY_SEGMENTS 6768349Sobrien 6868349SobrienThe @code{MANY_SEGMENTS} version of gas is only used for COFF. It uses the BFD 6968349Sobrienlibrary, but it writes out all the data itself using @code{bfd_write}. This 7068349Sobrienversion of gas supports up to 40 normal sections. The section names are stored 7168349Sobrienin the @code{seg_name} array. Other information is stored in the 7268349Sobrien@code{segment_info} array. 7368349Sobrien 7468349SobrienThe type @code{segT} is an enum. Code that wants to examine all the sections 7568349Sobriencan use a @code{segT} variable as loop index from @code{SEG_E0} up to but not 7668349Sobrienincluding @code{SEG_UNKNOWN}. 7768349Sobrien 7868349SobrienMost of the code specific to this version of GAS is in the file 7968349Sobrien@file{config/obj-coff.c}, in the portion of that file that is compiled when 8068349Sobrien@code{BFD_ASSEMBLER} is not defined. 8168349Sobrien 8268349SobrienThis version of GAS is still used for several COFF targets. 8368349Sobrien 8468349Sobrien@node BFD_ASSEMBLER 8568349Sobrien@subsection BFD_ASSEMBLER gas version 8668349Sobrien@cindex BFD_ASSEMBLER 8768349Sobrien 8868349SobrienThe preferred version of GAS is the @code{BFD_ASSEMBLER} version. In this 8968349Sobrienversion of GAS, the output file is a normal BFD, and the BFD routines are used 9068349Sobriento generate the output. 9168349Sobrien 9268349Sobrien@code{BFD_ASSEMBLER} will automatically be used for certain targets, including 9368349Sobrienthose that use the ELF, ECOFF, and SOM object file formats, and also all Alpha, 9468349SobrienMIPS, PowerPC, and SPARC targets. You can force the use of 9568349Sobrien@code{BFD_ASSEMBLER} for other targets with the configure option 9668349Sobrien@samp{--enable-bfd-assembler}; however, it has not been tested for many 9768349Sobrientargets, and can not be assumed to work. 9868349Sobrien 9968349Sobrien@node Data types 10068349Sobrien@section Data types 10168349Sobrien@cindex internals, data types 10268349Sobrien 10368349SobrienThis section describes some fundamental GAS data types. 10468349Sobrien 10568349Sobrien@menu 10668349Sobrien* Symbols:: The symbolS structure 10768349Sobrien* Expressions:: The expressionS structure 10868349Sobrien* Fixups:: The fixS structure 10968349Sobrien* Frags:: The fragS structure 11068349Sobrien@end menu 11168349Sobrien 11268349Sobrien@node Symbols 11368349Sobrien@subsection Symbols 11468349Sobrien@cindex internals, symbols 11568349Sobrien@cindex symbols, internal 11668349Sobrien@cindex symbolS structure 11768349Sobrien 11868349SobrienThe definition for @code{struct symbol}, also known as @code{symbolS}, is 11968349Sobrienlocated in @file{struc-symbol.h}. Symbol structures contain the following 12068349Sobrienfields: 12168349Sobrien 12268349Sobrien@table @code 12368349Sobrien@item sy_value 12468349SobrienThis is an @code{expressionS} that describes the value of the symbol. It might 12568349Sobrienrefer to one or more other symbols; if so, its true value may not be known 12668349Sobrienuntil @code{resolve_symbol_value} is called in @code{write_object_file}. 12768349Sobrien 12868349SobrienThe expression is often simply a constant. Before @code{resolve_symbol_value} 12968349Sobrienis called, the value is the offset from the frag (@pxref{Frags}). Afterward, 13068349Sobrienthe frag address has been added in. 13168349Sobrien 13268349Sobrien@item sy_resolved 13368349SobrienThis field is non-zero if the symbol's value has been completely resolved. It 13468349Sobrienis used during the final pass over the symbol table. 13568349Sobrien 13668349Sobrien@item sy_resolving 13768349SobrienThis field is used to detect loops while resolving the symbol's value. 13868349Sobrien 13968349Sobrien@item sy_used_in_reloc 14068349SobrienThis field is non-zero if the symbol is used by a relocation entry. If a local 14168349Sobriensymbol is used in a relocation entry, it must be possible to redirect those 14268349Sobrienrelocations to other symbols, or this symbol cannot be removed from the final 14368349Sobriensymbol list. 14468349Sobrien 14568349Sobrien@item sy_next 14668349Sobrien@itemx sy_previous 14768349SobrienThese pointers to other @code{symbolS} structures describe a singly or doubly 14868349Sobrienlinked list. (If @code{SYMBOLS_NEED_BACKPOINTERS} is not defined, the 14968349Sobrien@code{sy_previous} field will be omitted; @code{SYMBOLS_NEED_BACKPOINTERS} is 15068349Sobrienalways defined if @code{BFD_ASSEMBLER}.) These fields should be accessed with 15168349Sobrienthe @code{symbol_next} and @code{symbol_previous} macros. 15268349Sobrien 15368349Sobrien@item sy_frag 15468349SobrienThis points to the frag (@pxref{Frags}) that this symbol is attached to. 15568349Sobrien 15668349Sobrien@item sy_used 15768349SobrienWhether the symbol is used as an operand or in an expression. Note: Not all of 15868349Sobrienthe backends keep this information accurate; backends which use this bit are 15968349Sobrienresponsible for setting it when a symbol is used in backend routines. 16068349Sobrien 16168349Sobrien@item sy_mri_common 16268349SobrienWhether the symbol is an MRI common symbol created by the @code{COMMON} 16368349Sobrienpseudo-op when assembling in MRI mode. 16468349Sobrien 16568349Sobrien@item bsym 16668349SobrienIf @code{BFD_ASSEMBLER} is defined, this points to the BFD @code{asymbol} that 16768349Sobrienwill be used in writing the object file. 16868349Sobrien 16968349Sobrien@item sy_name_offset 17068349Sobrien(Only used if @code{BFD_ASSEMBLER} is not defined.) This is the position of 17168349Sobrienthe symbol's name in the string table of the object file. On some formats, 17268349Sobrienthis will start at position 4, with position 0 reserved for unnamed symbols. 17368349SobrienThis field is not used until @code{write_object_file} is called. 17468349Sobrien 17568349Sobrien@item sy_symbol 17668349Sobrien(Only used if @code{BFD_ASSEMBLER} is not defined.) This is the 17768349Sobrienformat-specific symbol structure, as it would be written into the object file. 17868349Sobrien 17968349Sobrien@item sy_number 18068349Sobrien(Only used if @code{BFD_ASSEMBLER} is not defined.) This is a 24-bit symbol 18168349Sobriennumber, for use in constructing relocation table entries. 18268349Sobrien 18368349Sobrien@item sy_obj 18468349SobrienThis format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by 18580588Sobrienthat name is defined in @file{obj-format.h}, this field is not defined. 18680588Sobrien 18768349Sobrien@item sy_tc 18868349SobrienThis processor-specific data is of type @code{TC_SYMFIELD_TYPE}. If no macro 18968349Sobrienby that name is defined in @file{targ-cpu.h}, this field is not defined. 19068349Sobrien 19168349Sobrien@item TARGET_SYMBOL_FIELDS 19268349SobrienIf this macro is defined, it defines additional fields in the symbol structure. 19368349SobrienThis macro is obsolete, and should be replaced when possible by uses of 19468349Sobrien@code{OBJ_SYMFIELD_TYPE} and @code{TC_SYMFIELD_TYPE}. 19568349Sobrien@end table 19668349Sobrien 19768349SobrienThere are a number of access routines used to extract the fields of a 19868349Sobrien@code{symbolS} structure. When possible, these routines should be used rather 19968349Sobrienthan referring to the fields directly. These routines will work for any GAS 20068349Sobrienversion. 20168349Sobrien 20268349Sobrien@table @code 20368349Sobrien@item S_SET_VALUE 20468349Sobrien@cindex S_SET_VALUE 20568349SobrienSet the symbol's value. 20668349Sobrien 20768349Sobrien@item S_GET_VALUE 20868349Sobrien@cindex S_GET_VALUE 20968349SobrienGet the symbol's value. This will cause @code{resolve_symbol_value} to be 21068349Sobriencalled if necessary, so @code{S_GET_VALUE} should only be called when it is 21168349Sobriensafe to resolve symbols (i.e., after the entire input file has been read and 21268349Sobrienall symbols have been defined). 21368349Sobrien 21468349Sobrien@item S_SET_SEGMENT 21568349Sobrien@cindex S_SET_SEGMENT 21668349SobrienSet the section of the symbol. 21768349Sobrien 21868349Sobrien@item S_GET_SEGMENT 21968349Sobrien@cindex S_GET_SEGMENT 22068349SobrienGet the symbol's section. 22168349Sobrien 22268349Sobrien@item S_GET_NAME 22368349Sobrien@cindex S_GET_NAME 22468349SobrienGet the name of the symbol. 22568349Sobrien 22668349Sobrien@item S_SET_NAME 22768349Sobrien@cindex S_SET_NAME 22868349SobrienSet the name of the symbol. 22968349Sobrien 23068349Sobrien@item S_IS_EXTERNAL 23168349Sobrien@cindex S_IS_EXTERNAL 23268349SobrienReturn non-zero if the symbol is externally visible. 23368349Sobrien 23468349Sobrien@item S_IS_EXTERN 23568349Sobrien@cindex S_IS_EXTERN 23668349SobrienA synonym for @code{S_IS_EXTERNAL}. Don't use it. 23768349Sobrien 23868349Sobrien@item S_IS_WEAK 23974784Sobrien@cindex S_IS_WEAK 24074784SobrienReturn non-zero if the symbol is weak. 24174784Sobrien 24274784Sobrien@item S_IS_COMMON 24374784Sobrien@cindex S_IS_COMMON 24474784SobrienReturn non-zero if this is a common symbol. Common symbols are sometimes 24574784Sobrienrepresented as undefined symbols with a value, in which case this function will 24674784Sobriennot be reliable. 24774784Sobrien 24875937Sobrien@item S_IS_DEFINED 24975937Sobrien@cindex S_IS_DEFINED 25075937SobrienReturn non-zero if this symbol is defined. This function is not reliable when 25175937Sobriencalled on a common symbol. 25275937Sobrien 253103373Sobrien@item S_IS_DEBUG 254103373Sobrien@cindex S_IS_DEBUG 255103373SobrienReturn non-zero if this is a debugging symbol. 256103373Sobrien 257103373Sobrien@item S_IS_LOCAL 258103373Sobrien@cindex S_IS_LOCAL 259Return non-zero if this is a local assembler symbol which should not be 260included in the final symbol table. Note that this is not the opposite of 261@code{S_IS_EXTERNAL}. The @samp{-L} assembler option affects the return value 262of this function. 263 264@item S_SET_EXTERNAL 265@cindex S_SET_EXTERNAL 266Mark the symbol as externally visible. 267 268@item S_CLEAR_EXTERNAL 269@cindex S_CLEAR_EXTERNAL 270Mark the symbol as not externally visible. 271 272@item S_SET_WEAK 273@cindex S_SET_WEAK 274Mark the symbol as weak. 275 276@item S_GET_TYPE 277@item S_GET_DESC 278@item S_GET_OTHER 279@cindex S_GET_TYPE 280@cindex S_GET_DESC 281@cindex S_GET_OTHER 282Get the @code{type}, @code{desc}, and @code{other} fields of the symbol. These 283are only defined for object file formats for which they make sense (primarily 284a.out). 285 286@item S_SET_TYPE 287@item S_SET_DESC 288@item S_SET_OTHER 289@cindex S_SET_TYPE 290@cindex S_SET_DESC 291@cindex S_SET_OTHER 292Set the @code{type}, @code{desc}, and @code{other} fields of the symbol. These 293are only defined for object file formats for which they make sense (primarily 294a.out). 295 296@item S_GET_SIZE 297@cindex S_GET_SIZE 298Get the size of a symbol. This is only defined for object file formats for 299which it makes sense (primarily ELF). 300 301@item S_SET_SIZE 302@cindex S_SET_SIZE 303Set the size of a symbol. This is only defined for object file formats for 304which it makes sense (primarily ELF). 305@end table 306 307@node Expressions 308@subsection Expressions 309@cindex internals, expressions 310@cindex expressions, internal 311@cindex expressionS structure 312 313Expressions are stored in an @code{expressionS} structure. The structure is 314defined in @file{expr.h}. 315 316@cindex expression 317The macro @code{expression} will create an @code{expressionS} structure based 318on the text found at the global variable @code{input_line_pointer}. 319 320@cindex make_expr_symbol 321@cindex expr_symbol_where 322A single @code{expressionS} structure can represent a single operation. 323Complex expressions are formed by creating @dfn{expression symbols} and 324combining them in @code{expressionS} structures. An expression symbol is 325created by calling @code{make_expr_symbol}. An expression symbol should 326naturally never appear in a symbol table, and the implementation of 327@code{S_IS_LOCAL} (@pxref{Symbols}) reflects that. The function 328@code{expr_symbol_where} returns non-zero if a symbol is an expression symbol, 329and also returns the file and line for the expression which caused it to be 330created. 331 332The @code{expressionS} structure has two symbol fields, a number field, an 333operator field, and a field indicating whether the number is unsigned. 334 335The operator field is of type @code{operatorT}, and describes how to interpret 336the other fields; see the definition in @file{expr.h} for the possibilities. 337 338An @code{operatorT} value of @code{O_big} indicates either a floating point 339number, stored in the global variable @code{generic_floating_point_number}, or 340an integer to large to store in an @code{offsetT} type, stored in the global 341array @code{generic_bignum}. This rather inflexible approach makes it 342impossible to use floating point numbers or large expressions in complex 343expressions. 344 345@node Fixups 346@subsection Fixups 347@cindex internals, fixups 348@cindex fixups 349@cindex fixS structure 350 351A @dfn{fixup} is basically anything which can not be resolved in the first 352pass. Sometimes a fixup can be resolved by the end of the assembly; if not, 353the fixup becomes a relocation entry in the object file. 354 355@cindex fix_new 356@cindex fix_new_exp 357A fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both 358take a frag (@pxref{Frags}), a position within the frag, a size, an indication 359of whether the fixup is PC relative, and a type. In a @code{BFD_ASSEMBLER} 360GAS, the type is nominally a @code{bfd_reloc_code_real_type}, but several 361targets use other type codes to represent fixups that can not be described as 362relocations. 363 364The @code{fixS} structure has a number of fields, several of which are obsolete 365or are only used by a particular target. The important fields are: 366 367@table @code 368@item fx_frag 369The frag (@pxref{Frags}) this fixup is in. 370 371@item fx_where 372The location within the frag where the fixup occurs. 373 374@item fx_addsy 375The symbol this fixup is against. Typically, the value of this symbol is added 376into the object contents. This may be NULL. 377 378@item fx_subsy 379The value of this symbol is subtracted from the object contents. This is 380normally NULL. 381 382@item fx_offset 383A number which is added into the fixup. 384 385@item fx_addnumber 386Some CPU backends use this field to convey information between 387@code{md_apply_fix} and @code{tc_gen_reloc}. The machine independent code does 388not use it. 389 390@item fx_next 391The next fixup in the section. 392 393@item fx_r_type 394The type of the fixup. This field is only defined if @code{BFD_ASSEMBLER}, or 395if the target defines @code{NEED_FX_R_TYPE}. 396 397@item fx_size 398The size of the fixup. This is mostly used for error checking. 399 400@item fx_pcrel 401Whether the fixup is PC relative. 402 403@item fx_done 404Non-zero if the fixup has been applied, and no relocation entry needs to be 405generated. 406 407@item fx_file 408@itemx fx_line 409The file and line where the fixup was created. 410 411@item tc_fix_data 412This has the type @code{TC_FIX_TYPE}, and is only defined if the target defines 413that macro. 414@end table 415 416@node Frags 417@subsection Frags 418@cindex internals, frags 419@cindex frags 420@cindex fragS structure. 421 422The @code{fragS} structure is defined in @file{as.h}. Each frag represents a 423portion of the final object file. As GAS reads the source file, it creates 424frags to hold the data that it reads. At the end of the assembly the frags and 425fixups are processed to produce the final contents. 426 427@table @code 428@item fr_address 429The address of the frag. This is not set until the assembler rescans the list 430of all frags after the entire input file is parsed. The function 431@code{relax_segment} fills in this field. 432 433@item fr_next 434Pointer to the next frag in this (sub)section. 435 436@item fr_fix 437Fixed number of characters we know we're going to emit to the output file. May 438be zero. 439 440@item fr_var 441Variable number of characters we may output, after the initial @code{fr_fix} 442characters. May be zero. 443 444@item fr_offset 445The interpretation of this field is controlled by @code{fr_type}. Generally, 446if @code{fr_var} is non-zero, this is a repeat count: the @code{fr_var} 447characters are output @code{fr_offset} times. 448 449@item line 450Holds line number info when an assembler listing was requested. 451 452@item fr_type 453Relaxation state. This field indicates the interpretation of @code{fr_offset}, 454@code{fr_symbol} and the variable-length tail of the frag, as well as the 455treatment it gets in various phases of processing. It does not affect the 456initial @code{fr_fix} characters; they are always supposed to be output 457verbatim (fixups aside). See below for specific values this field can have. 458 459@item fr_subtype 460Relaxation substate. If the macro @code{md_relax_frag} isn't defined, this is 461assumed to be an index into @code{TC_GENERIC_RELAX_TABLE} for the generic 462relaxation code to process (@pxref{Relaxation}). If @code{md_relax_frag} is 463defined, this field is available for any use by the CPU-specific code. 464 465@item fr_symbol 466This normally indicates the symbol to use when relaxing the frag according to 467@code{fr_type}. 468 469@item fr_opcode 470Points to the lowest-addressed byte of the opcode, for use in relaxation. 471 472@item tc_frag_data 473Target specific fragment data of type TC_FRAG_TYPE. 474Only present if @code{TC_FRAG_TYPE} is defined. 475 476@item fr_file 477@itemx fr_line 478The file and line where this frag was last modified. 479 480@item fr_literal 481Declared as a one-character array, this last field grows arbitrarily large to 482hold the actual contents of the frag. 483@end table 484 485These are the possible relaxation states, provided in the enumeration type 486@code{relax_stateT}, and the interpretations they represent for the other 487fields: 488 489@table @code 490@item rs_align 491@itemx rs_align_code 492The start of the following frag should be aligned on some boundary. In this 493frag, @code{fr_offset} is the logarithm (base 2) of the alignment in bytes. 494(For example, if alignment on an 8-byte boundary were desired, @code{fr_offset} 495would have a value of 3.) The variable characters indicate the fill pattern to 496be used. The @code{fr_subtype} field holds the maximum number of bytes to skip 497when doing this alignment. If more bytes are needed, the alignment is not 498done. An @code{fr_subtype} value of 0 means no maximum, which is the normal 499case. Target backends can use @code{rs_align_code} to handle certain types of 500alignment differently. 501 502@item rs_broken_word 503This indicates that ``broken word'' processing should be done (@pxref{Broken 504words}). If broken word processing is not necessary on the target machine, 505this enumerator value will not be defined. 506 507@item rs_cfa 508This state is used to implement exception frame optimizations. The 509@code{fr_symbol} is an expression symbol for the subtraction which may be 510relaxed. The @code{fr_opcode} field holds the frag for the preceding command 511byte. The @code{fr_offset} field holds the offset within that frag. The 512@code{fr_subtype} field is used during relaxation to hold the current size of 513the frag. 514 515@item rs_fill 516The variable characters are to be repeated @code{fr_offset} times. If 517@code{fr_offset} is 0, this frag has a length of @code{fr_fix}. Most frags 518have this type. 519 520@item rs_leb128 521This state is used to implement the DWARF ``little endian base 128'' 522variable length number format. The @code{fr_symbol} is always an expression 523symbol, as constant expressions are emitted directly. The @code{fr_offset} 524field is used during relaxation to hold the previous size of the number so 525that we can determine if the fragment changed size. 526 527@item rs_machine_dependent 528Displacement relaxation is to be done on this frag. The target is indicated by 529@code{fr_symbol} and @code{fr_offset}, and @code{fr_subtype} indicates the 530particular machine-specific addressing mode desired. @xref{Relaxation}. 531 532@item rs_org 533The start of the following frag should be pushed back to some specific offset 534within the section. (Some assemblers use the value as an absolute address; GAS 535does not handle final absolute addresses, but rather requires that the linker 536set them.) The offset is given by @code{fr_symbol} and @code{fr_offset}; one 537character from the variable-length tail is used as the fill character. 538@end table 539 540@cindex frchainS structure 541A chain of frags is built up for each subsection. The data structure 542describing a chain is called a @code{frchainS}, and contains the following 543fields: 544 545@table @code 546@item frch_root 547Points to the first frag in the chain. May be NULL if there are no frags in 548this chain. 549@item frch_last 550Points to the last frag in the chain, or NULL if there are none. 551@item frch_next 552Next in the list of @code{frchainS} structures. 553@item frch_seg 554Indicates the section this frag chain belongs to. 555@item frch_subseg 556Subsection (subsegment) number of this frag chain. 557@item fix_root, fix_tail 558(Defined only if @code{BFD_ASSEMBLER} is defined). Point to first and last 559@code{fixS} structures associated with this subsection. 560@item frch_obstack 561Not currently used. Intended to be used for frag allocation for this 562subsection. This should reduce frag generation caused by switching sections. 563@item frch_frag_now 564The current frag for this subsegment. 565@end table 566 567A @code{frchainS} corresponds to a subsection; each section has a list of 568@code{frchainS} records associated with it. In most cases, only one subsection 569of each section is used, so the list will only be one element long, but any 570processing of frag chains should be prepared to deal with multiple chains per 571section. 572 573After the input files have been completely processed, and no more frags are to 574be generated, the frag chains are joined into one per section for further 575processing. After this point, it is safe to operate on one chain per section. 576 577The assembler always has a current frag, named @code{frag_now}. More space is 578allocated for the current frag using the @code{frag_more} function; this 579returns a pointer to the amount of requested space. Relaxing is done using 580variant frags allocated by @code{frag_var} or @code{frag_variant} 581(@pxref{Relaxation}). 582 583@node GAS processing 584@section What GAS does when it runs 585@cindex internals, overview 586 587This is a quick look at what an assembler run looks like. 588 589@itemize @bullet 590@item 591The assembler initializes itself by calling various init routines. 592 593@item 594For each source file, the @code{read_a_source_file} function reads in the file 595and parses it. The global variable @code{input_line_pointer} points to the 596current text; it is guaranteed to be correct up to the end of the line, but not 597farther. 598 599@item 600For each line, the assembler passes labels to the @code{colon} function, and 601isolates the first word. If it looks like a pseudo-op, the word is looked up 602in the pseudo-op hash table @code{po_hash} and dispatched to a pseudo-op 603routine. Otherwise, the target dependent @code{md_assemble} routine is called 604to parse the instruction. 605 606@item 607When pseudo-ops or instructions output data, they add it to a frag, calling 608@code{frag_more} to get space to store it in. 609 610@item 611Pseudo-ops and instructions can also output fixups created by @code{fix_new} or 612@code{fix_new_exp}. 613 614@item 615For certain targets, instructions can create variant frags which are used to 616store relaxation information (@pxref{Relaxation}). 617 618@item 619When the input file is finished, the @code{write_object_file} routine is 620called. It assigns addresses to all the frags (@code{relax_segment}), resolves 621all the fixups (@code{fixup_segment}), resolves all the symbol values (using 622@code{resolve_symbol_value}), and finally writes out the file (in the 623@code{BFD_ASSEMBLER} case, this is done by simply calling @code{bfd_close}). 624@end itemize 625 626@node Porting GAS 627@section Porting GAS 628@cindex porting 629 630Each GAS target specifies two main things: the CPU file and the object format 631file. Two main switches in the @file{configure.in} file handle this. The 632first switches on CPU type to set the shell variable @code{cpu_type}. The 633second switches on the entire target to set the shell variable @code{fmt}. 634 635The configure script uses the value of @code{cpu_type} to select two files in 636the @file{config} directory: @file{tc-@var{CPU}.c} and @file{tc-@var{CPU}.h}. 637The configuration process will create a file named @file{targ-cpu.h} in the 638build directory which includes @file{tc-@var{CPU}.h}. 639 640The configure script also uses the value of @code{fmt} to select two files: 641@file{obj-@var{fmt}.c} and @file{obj-@var{fmt}.h}. The configuration process 642will create a file named @file{obj-format.h} in the build directory which 643includes @file{obj-@var{fmt}.h}. 644 645You can also set the emulation in the configure script by setting the @code{em} 646variable. Normally the default value of @samp{generic} is fine. The 647configuration process will create a file named @file{targ-env.h} in the build 648directory which includes @file{te-@var{em}.h}. 649 650Porting GAS to a new CPU requires writing the @file{tc-@var{CPU}} files. 651Porting GAS to a new object file format requires writing the 652@file{obj-@var{fmt}} files. There is sometimes some interaction between these 653two files, but it is normally minimal. 654 655The best approach is, of course, to copy existing files. The documentation 656below assumes that you are looking at existing files to see usage details. 657 658These interfaces have grown over time, and have never been carefully thought 659out or designed. Nothing about the interfaces described here is cast in stone. 660It is possible that they will change from one version of the assembler to the 661next. Also, new macros are added all the time as they are needed. 662 663@menu 664* CPU backend:: Writing a CPU backend 665* Object format backend:: Writing an object format backend 666* Emulations:: Writing emulation files 667@end menu 668 669@node CPU backend 670@subsection Writing a CPU backend 671@cindex CPU backend 672@cindex @file{tc-@var{CPU}} 673 674The CPU backend files are the heart of the assembler. They are the only parts 675of the assembler which actually know anything about the instruction set of the 676processor. 677 678You must define a reasonably small list of macros and functions in the CPU 679backend files. You may define a large number of additional macros in the CPU 680backend files, not all of which are documented here. You must, of course, 681define macros in the @file{.h} file, which is included by every assembler 682source file. You may define the functions as macros in the @file{.h} file, or 683as functions in the @file{.c} file. 684 685@table @code 686@item TC_@var{CPU} 687@cindex TC_@var{CPU} 688By convention, you should define this macro in the @file{.h} file. For 689example, @file{tc-m68k.h} defines @code{TC_M68K}. You might have to use this 690if it is necessary to add CPU specific code to the object format file. 691 692@item TARGET_FORMAT 693This macro is the BFD target name to use when creating the output file. This 694will normally depend upon the @code{OBJ_@var{FMT}} macro. 695 696@item TARGET_ARCH 697This macro is the BFD architecture to pass to @code{bfd_set_arch_mach}. 698 699@item TARGET_MACH 700This macro is the BFD machine number to pass to @code{bfd_set_arch_mach}. If 701it is not defined, GAS will use 0. 702 703@item TARGET_BYTES_BIG_ENDIAN 704You should define this macro to be non-zero if the target is big endian, and 705zero if the target is little endian. 706 707@item md_shortopts 708@itemx md_longopts 709@itemx md_longopts_size 710@itemx md_parse_option 711@itemx md_show_usage 712@cindex md_shortopts 713@cindex md_longopts 714@cindex md_longopts_size 715@cindex md_parse_option 716@cindex md_show_usage 717GAS uses these variables and functions during option processing. 718@code{md_shortopts} is a @code{const char *} which GAS adds to the machine 719independent string passed to @code{getopt}. @code{md_longopts} is a 720@code{struct option []} which GAS adds to the machine independent long options 721passed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in 722@file{as.h}, as the start of a set of long option indices, if necessary. 723@code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}. 724GAS will call @code{md_parse_option} whenever @code{getopt} returns an 725unrecognized code, presumably indicating a special code value which appears in 726@code{md_longopts}. GAS will call @code{md_show_usage} when a usage message is 727printed; it should print a description of the machine specific options. 728 729@item md_begin 730@cindex md_begin 731GAS will call this function at the start of the assembly, after the command 732line arguments have been parsed and all the machine independent initializations 733have been completed. 734 735@item md_cleanup 736@cindex md_cleanup 737If you define this macro, GAS will call it at the end of each input file. 738 739@item md_assemble 740@cindex md_assemble 741GAS will call this function for each input line which does not contain a 742pseudo-op. The argument is a null terminated string. The function should 743assemble the string as an instruction with operands. Normally 744@code{md_assemble} will do this by calling @code{frag_more} and writing out 745some bytes (@pxref{Frags}). @code{md_assemble} will call @code{fix_new} to 746create fixups as needed (@pxref{Fixups}). Targets which need to do special 747purpose relaxation will call @code{frag_var}. 748 749@item md_pseudo_table 750@cindex md_pseudo_table 751This is a const array of type @code{pseudo_typeS}. It is a mapping from 752pseudo-op names to functions. You should use this table to implement 753pseudo-ops which are specific to the CPU. 754 755@item tc_conditional_pseudoop 756@cindex tc_conditional_pseudoop 757If this macro is defined, GAS will call it with a @code{pseudo_typeS} argument. 758It should return non-zero if the pseudo-op is a conditional which controls 759whether code is assembled, such as @samp{.if}. GAS knows about the normal 760conditional pseudo-ops,and you should normally not have to define this macro. 761 762@item comment_chars 763@cindex comment_chars 764This is a null terminated @code{const char} array of characters which start a 765comment. 766 767@item tc_comment_chars 768@cindex tc_comment_chars 769If this macro is defined, GAS will use it instead of @code{comment_chars}. 770 771@item line_comment_chars 772@cindex line_comment_chars 773This is a null terminated @code{const char} array of characters which start a 774comment when they appear at the start of a line. 775 776@item line_separator_chars 777@cindex line_separator_chars 778This is a null terminated @code{const char} array of characters which separate 779lines (the semicolon is such a character by default, and need not be listed in 780this array). 781 782@item EXP_CHARS 783@cindex EXP_CHARS 784This is a null terminated @code{const char} array of characters which may be 785used as the exponent character in a floating point number. This is normally 786@code{"eE"}. 787 788@item FLT_CHARS 789@cindex FLT_CHARS 790This is a null terminated @code{const char} array of characters which may be 791used to indicate a floating point constant. A zero followed by one of these 792characters is assumed to be followed by a floating point number; thus they 793operate the way that @code{0x} is used to indicate a hexadecimal constant. 794Usually this includes @samp{r} and @samp{f}. 795 796@item LEX_AT 797@cindex LEX_AT 798You may define this macro to the lexical type of the @kbd{@}} character. The 799default is zero. 800 801Lexical types are a combination of @code{LEX_NAME} and @code{LEX_BEGIN_NAME}, 802both defined in @file{read.h}. @code{LEX_NAME} indicates that the character 803may appear in a name. @code{LEX_BEGIN_NAME} indicates that the character may 804appear at the beginning of a nem. 805 806@item LEX_BR 807@cindex LEX_BR 808You may define this macro to the lexical type of the brace characters @kbd{@{}, 809@kbd{@}}, @kbd{[}, and @kbd{]}. The default value is zero. 810 811@item LEX_PCT 812@cindex LEX_PCT 813You may define this macro to the lexical type of the @kbd{%} character. The 814default value is zero. 815 816@item LEX_QM 817@cindex LEX_QM 818You may define this macro to the lexical type of the @kbd{?} character. The 819default value it zero. 820 821@item LEX_DOLLAR 822@cindex LEX_DOLLAR 823You may define this macro to the lexical type of the @kbd{$} character. The 824default value is @code{LEX_NAME | LEX_BEGIN_NAME}. 825 826@item SINGLE_QUOTE_STRINGS 827@cindex SINGLE_QUOTE_STRINGS 828If you define this macro, GAS will treat single quotes as string delimiters. 829Normally only double quotes are accepted as string delimiters. 830 831@item NO_STRING_ESCAPES 832@cindex NO_STRING_ESCAPES 833If you define this macro, GAS will not permit escape sequences in a string. 834 835@item ONLY_STANDARD_ESCAPES 836@cindex ONLY_STANDARD_ESCAPES 837If you define this macro, GAS will warn about the use of nonstandard escape 838sequences in a string. 839 840@item md_start_line_hook 841@cindex md_start_line_hook 842If you define this macro, GAS will call it at the start of each line. 843 844@item LABELS_WITHOUT_COLONS 845@cindex LABELS_WITHOUT_COLONS 846If you define this macro, GAS will assume that any text at the start of a line 847is a label, even if it does not have a colon. 848 849@item TC_START_LABEL 850@cindex TC_START_LABEL 851You may define this macro to control what GAS considers to be a label. The 852default definition is to accept any name followed by a colon character. 853 854@item NO_PSEUDO_DOT 855@cindex NO_PSEUDO_DOT 856If you define this macro, GAS will not require pseudo-ops to start with a 857@kbd{.} character. 858 859@item TC_EQUAL_IN_INSN 860@cindex TC_EQUAL_IN_INSN 861If you define this macro, it should return nonzero if the instruction is 862permitted to contain an @kbd{=} character. GAS will use this to decide if a 863@kbd{=} is an assignment or an instruction. 864 865@item TC_EOL_IN_INSN 866@cindex TC_EOL_IN_INSN 867If you define this macro, it should return nonzero if the current input line 868pointer should be treated as the end of a line. 869 870@item md_parse_name 871@cindex md_parse_name 872If this macro is defined, GAS will call it for any symbol found in an 873expression. You can define this to handle special symbols in a special way. 874If a symbol always has a certain value, you should normally enter it in the 875symbol table, perhaps using @code{reg_section}. 876 877@item md_undefined_symbol 878@cindex md_undefined_symbol 879GAS will call this function when a symbol table lookup fails, before it 880creates a new symbol. Typically this would be used to supply symbols whose 881name or value changes dynamically, possibly in a context sensitive way. 882Predefined symbols with fixed values, such as register names or condition 883codes, are typically entered directly into the symbol table when @code{md_begin} 884is called. 885 886@item md_operand 887@cindex md_operand 888GAS will call this function for any expression that can not be recognized. 889When the function is called, @code{input_line_pointer} will point to the start 890of the expression. 891 892@item tc_unrecognized_line 893@cindex tc_unrecognized_line 894If you define this macro, GAS will call it when it finds a line that it can not 895parse. 896 897@item md_do_align 898@cindex md_do_align 899You may define this macro to handle an alignment directive. GAS will call it 900when the directive is seen in the input file. For example, the i386 backend 901uses this to generate efficient nop instructions of varying lengths, depending 902upon the number of bytes that the alignment will skip. 903 904@item HANDLE_ALIGN 905@cindex HANDLE_ALIGN 906You may define this macro to do special handling for an alignment directive. 907GAS will call it at the end of the assembly. 908 909@item md_flush_pending_output 910@cindex md_flush_pending_output 911If you define this macro, GAS will call it each time it skips any space because of a 912space filling or alignment or data allocation pseudo-op. 913 914@item TC_PARSE_CONS_EXPRESSION 915@cindex TC_PARSE_CONS_EXPRESSION 916You may define this macro to parse an expression used in a data allocation 917pseudo-op such as @code{.word}. You can use this to recognize relocation 918directives that may appear in such directives. 919 920@item BITFIELD_CONS_EXPRESSION 921@cindex BITFIELD_CONS_EXPRESSION 922If you define this macro, GAS will recognize bitfield instructions in data 923allocation pseudo-ops, as used on the i960. 924 925@item REPEAT_CONS_EXPRESSION 926@cindex REPEAT_CONS_EXPRESSION 927If you define this macro, GAS will recognize repeat counts in data allocation 928pseudo-ops, as used on the MIPS. 929 930@item md_cons_align 931@cindex md_cons_align 932You may define this macro to do any special alignment before a data allocation 933pseudo-op. 934 935@item TC_CONS_FIX_NEW 936@cindex TC_CONS_FIX_NEW 937You may define this macro to generate a fixup for a data allocation pseudo-op. 938 939@item TC_INIT_FIX_DATA (@var{fixp}) 940@cindex TC_INIT_FIX_DATA 941A C statement to initialize the target specific fields of fixup @var{fixp}. 942These fields are defined with the @code{TC_FIX_TYPE} macro. 943 944@item TC_FIX_DATA_PRINT (@var{stream}, @var{fixp}) 945@cindex TC_FIX_DATA_PRINT 946A C statement to output target specific debugging information for 947fixup @var{fixp} to @var{stream}. This macro is called by @code{print_fixup}. 948 949@item TC_FRAG_INIT (@var{fragp}) 950@cindex TC_FRAG_INIT 951A C statement to initialize the target specific fields of frag @var{fragp}. 952These fields are defined with the @code{TC_FRAG_TYPE} macro. 953 954@item md_number_to_chars 955@cindex md_number_to_chars 956This should just call either @code{number_to_chars_bigendian} or 957@code{number_to_chars_littleendian}, whichever is appropriate. On targets like 958the MIPS which support options to change the endianness, which function to call 959is a runtime decision. On other targets, @code{md_number_to_chars} can be a 960simple macro. 961 962@item md_reloc_size 963@cindex md_reloc_size 964This variable is only used in the original version of gas (not 965@code{BFD_ASSEMBLER} and not @code{MANY_SEGMENTS}). It holds the size of a 966relocation entry. 967 968@item WORKING_DOT_WORD 969@itemx md_short_jump_size 970@itemx md_long_jump_size 971@itemx md_create_short_jump 972@itemx md_create_long_jump 973@cindex WORKING_DOT_WORD 974@cindex md_short_jump_size 975@cindex md_long_jump_size 976@cindex md_create_short_jump 977@cindex md_create_long_jump 978If @code{WORKING_DOT_WORD} is defined, GAS will not do broken word processing 979(@pxref{Broken words}). Otherwise, you should set @code{md_short_jump_size} to 980the size of a short jump (a jump that is just long enough to jump around a long 981jmp) and @code{md_long_jump_size} to the size of a long jump (a jump that can 982go anywhere in the function), You should define @code{md_create_short_jump} to 983create a short jump around a long jump, and define @code{md_create_long_jump} 984to create a long jump. 985 986@item md_estimate_size_before_relax 987@cindex md_estimate_size_before_relax 988This function returns an estimate of the size of a @code{rs_machine_dependent} 989frag before any relaxing is done. It may also create any necessary 990relocations. 991 992@item md_relax_frag 993@cindex md_relax_frag 994This macro may be defined to relax a frag. GAS will call this with the frag 995and the change in size of all previous frags; @code{md_relax_frag} should 996return the change in size of the frag. @xref{Relaxation}. 997 998@item TC_GENERIC_RELAX_TABLE 999@cindex TC_GENERIC_RELAX_TABLE 1000If you do not define @code{md_relax_frag}, you may define 1001@code{TC_GENERIC_RELAX_TABLE} as a table of @code{relax_typeS} structures. The 1002machine independent code knows how to use such a table to relax PC relative 1003references. See @file{tc-m68k.c} for an example. @xref{Relaxation}. 1004 1005@item md_prepare_relax_scan 1006@cindex md_prepare_relax_scan 1007If defined, it is a C statement that is invoked prior to scanning 1008the relax table. 1009 1010@item LINKER_RELAXING_SHRINKS_ONLY 1011@cindex LINKER_RELAXING_SHRINKS_ONLY 1012If you define this macro, and the global variable @samp{linkrelax} is set 1013(because of a command line option, or unconditionally in @code{md_begin}), a 1014@samp{.align} directive will cause extra space to be allocated. The linker can 1015then discard this space when relaxing the section. 1016 1017@item md_convert_frag 1018@cindex md_convert_frag 1019GAS will call this for each rs_machine_dependent fragment. 1020The instruction is completed using the data from the relaxation pass. 1021It may also create any necessary relocations. 1022@xref{Relaxation}. 1023 1024@item md_apply_fix 1025@cindex md_apply_fix 1026GAS will call this for each fixup. It should store the correct value in the 1027object file. 1028 1029@item TC_HANDLES_FX_DONE 1030@cindex TC_HANDLES_FX_DONE 1031If this macro is defined, it means that @code{md_apply_fix} correctly sets the 1032@code{fx_done} field in the fixup. 1033 1034@item tc_gen_reloc 1035@cindex tc_gen_reloc 1036A @code{BFD_ASSEMBLER} GAS will call this to generate a reloc. GAS will pass 1037the resulting reloc to @code{bfd_install_relocation}. This currently works 1038poorly, as @code{bfd_install_relocation} often does the wrong thing, and 1039instances of @code{tc_gen_reloc} have been written to work around the problems, 1040which in turns makes it difficult to fix @code{bfd_install_relocation}. 1041 1042@item RELOC_EXPANSION_POSSIBLE 1043@cindex RELOC_EXPANSION_POSSIBLE 1044If you define this macro, it means that @code{tc_gen_reloc} may return multiple 1045relocation entries for a single fixup. In this case, the return value of 1046@code{tc_gen_reloc} is a pointer to a null terminated array. 1047 1048@item MAX_RELOC_EXPANSION 1049@cindex MAX_RELOC_EXPANSION 1050You must define this if @code{RELOC_EXPANSION_POSSIBLE} is defined; it 1051indicates the largest number of relocs which @code{tc_gen_reloc} may return for 1052a single fixup. 1053 1054@item tc_fix_adjustable 1055@cindex tc_fix_adjustable 1056You may define this macro to indicate whether a fixup against a locally defined 1057symbol should be adjusted to be against the section symbol. It should return a 1058non-zero value if the adjustment is acceptable. 1059 1060@item MD_PCREL_FROM_SECTION 1061@cindex MD_PCREL_FROM_SECTION 1062If you define this macro, it should return the offset between the address of a 1063PC relative fixup and the position from which the PC relative adjustment should 1064be made. On many processors, the base of a PC relative instruction is the next 1065instruction, so this macro would return the length of an instruction. 1066 1067@item md_pcrel_from 1068@cindex md_pcrel_from 1069This is the default value of @code{MD_PCREL_FROM_SECTION}. The difference is 1070that @code{md_pcrel_from} does not take a section argument. 1071 1072@item tc_frob_label 1073@cindex tc_frob_label 1074If you define this macro, GAS will call it each time a label is defined. 1075 1076@item md_section_align 1077@cindex md_section_align 1078GAS will call this function for each section at the end of the assembly, to 1079permit the CPU backend to adjust the alignment of a section. 1080 1081@item tc_frob_section 1082@cindex tc_frob_section 1083If you define this macro, a @code{BFD_ASSEMBLER} GAS will call it for each 1084section at the end of the assembly. 1085 1086@item tc_frob_file_before_adjust 1087@cindex tc_frob_file_before_adjust 1088If you define this macro, GAS will call it after the symbol values are 1089resolved, but before the fixups have been changed from local symbols to section 1090symbols. 1091 1092@item tc_frob_symbol 1093@cindex tc_frob_symbol 1094If you define this macro, GAS will call it for each symbol. You can indicate 1095that the symbol should not be included in the object file by definining this 1096macro to set its second argument to a non-zero value. 1097 1098@item tc_frob_file 1099@cindex tc_frob_file 1100If you define this macro, GAS will call it after the symbol table has been 1101completed, but before the relocations have been generated. 1102 1103@item tc_frob_file_after_relocs 1104If you define this macro, GAS will call it after the relocs have been 1105generated. 1106 1107@item LISTING_HEADER 1108A string to use on the header line of a listing. The default value is simply 1109@code{"GAS LISTING"}. 1110 1111@item LISTING_WORD_SIZE 1112The number of bytes to put into a word in a listing. This affects the way the 1113bytes are clumped together in the listing. For example, a value of 2 might 1114print @samp{1234 5678} where a value of 1 would print @samp{12 34 56 78}. The 1115default value is 4. 1116 1117@item LISTING_LHS_WIDTH 1118The number of words of data to print on the first line of a listing for a 1119particular source line, where each word is @code{LISTING_WORD_SIZE} bytes. The 1120default value is 1. 1121 1122@item LISTING_LHS_WIDTH_SECOND 1123Like @code{LISTING_LHS_WIDTH}, but applying to the second and subsequent line 1124of the data printed for a particular source line. The default value is 1. 1125 1126@item LISTING_LHS_CONT_LINES 1127The maximum number of continuation lines to print in a listing for a particular 1128source line. The default value is 4. 1129 1130@item LISTING_RHS_WIDTH 1131The maximum number of characters to print from one line of the input file. The 1132default value is 100. 1133@end table 1134 1135@node Object format backend 1136@subsection Writing an object format backend 1137@cindex object format backend 1138@cindex @file{obj-@var{fmt}} 1139 1140As with the CPU backend, the object format backend must define a few things, 1141and may define some other things. The interface to the object format backend 1142is generally simpler; most of the support for an object file format consists of 1143defining a number of pseudo-ops. 1144 1145The object format @file{.h} file must include @file{targ-cpu.h}. 1146 1147This section will only define the @code{BFD_ASSEMBLER} version of GAS. It is 1148impossible to support a new object file format using any other version anyhow, 1149as the original GAS version only supports a.out, and the @code{MANY_SEGMENTS} 1150GAS version only supports COFF. 1151 1152@table @code 1153@item OBJ_@var{format} 1154@cindex OBJ_@var{format} 1155By convention, you should define this macro in the @file{.h} file. For 1156example, @file{obj-elf.h} defines @code{OBJ_ELF}. You might have to use this 1157if it is necessary to add object file format specific code to the CPU file. 1158 1159@item obj_begin 1160If you define this macro, GAS will call it at the start of the assembly, after 1161the command line arguments have been parsed and all the machine independent 1162initializations have been completed. 1163 1164@item obj_app_file 1165@cindex obj_app_file 1166If you define this macro, GAS will invoke it when it sees a @code{.file} 1167pseudo-op or a @samp{#} line as used by the C preprocessor. 1168 1169@item OBJ_COPY_SYMBOL_ATTRIBUTES 1170@cindex OBJ_COPY_SYMBOL_ATTRIBUTES 1171You should define this macro to copy object format specific information from 1172one symbol to another. GAS will call it when one symbol is equated to 1173another. 1174 1175@item obj_fix_adjustable 1176@cindex obj_fix_adjustable 1177You may define this macro to indicate whether a fixup against a locally defined 1178symbol should be adjusted to be against the section symbol. It should return a 1179non-zero value if the adjustment is acceptable. 1180 1181@item obj_sec_sym_ok_for_reloc 1182@cindex obj_sec_sym_ok_for_reloc 1183You may define this macro to indicate that it is OK to use a section symbol in 1184a relocateion entry. If it is not, GAS will define a new symbol at the start 1185of a section. 1186 1187@item EMIT_SECTION_SYMBOLS 1188@cindex EMIT_SECTION_SYMBOLS 1189You should define this macro with a zero value if you do not want to include 1190section symbols in the output symbol table. The default value for this macro 1191is one. 1192 1193@item obj_adjust_symtab 1194@cindex obj_adjust_symtab 1195If you define this macro, GAS will invoke it just before setting the symbol 1196table of the output BFD. For example, the COFF support uses this macro to 1197generate a @code{.file} symbol if none was generated previously. 1198 1199@item SEPARATE_STAB_SECTIONS 1200@cindex SEPARATE_STAB_SECTIONS 1201You may define this macro to indicate that stabs should be placed in separate 1202sections, as in ELF. 1203 1204@item INIT_STAB_SECTION 1205@cindex INIT_STAB_SECTION 1206You may define this macro to initialize the stabs section in the output file. 1207 1208@item OBJ_PROCESS_STAB 1209@cindex OBJ_PROCESS_STAB 1210You may define this macro to do specific processing on a stabs entry. 1211 1212@item obj_frob_section 1213@cindex obj_frob_section 1214If you define this macro, GAS will call it for each section at the end of the 1215assembly. 1216 1217@item obj_frob_file_before_adjust 1218@cindex obj_frob_file_before_adjust 1219If you define this macro, GAS will call it after the symbol values are 1220resolved, but before the fixups have been changed from local symbols to section 1221symbols. 1222 1223@item obj_frob_symbol 1224@cindex obj_frob_symbol 1225If you define this macro, GAS will call it for each symbol. You can indicate 1226that the symbol should not be included in the object file by definining this 1227macro to set its second argument to a non-zero value. 1228 1229@item obj_frob_file 1230@cindex obj_frob_file 1231If you define this macro, GAS will call it after the symbol table has been 1232completed, but before the relocations have been generated. 1233 1234@item obj_frob_file_after_relocs 1235If you define this macro, GAS will call it after the relocs have been 1236generated. 1237@end table 1238 1239@node Emulations 1240@subsection Writing emulation files 1241 1242Normally you do not have to write an emulation file. You can just use 1243@file{te-generic.h}. 1244 1245If you do write your own emulation file, it must include @file{obj-format.h}. 1246 1247An emulation file will often define @code{TE_@var{EM}}; this may then be used 1248in other files to change the output. 1249 1250@node Relaxation 1251@section Relaxation 1252@cindex relaxation 1253 1254@dfn{Relaxation} is a generic term used when the size of some instruction or 1255data depends upon the value of some symbol or other data. 1256 1257GAS knows to relax a particular type of PC relative relocation using a table. 1258You can also define arbitrarily complex forms of relaxation yourself. 1259 1260@menu 1261* Relaxing with a table:: Relaxing with a table 1262* General relaxing:: General relaxing 1263@end menu 1264 1265@node Relaxing with a table 1266@subsection Relaxing with a table 1267 1268If you do not define @code{md_relax_frag}, and you do define 1269@code{TC_GENERIC_RELAX_TABLE}, GAS will relax @code{rs_machine_dependent} frags 1270based on the frag subtype and the displacement to some specified target 1271address. The basic idea is that several machines have different addressing 1272modes for instructions that can specify different ranges of values, with 1273successive modes able to access wider ranges, including the entirety of the 1274previous range. Smaller ranges are assumed to be more desirable (perhaps the 1275instruction requires one word instead of two or three); if this is not the 1276case, don't describe the smaller-range, inferior mode. 1277 1278The @code{fr_subtype} field of a frag is an index into a CPU-specific 1279relaxation table. That table entry indicates the range of values that can be 1280stored, the number of bytes that will have to be added to the frag to 1281accomodate the addressing mode, and the index of the next entry to examine if 1282the value to be stored is outside the range accessible by the current 1283addressing mode. The @code{fr_symbol} field of the frag indicates what symbol 1284is to be accessed; the @code{fr_offset} field is added in. 1285 1286If the @code{TC_PCREL_ADJUST} macro is defined, which currently should only happen 1287for the NS32k family, the @code{TC_PCREL_ADJUST} macro is called on the frag to 1288compute an adjustment to be made to the displacement. 1289 1290The value fitted by the relaxation code is always assumed to be a displacement 1291from the current frag. (More specifically, from @code{fr_fix} bytes into the 1292frag.) 1293@ignore 1294This seems kinda silly. What about fitting small absolute values? I suppose 1295@code{md_assemble} is supposed to take care of that, but if the operand is a 1296difference between symbols, it might not be able to, if the difference was not 1297computable yet. 1298@end ignore 1299 1300The end of the relaxation sequence is indicated by a ``next'' value of 0. This 1301means that the first entry in the table can't be used. 1302 1303For some configurations, the linker can do relaxing within a section of an 1304object file. If call instructions of various sizes exist, the linker can 1305determine which should be used in each instance, when a symbol's value is 1306resolved. In order for the linker to avoid wasting space and having to insert 1307no-op instructions, it must be able to expand or shrink the section contents 1308while still preserving intra-section references and meeting alignment 1309requirements. 1310 1311For the i960 using b.out format, no expansion is done; instead, each 1312@samp{.align} directive causes extra space to be allocated, enough that when 1313the linker is relaxing a section and removing unneeded space, it can discard 1314some or all of this extra padding and cause the following data to be correctly 1315aligned. 1316 1317For the H8/300, I think the linker expands calls that can't reach, and doesn't 1318worry about alignment issues; the cpu probably never needs any significant 1319alignment beyond the instruction size. 1320 1321The relaxation table type contains these fields: 1322 1323@table @code 1324@item long rlx_forward 1325Forward reach, must be non-negative. 1326@item long rlx_backward 1327Backward reach, must be zero or negative. 1328@item rlx_length 1329Length in bytes of this addressing mode. 1330@item rlx_more 1331Index of the next-longer relax state, or zero if there is no next relax state. 1332@end table 1333 1334The relaxation is done in @code{relax_segment} in @file{write.c}. The 1335difference in the length fields between the original mode and the one finally 1336chosen by the relaxing code is taken as the size by which the current frag will 1337be increased in size. For example, if the initial relaxing mode has a length 1338of 2 bytes, and because of the size of the displacement, it gets upgraded to a 1339mode with a size of 6 bytes, it is assumed that the frag will grow by 4 bytes. 1340(The initial two bytes should have been part of the fixed portion of the frag, 1341since it is already known that they will be output.) This growth must be 1342effected by @code{md_convert_frag}; it should increase the @code{fr_fix} field 1343by the appropriate size, and fill in the appropriate bytes of the frag. 1344(Enough space for the maximum growth should have been allocated in the call to 1345frag_var as the second argument.) 1346 1347If relocation records are needed, they should be emitted by 1348@code{md_estimate_size_before_relax}. This function should examine the target 1349symbol of the supplied frag and correct the @code{fr_subtype} of the frag if 1350needed. When this function is called, if the symbol has not yet been defined, 1351it will not become defined later; however, its value may still change if the 1352section it is in gets relaxed. 1353 1354Usually, if the symbol is in the same section as the frag (given by the 1355@var{sec} argument), the narrowest likely relaxation mode is stored in 1356@code{fr_subtype}, and that's that. 1357 1358If the symbol is undefined, or in a different section (and therefore moveable 1359to an arbitrarily large distance), the largest available relaxation mode is 1360specified, @code{fix_new} is called to produce the relocation record, 1361@code{fr_fix} is increased to include the relocated field (remember, this 1362storage was allocated when @code{frag_var} was called), and @code{frag_wane} is 1363called to convert the frag to an @code{rs_fill} frag with no variant part. 1364Sometimes changing addressing modes may also require rewriting the instruction. 1365It can be accessed via @code{fr_opcode} or @code{fr_fix}. 1366 1367Sometimes @code{fr_var} is increased instead, and @code{frag_wane} is not 1368called. I'm not sure, but I think this is to keep @code{fr_fix} referring to 1369an earlier byte, and @code{fr_subtype} set to @code{rs_machine_dependent} so 1370that @code{md_convert_frag} will get called. 1371 1372@node General relaxing 1373@subsection General relaxing 1374 1375If using a simple table is not suitable, you may implement arbitrarily complex 1376relaxation semantics yourself. For example, the MIPS backend uses this to emit 1377different instruction sequences depending upon the size of the symbol being 1378accessed. 1379 1380When you assemble an instruction that may need relaxation, you should allocate 1381a frag using @code{frag_var} or @code{frag_variant} with a type of 1382@code{rs_machine_dependent}. You should store some sort of information in the 1383@code{fr_subtype} field so that you can figure out what to do with the frag 1384later. 1385 1386When GAS reaches the end of the input file, it will look through the frags and 1387work out their final sizes. 1388 1389GAS will first call @code{md_estimate_size_before_relax} on each 1390@code{rs_machine_dependent} frag. This function must return an estimated size 1391for the frag. 1392 1393GAS will then loop over the frags, calling @code{md_relax_frag} on each 1394@code{rs_machine_dependent} frag. This function should return the change in 1395size of the frag. GAS will keep looping over the frags until none of the frags 1396changes size. 1397 1398@node Broken words 1399@section Broken words 1400@cindex internals, broken words 1401@cindex broken words 1402 1403Some compilers, including GCC, will sometimes emit switch tables specifying 140416-bit @code{.word} displacements to branch targets, and branch instructions 1405that load entries from that table to compute the target address. If this is 1406done on a 32-bit machine, there is a chance (at least with really large 1407functions) that the displacement will not fit in 16 bits. The assembler 1408handles this using a concept called @dfn{broken words}. This idea is well 1409named, since there is an implied promise that the 16-bit field will in fact 1410hold the specified displacement. 1411 1412If broken word processing is enabled, and a situation like this is encountered, 1413the assembler will insert a jump instruction into the instruction stream, close 1414enough to be reached with the 16-bit displacement. This jump instruction will 1415transfer to the real desired target address. Thus, as long as the @code{.word} 1416value really is used as a displacement to compute an address to jump to, the 1417net effect will be correct (minus a very small efficiency cost). If 1418@code{.word} directives with label differences for values are used for other 1419purposes, however, things may not work properly. For targets which use broken 1420words, the @samp{-K} option will warn when a broken word is discovered. 1421 1422The broken word code is turned off by the @code{WORKING_DOT_WORD} macro. It 1423isn't needed if @code{.word} emits a value large enough to contain an address 1424(or, more correctly, any possible difference between two addresses). 1425 1426@node Internal functions 1427@section Internal functions 1428 1429This section describes basic internal functions used by GAS. 1430 1431@menu 1432* Warning and error messages:: Warning and error messages 1433* Hash tables:: Hash tables 1434@end menu 1435 1436@node Warning and error messages 1437@subsection Warning and error messages 1438 1439@deftypefun @{@} int had_warnings (void) 1440@deftypefunx @{@} int had_errors (void) 1441Returns non-zero if any warnings or errors, respectively, have been printed 1442during this invocation. 1443@end deftypefun 1444 1445@deftypefun @{@} void as_perror (const char *@var{gripe}, const char *@var{filename}) 1446Displays a BFD or system error, then clears the error status. 1447@end deftypefun 1448 1449@deftypefun @{@} void as_tsktsk (const char *@var{format}, ...) 1450@deftypefunx @{@} void as_warn (const char *@var{format}, ...) 1451@deftypefunx @{@} void as_bad (const char *@var{format}, ...) 1452@deftypefunx @{@} void as_fatal (const char *@var{format}, ...) 1453These functions display messages about something amiss with the input file, or 1454internal problems in the assembler itself. The current file name and line 1455number are printed, followed by the supplied message, formatted using 1456@code{vfprintf}, and a final newline. 1457 1458An error indicated by @code{as_bad} will result in a non-zero exit status when 1459the assembler has finished. Calling @code{as_fatal} will result in immediate 1460termination of the assembler process. 1461@end deftypefun 1462 1463@deftypefun @{@} void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...) 1464@deftypefunx @{@} void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...) 1465These variants permit specification of the file name and line number, and are 1466used when problems are detected when reprocessing information saved away when 1467processing some earlier part of the file. For example, fixups are processed 1468after all input has been read, but messages about fixups should refer to the 1469original filename and line number that they are applicable to. 1470@end deftypefun 1471 1472@deftypefun @{@} void fprint_value (FILE *@var{file}, valueT @var{val}) 1473@deftypefunx @{@} void sprint_value (char *@var{buf}, valueT @var{val}) 1474These functions are helpful for converting a @code{valueT} value into printable 1475format, in case it's wider than modes that @code{*printf} can handle. If the 1476type is narrow enough, a decimal number will be produced; otherwise, it will be 1477in hexadecimal. The value itself is not examined to make this determination. 1478@end deftypefun 1479 1480@node Hash tables 1481@subsection Hash tables 1482@cindex hash tables 1483 1484@deftypefun @{@} @{struct hash_control *@} hash_new (void) 1485Creates the hash table control structure. 1486@end deftypefun 1487 1488@deftypefun @{@} void hash_die (struct hash_control *) 1489Destroy a hash table. 1490@end deftypefun 1491 1492@deftypefun @{@} PTR hash_delete (struct hash_control *, const char *) 1493Deletes entry from the hash table, returns the value it had. 1494@end deftypefun 1495 1496@deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR) 1497Updates the value for an entry already in the table, returning the old value. 1498If no entry was found, just returns NULL. 1499@end deftypefun 1500 1501@deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR) 1502Inserting a value already in the table is an error. 1503Returns an error message or NULL. 1504@end deftypefun 1505 1506@deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR) 1507Inserts if the value isn't already present, updates it if it is. 1508@end deftypefun 1509 1510@node Test suite 1511@section Test suite 1512@cindex test suite 1513 1514The test suite is kind of lame for most processors. Often it only checks to 1515see if a couple of files can be assembled without the assembler reporting any 1516errors. For more complete testing, write a test which either examines the 1517assembler listing, or runs @code{objdump} and examines its output. For the 1518latter, the TCL procedure @code{run_dump_test} may come in handy. It takes the 1519base name of a file, and looks for @file{@var{file}.d}. This file should 1520contain as its initial lines a set of variable settings in @samp{#} comments, 1521in the form: 1522 1523@example 1524 #@var{varname}: @var{value} 1525@end example 1526 1527The @var{varname} may be @code{objdump}, @code{nm}, or @code{as}, in which case 1528it specifies the options to be passed to the specified programs. Exactly one 1529of @code{objdump} or @code{nm} must be specified, as that also specifies which 1530program to run after the assembler has finished. If @var{varname} is 1531@code{source}, it specifies the name of the source file; otherwise, 1532@file{@var{file}.s} is used. If @var{varname} is @code{name}, it specifies the 1533name of the test to be used in the @code{pass} or @code{fail} messages. 1534 1535The non-commented parts of the file are interpreted as regular expressions, one 1536per line. Blank lines in the @code{objdump} or @code{nm} output are skipped, 1537as are blank lines in the @code{.d} file; the other lines are tested to see if 1538the regular expression matches the program output. If it does not, the test 1539fails. 1540 1541Note that this means the tests must be modified if the @code{objdump} output 1542style is changed. 1543 1544@bye 1545@c Local Variables: 1546@c fill-column: 79 1547@c End: 1548