diff options
author | Alan Modra <amodra@gmail.com> | 2005-08-11 01:34:12 +0000 |
---|---|---|
committer | Alan Modra <amodra@gmail.com> | 2005-08-11 01:34:12 +0000 |
commit | 829c3ed3b4c01d77c76e0c05dbb9f5a06bf023fb (patch) | |
tree | 03c98b53bf227051d4d340f558d4cd448cf27e08 /gas/doc/internals.texi | |
parent | 7be1c4891a2036c31e706908d43f33f7f59ae5a9 (diff) | |
download | gdb-829c3ed3b4c01d77c76e0c05dbb9f5a06bf023fb.zip gdb-829c3ed3b4c01d77c76e0c05dbb9f5a06bf023fb.tar.gz gdb-829c3ed3b4c01d77c76e0c05dbb9f5a06bf023fb.tar.bz2 |
missed from last commit
Diffstat (limited to 'gas/doc/internals.texi')
-rw-r--r-- | gas/doc/internals.texi | 132 |
1 files changed, 13 insertions, 119 deletions
diff --git a/gas/doc/internals.texi b/gas/doc/internals.texi index fcda0f0..8c8c66e 100644 --- a/gas/doc/internals.texi +++ b/gas/doc/internals.texi @@ -14,7 +14,6 @@ it may help a bit. This chapter is not updated regularly, and it may be out of date. @menu -* GAS versions:: GAS versions * Data types:: Data types * GAS processing:: What GAS does when it runs * Porting GAS:: Porting GAS @@ -24,80 +23,6 @@ This chapter is not updated regularly, and it may be out of date. * Test suite:: Test suite @end menu -@node GAS versions -@section GAS versions - -GAS has acquired layers of code over time. The original GAS only supported the -a.out object file format, with three sections. Support for multiple sections -has been added in two different ways. - -The preferred approach is to use the version of GAS created when the symbol -@code{BFD_ASSEMBLER} is defined. The other versions of GAS are documented for -historical purposes, and to help anybody who has to debug code written for -them. - -The type @code{segT} is used to represent a section in code which must work -with all versions of GAS. - -@menu -* Original GAS:: Original GAS version -* MANY_SEGMENTS:: MANY_SEGMENTS gas version -* BFD_ASSEMBLER:: BFD_ASSEMBLER gas version -@end menu - -@node Original GAS -@subsection Original GAS - -The original GAS only supported the a.out object file format with three -sections: @samp{.text}, @samp{.data}, and @samp{.bss}. This is the version of -GAS that is compiled if neither @code{BFD_ASSEMBLER} nor @code{MANY_SEGMENTS} -is defined. This version of GAS is still used for the m68k-aout target, and -perhaps others. - -This version of GAS should not be used for any new development. - -There is still code that is specific to this version of GAS, notably in -@file{write.c}. There is no way for this code to loop through all the -sections; it simply looks at global variables like @code{text_frag_root} and -@code{data_frag_root}. - -The type @code{segT} is an enum. - -@node MANY_SEGMENTS -@subsection MANY_SEGMENTS gas version -@cindex MANY_SEGMENTS - -The @code{MANY_SEGMENTS} version of gas is only used for COFF. It uses the BFD -library, but it writes out all the data itself using @code{bfd_write}. This -version of gas supports up to 40 normal sections. The section names are stored -in the @code{seg_name} array. Other information is stored in the -@code{segment_info} array. - -The type @code{segT} is an enum. Code that wants to examine all the sections -can use a @code{segT} variable as loop index from @code{SEG_E0} up to but not -including @code{SEG_UNKNOWN}. - -Most of the code specific to this version of GAS is in the file -@file{config/obj-coff.c}, in the portion of that file that is compiled when -@code{BFD_ASSEMBLER} is not defined. - -This version of GAS is still used for several COFF targets. - -@node BFD_ASSEMBLER -@subsection BFD_ASSEMBLER gas version -@cindex BFD_ASSEMBLER - -The preferred version of GAS is the @code{BFD_ASSEMBLER} version. In this -version of GAS, the output file is a normal BFD, and the BFD routines are used -to generate the output. - -@code{BFD_ASSEMBLER} will automatically be used for certain targets, including -those that use the ELF, ECOFF, and SOM object file formats, and also all Alpha, -MIPS, PowerPC, and SPARC targets. You can force the use of -@code{BFD_ASSEMBLER} for other targets with the configure option -@samp{--enable-bfd-assembler}; however, it has not been tested for many -targets, and can not be assumed to work. - @node Data types @section Data types @cindex internals, data types @@ -152,10 +77,8 @@ symbol list. @item sy_next @itemx sy_previous -These pointers to other @code{symbolS} structures describe a singly or doubly -linked list. (If @code{SYMBOLS_NEED_BACKPOINTERS} is not defined, the -@code{sy_previous} field will be omitted; @code{SYMBOLS_NEED_BACKPOINTERS} is -always defined if @code{BFD_ASSEMBLER}.) These fields should be accessed with +These pointers to other @code{symbolS} structures describe a doubly +linked list. These fields should be accessed with the @code{symbol_next} and @code{symbol_previous} macros. @item sy_frag @@ -171,23 +94,9 @@ Whether the symbol is an MRI common symbol created by the @code{COMMON} pseudo-op when assembling in MRI mode. @item bsym -If @code{BFD_ASSEMBLER} is defined, this points to the BFD @code{asymbol} that +This points to the BFD @code{asymbol} that will be used in writing the object file. -@item sy_name_offset -(Only used if @code{BFD_ASSEMBLER} is not defined.) This is the position of -the symbol's name in the string table of the object file. On some formats, -this will start at position 4, with position 0 reserved for unnamed symbols. -This field is not used until @code{write_object_file} is called. - -@item sy_symbol -(Only used if @code{BFD_ASSEMBLER} is not defined.) This is the -format-specific symbol structure, as it would be written into the object file. - -@item sy_number -(Only used if @code{BFD_ASSEMBLER} is not defined.) This is a 24-bit symbol -number, for use in constructing relocation table entries. - @item sy_obj This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by that name is defined in @file{obj-format.h}, this field is not defined. @@ -415,7 +324,7 @@ Set the @code{TC_SYMFIELD_TYPE} field of a symbol. @end table -When @code{BFD_ASSEMBLER} is defined, GAS attempts to store local +GAS attempts to store local symbols--symbols which will not be written to the output file--using a different structure, @code{struct local_symbol}. This structure can only represent symbols whose value is an offset within a frag. @@ -484,8 +393,8 @@ the fixup becomes a relocation entry in the object file. @cindex fix_new_exp A fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both take a frag (@pxref{Frags}), a position within the frag, a size, an indication -of whether the fixup is PC relative, and a type. In a @code{BFD_ASSEMBLER} -GAS, the type is nominally a @code{bfd_reloc_code_real_type}, but several +of whether the fixup is PC relative, and a type. +The type is nominally a @code{bfd_reloc_code_real_type}, but several targets use other type codes to represent fixups that can not be described as relocations. @@ -519,8 +428,7 @@ not use it. The next fixup in the section. @item fx_r_type -The type of the fixup. This field is only defined if @code{BFD_ASSEMBLER}, or -if the target defines @code{NEED_FX_R_TYPE}. +The type of the fixup. @item fx_size The size of the fixup. This is mostly used for error checking. @@ -683,8 +591,7 @@ Indicates the section this frag chain belongs to. @item frch_subseg Subsection (subsegment) number of this frag chain. @item fix_root, fix_tail -(Defined only if @code{BFD_ASSEMBLER} is defined). Point to first and last -@code{fixS} structures associated with this subsection. +Point to first and last @code{fixS} structures associated with this subsection. @item frch_obstack Not currently used. Intended to be used for frag allocation for this subsection. This should reduce frag generation caused by switching sections. @@ -748,8 +655,7 @@ store relaxation information (@pxref{Relaxation}). When the input file is finished, the @code{write_object_file} routine is called. It assigns addresses to all the frags (@code{relax_segment}), resolves all the fixups (@code{fixup_segment}), resolves all the symbol values (using -@code{resolve_symbol_value}), and finally writes out the file (in the -@code{BFD_ASSEMBLER} case, this is done by simply calling @code{bfd_close}). +@code{resolve_symbol_value}), and finally writes out the file. @end itemize @node Porting GAS @@ -1181,12 +1087,6 @@ single precision, @samp{D_PRECISION} for double precision, or The macro has a default definition which returns 0 for all cases. -@item md_reloc_size -@cindex md_reloc_size -This variable is only used in the original version of gas (not -@code{BFD_ASSEMBLER} and not @code{MANY_SEGMENTS}). It holds the size of a -relocation entry. - @item WORKING_DOT_WORD @itemx md_short_jump_size @itemx md_long_jump_size @@ -1347,7 +1247,7 @@ symbol value will be included. For ELF, a suitable definition might simply be @item S_FORCE_RELOC (@var{sym}, @var{strict}) @cindex S_FORCE_RELOC -This macro (or function, for @code{BFD_ASSEMBLER} gas) returns true for symbols +This function returns true for symbols that should not be reduced to section symbols or eliminated from expressions, because they may be overridden by the linker. ie. for symbols that are undefined or common, and when @var{strict} is set, weak, or global (for ELF @@ -1361,7 +1261,7 @@ symbols. If undefined, the default is @code{true} for ELF assemblers, and @item tc_gen_reloc @cindex tc_gen_reloc -A @code{BFD_ASSEMBLER} GAS will call this to generate a reloc. GAS will pass +GAS will call this to generate a reloc. GAS will pass the resulting reloc to @code{bfd_install_relocation}. This currently works poorly, as @code{bfd_install_relocation} often does the wrong thing, and instances of @code{tc_gen_reloc} have been written to work around the problems, @@ -1446,7 +1346,7 @@ whitespace, or concatenated if there is not. @item tc_frob_section @cindex tc_frob_section -If you define this macro, a @code{BFD_ASSEMBLER} GAS will call it for each +If you define this macro, GAS will call it for each section at the end of the assembly. @item tc_frob_file_before_adjust @@ -1562,11 +1462,6 @@ defining a number of pseudo-ops. The object format @file{.h} file must include @file{targ-cpu.h}. -This section will only define the @code{BFD_ASSEMBLER} version of GAS. It is -impossible to support a new object file format using any other version anyhow, -as the original GAS version only supports a.out, and the @code{MANY_SEGMENTS} -GAS version only supports COFF. - @table @code @item OBJ_@var{format} @cindex OBJ_@var{format} @@ -1651,8 +1546,7 @@ generated. @cindex SET_SECTION_RELOCS If you define this, it will be called after the relocations have been set for the section @var{sec}. The list of relocations is in @var{relocs}, and the -number of relocations is in @var{n}. This is only used with -@code{BFD_ASSEMBLER}. +number of relocations is in @var{n}. @end table @node Emulations |