internals.texi

基于4个mips核的noc设计

\input texinfo
@c  Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
@c  2001
@c  Free Software Foundation, Inc.
@setfilename internals.info
@node Top
@top Assembler Internals
@raisesections
@cindex internals

This chapter describes the internals of the assembler.  It is incomplete, but
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
* Relaxation::          Relaxation
* Broken words::        Broken words
* Internal functions::  Internal functions
* 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

This section describes some fundamental GAS data types.

@menu
* Symbols::             The symbolS structure
* Expressions::         The expressionS structure
* Fixups::		The fixS structure
* Frags::               The fragS structure
@end menu

@node Symbols
@subsection Symbols
@cindex internals, symbols
@cindex symbols, internal
@cindex symbolS structure

The definition for the symbol structure, @code{symbolS}, is located in
@file{struc-symbol.h}.

In general, the fields of this structure may not be referred to directly.
Instead, you must use one of the accessor functions defined in @file{symbol.h}.
These accessor functions should work for any GAS version.

Symbol structures contain the following fields:

@table @code
@item sy_value
This is an @code{expressionS} that describes the value of the symbol.  It might
refer to one or more other symbols; if so, its true value may not be known
until @code{resolve_symbol_value} is called in @code{write_object_file}.

The expression is often simply a constant.  Before @code{resolve_symbol_value}
is called, the value is the offset from the frag (@pxref{Frags}).  Afterward,
the frag address has been added in.

@item sy_resolved
This field is non-zero if the symbol's value has been completely resolved.  It
is used during the final pass over the symbol table.

@item sy_resolving
This field is used to detect loops while resolving the symbol's value.

@item sy_used_in_reloc
This field is non-zero if the symbol is used by a relocation entry.  If a local
symbol is used in a relocation entry, it must be possible to redirect those
relocations to other symbols, or this symbol cannot be removed from the final
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
the @code{symbol_next} and @code{symbol_previous} macros.

@item sy_frag
This points to the frag (@pxref{Frags}) that this symbol is attached to.

@item sy_used
Whether the symbol is used as an operand or in an expression.  Note: Not all of
the backends keep this information accurate; backends which use this bit are
responsible for setting it when a symbol is used in backend routines.

@item sy_mri_common
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
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.

@item sy_tc
This processor-specific data is of type @code{TC_SYMFIELD_TYPE}.  If no macro
by that name is defined in @file{targ-cpu.h}, this field is not defined.

@end table

Here is a description of the accessor functions.  These should be used rather
than referring to the fields of @code{symbolS} directly.

@table @code
@item S_SET_VALUE
@cindex S_SET_VALUE
Set the symbol's value.

@item S_GET_VALUE
@cindex S_GET_VALUE
Get the symbol's value.  This will cause @code{resolve_symbol_value} to be
called if necessary, so @code{S_GET_VALUE} should only be called when it is
safe to resolve symbols (i.e., after the entire input file has been read and
all symbols have been defined).

@item S_SET_SEGMENT
@cindex S_SET_SEGMENT
Set the section of the symbol.

@item S_GET_SEGMENT
@cindex S_GET_SEGMENT
Get the symbol's section.

@item S_GET_NAME
@cindex S_GET_NAME
Get the name of the symbol.

@item S_SET_NAME
@cindex S_SET_NAME
Set the name of the symbol.

@item S_IS_EXTERNAL
@cindex S_IS_EXTERNAL
Return non-zero if the symbol is externally visible.

@item S_IS_EXTERN
@cindex S_IS_EXTERN
A synonym for @code{S_IS_EXTERNAL}.  Don't use it.

@item S_IS_WEAK
@cindex S_IS_WEAK
Return non-zero if the symbol is weak.

@item S_IS_COMMON
@cindex S_IS_COMMON
Return non-zero if this is a common symbol.  Common symbols are sometimes
represented as undefined symbols with a value, in which case this function will
not be reliable.

@item S_IS_DEFINED
@cindex S_IS_DEFINED
Return non-zero if this symbol is defined.  This function is not reliable when
called on a common symbol.

@item S_IS_DEBUG
@cindex S_IS_DEBUG
Return non-zero if this is a debugging symbol.

@item S_IS_LOCAL
@cindex S_IS_LOCAL
Return non-zero if this is a local assembler symbol which should not be
included in the final symbol table.  Note that this is not the opposite of
@code{S_IS_EXTERNAL}.  The @samp{-L} assembler option affects the return value
of this function.

@item S_SET_EXTERNAL
@cindex S_SET_EXTERNAL
Mark the symbol as externally visible.

@item S_CLEAR_EXTERNAL
@cindex S_CLEAR_EXTERNAL
Mark the symbol as not externally visible.

@item S_SET_WEAK
@cindex S_SET_WEAK
Mark the symbol as weak.

@item S_GET_TYPE
@item S_GET_DESC
@item S_GET_OTHER
@cindex S_GET_TYPE
@cindex S_GET_DESC
@cindex S_GET_OTHER
Get the @code{type}, @code{desc}, and @code{other} fields of the symbol.  These
are only defined for object file formats for which they make sense (primarily
a.out).

@item S_SET_TYPE
@item S_SET_DESC
@item S_SET_OTHER
@cindex S_SET_TYPE
@cindex S_SET_DESC
@cindex S_SET_OTHER
Set the @code{type}, @code{desc}, and @code{other} fields of the symbol.  These
are only defined for object file formats for which they make sense (primarily
a.out).

@item S_GET_SIZE
@cindex S_GET_SIZE
Get the size of a symbol.  This is only defined for object file formats for
which it makes sense (primarily ELF).

@item S_SET_SIZE
@cindex S_SET_SIZE
Set the size of a symbol.  This is only defined for object file formats for
which it makes sense (primarily ELF).

@item symbol_get_value_expression
@cindex symbol_get_value_expression
Get a pointer to an @code{expressionS} structure which represents the value of
the symbol as an expression.

@item symbol_set_value_expression
@cindex symbol_set_value_expression
Set the value of a symbol to an expression.

@item symbol_set_frag
@cindex symbol_set_frag
Set the frag where a symbol is defined.

@item symbol_get_frag
@cindex symbol_get_frag
Get the frag where a symbol is defined.

@item symbol_mark_used
@cindex symbol_mark_used
Mark a symbol as having been used in an expression.

@item symbol_clear_used
@cindex symbol_clear_used
Clear the mark indicating that a symbol was used in an expression.

@item symbol_used_p
@cindex symbol_used_p