internals.texi

基于4个mips核的noc设计

@item LISTING_HEADER
A string to use on the header line of a listing.  The default value is simply
@code{"GAS LISTING"}.

@item LISTING_WORD_SIZE
The number of bytes to put into a word in a listing.  This affects the way the
bytes are clumped together in the listing.  For example, a value of 2 might
print @samp{1234 5678} where a value of 1 would print @samp{12 34 56 78}.  The
default value is 4.

@item LISTING_LHS_WIDTH
The number of words of data to print on the first line of a listing for a
particular source line, where each word is @code{LISTING_WORD_SIZE} bytes.  The
default value is 1.

@item LISTING_LHS_WIDTH_SECOND
Like @code{LISTING_LHS_WIDTH}, but applying to the second and subsequent line
of the data printed for a particular source line.  The default value is 1.

@item LISTING_LHS_CONT_LINES
The maximum number of continuation lines to print in a listing for a particular
source line.  The default value is 4.

@item LISTING_RHS_WIDTH
The maximum number of characters to print from one line of the input file.  The
default value is 100.

@item TC_COFF_SECTION_DEFAULT_ATTRIBUTES
@cindex TC_COFF_SECTION_DEFAULT_ATTRIBUTES
The COFF @code{.section} directive will use the value of this macro to set
a new section's attributes when a directive has no valid flags or when the
flag is @code{w}. The default value of the macro is @code{SEC_LOAD | SEC_DATA}.

@end table

@node Object format backend
@subsection Writing an object format backend
@cindex object format backend
@cindex @file{obj-@var{fmt}}

As with the CPU backend, the object format backend must define a few things,
and may define some other things.  The interface to the object format backend
is generally simpler; most of the support for an object file format consists of
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}
By convention, you should define this macro in the @file{.h} file.  For
example, @file{obj-elf.h} defines @code{OBJ_ELF}.  You might have to use this
if it is necessary to add object file format specific code to the CPU file.

@item obj_begin
If you define this macro, GAS will call it at the start of the assembly, after
the command line arguments have been parsed and all the machine independent
initializations have been completed.

@item obj_app_file
@cindex obj_app_file
If you define this macro, GAS will invoke it when it sees a @code{.file}
pseudo-op or a @samp{#} line as used by the C preprocessor.

@item OBJ_COPY_SYMBOL_ATTRIBUTES
@cindex OBJ_COPY_SYMBOL_ATTRIBUTES
You should define this macro to copy object format specific information from
one symbol to another.  GAS will call it when one symbol is equated to
another.

@item obj_fix_adjustable
@cindex obj_fix_adjustable
You may define this macro to indicate whether a fixup against a locally defined
symbol should be adjusted to be against the section symbol.  It should return a
non-zero value if the adjustment is acceptable.

@item obj_sec_sym_ok_for_reloc
@cindex obj_sec_sym_ok_for_reloc
You may define this macro to indicate that it is OK to use a section symbol in
a relocateion entry.  If it is not, GAS will define a new symbol at the start
of a section.

@item EMIT_SECTION_SYMBOLS
@cindex EMIT_SECTION_SYMBOLS
You should define this macro with a zero value if you do not want to include
section symbols in the output symbol table.  The default value for this macro
is one.

@item obj_adjust_symtab
@cindex obj_adjust_symtab
If you define this macro, GAS will invoke it just before setting the symbol
table of the output BFD.  For example, the COFF support uses this macro to
generate a @code{.file} symbol if none was generated previously.

@item SEPARATE_STAB_SECTIONS
@cindex SEPARATE_STAB_SECTIONS
You may define this macro to a nonzero value to indicate that stabs should be
placed in separate sections, as in ELF.

@item INIT_STAB_SECTION
@cindex INIT_STAB_SECTION
You may define this macro to initialize the stabs section in the output file.

@item OBJ_PROCESS_STAB
@cindex OBJ_PROCESS_STAB
You may define this macro to do specific processing on a stabs entry.

@item obj_frob_section
@cindex obj_frob_section
If you define this macro, GAS will call it for each section at the end of the
assembly.

@item obj_frob_file_before_adjust
@cindex obj_frob_file_before_adjust
If you define this macro, GAS will call it after the symbol values are
resolved, but before the fixups have been changed from local symbols to section
symbols.

@item obj_frob_symbol
@cindex obj_frob_symbol
If you define this macro, GAS will call it for each symbol.  You can indicate
that the symbol should not be included in the object file by definining this
macro to set its second argument to a non-zero value.

@item obj_frob_file
@cindex obj_frob_file
If you define this macro, GAS will call it after the symbol table has been
completed, but before the relocations have been generated.

@item obj_frob_file_after_relocs
If you define this macro, GAS will call it after the relocs have been
generated.

@item SET_SECTION_RELOCS (@var{sec}, @var{relocs}, @var{n})
@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}.
@end table

@node Emulations
@subsection Writing emulation files

Normally you do not have to write an emulation file.  You can just use
@file{te-generic.h}.

If you do write your own emulation file, it must include @file{obj-format.h}.

An emulation file will often define @code{TE_@var{EM}}; this may then be used
in other files to change the output.

@node Relaxation
@section Relaxation
@cindex relaxation

@dfn{Relaxation} is a generic term used when the size of some instruction or
data depends upon the value of some symbol or other data.

GAS knows to relax a particular type of PC relative relocation using a table.
You can also define arbitrarily complex forms of relaxation yourself.

@menu
* Relaxing with a table::       Relaxing with a table
* General relaxing::            General relaxing
@end menu

@node Relaxing with a table
@subsection Relaxing with a table

If you do not define @code{md_relax_frag}, and you do define
@code{TC_GENERIC_RELAX_TABLE}, GAS will relax @code{rs_machine_dependent} frags
based on the frag subtype and the displacement to some specified target
address.  The basic idea is that several machines have different addressing
modes for instructions that can specify different ranges of values, with
successive modes able to access wider ranges, including the entirety of the
previous range.  Smaller ranges are assumed to be more desirable (perhaps the
instruction requires one word instead of two or three); if this is not the
case, don't describe the smaller-range, inferior mode.

The @code{fr_subtype} field of a frag is an index into a CPU-specific
relaxation table.  That table entry indicates the range of values that can be
stored, the number of bytes that will have to be added to the frag to
accomodate the addressing mode, and the index of the next entry to examine if
the value to be stored is outside the range accessible by the current
addressing mode.  The @code{fr_symbol} field of the frag indicates what symbol
is to be accessed; the @code{fr_offset} field is added in.

If the @code{TC_PCREL_ADJUST} macro is defined, which currently should only happen
for the NS32k family, the @code{TC_PCREL_ADJUST} macro is called on the frag to
compute an adjustment to be made to the displacement.

The value fitted by the relaxation code is always assumed to be a displacement
from the current frag.  (More specifically, from @code{fr_fix} bytes into the
frag.)
@ignore
This seems kinda silly.  What about fitting small absolute values?  I suppose
@code{md_assemble} is supposed to take care of that, but if the operand is a
difference between symbols, it might not be able to, if the difference was not
computable yet.
@end ignore

The end of the relaxation sequence is indicated by a ``next'' value of 0.  This
means that the first entry in the table can't be used.

For some configurations, the linker can do relaxing within a section of an
object file.  If call instructions of various sizes exist, the linker can
determine which should be used in each instance, when a symbol's value is
resolved.  In order for the linker to avoid wasting space and having to insert
no-op instructions, it must be able to expand or shrink the section contents
while still preserving intra-section references and meeting alignment
requirements.

For the i960 using b.out format, no expansion is done; instead, each
@samp{.align} directive causes extra space to be allocated, enough that when
the linker is relaxing a section and removing unneeded space, it can discard
some or all of this extra padding and cause the following data to be correctly
aligned.

For the H8/300, I think the linker expands calls that can't reach, and doesn't
worry about alignment issues; the cpu probably never needs any significant
alignment beyond the instruction size.

The relaxation table type contains these fields:

@table @code
@item long rlx_forward
Forward reach, must be non-negative.
@item long rlx_backward
Backward reach, must be zero or negative.
@item rlx_length
Length in bytes of this addressing mode.
@item rlx_more
Index of the next-longer relax state, or zero if there is no next relax state.
@end table

The relaxation is done in @code{relax_segment} in @file{write.c}.  The
difference in the length fields between the original mode and the one finally
chosen by the relaxing code is taken as the size by which the current frag will
be increased in size.  For example, if the initial relaxing mode has a length
of 2 bytes, and because of the size of the displacement, it gets upgraded to a
mode with a size of 6 bytes, it is assumed that the frag will grow by 4 bytes.
(The initial two bytes should have been part of the fixed portion of the frag,
since it is already known that they will be output.)  This growth must be
effected by @code{md_convert_frag}; it should increase the @code{fr_fix} field
by the appropriate size, and fill in the appropriate bytes of the frag.
(Enough space for the maximum growth should have been allocated in the call to
frag_var as the second argument.)

If relocation records are needed, they should be emitted by
@code{md_estimate_size_before_relax}.  This function should examine the target
symbol of the supplied frag and correct the @code{fr_subtype} of the frag if
needed.  When this function is called, if the symbol has not yet been defined,
it will not become defined later; however, its value may still change if the
section it is in gets relaxed.

Usually, if the symbol is in the same section as the frag (given by the
@var{sec} argument), the narrowest likely relaxation mode is stored in
@code{fr_subtype}, and that's that.

If the symbol is undefined, or in a different section (and therefore moveable
to an arbitrarily large distance), the largest available relaxation mode is
specified, @code{fix_new} is called to produce the relocation record,
@code{fr_fix} is increased to include the relocated field (remember, this
storage was allocated when @code{frag_var} was called), and @code{frag_wane} is
called to convert the frag to an @code{rs_fill} frag with no variant part.
Sometimes changing addressing modes may also require rewriting the instruction.
It can be accessed via @code{fr_opcode} or @code{fr_fix}.

If you generate frags separately for the basic insn opcode and any relaxable
operands, do not call @code{fix_new} thinking you can emit fixups for the
opcode field from the relaxable frag.  It is not garanteed to be the same frag.
If you need to emit fixups for the opcode field from inspection of the
relaxable frag, then you need to generate a common frag for both the basic
opcode and relaxable fields, or you need to provide the frag for the opcode to
pass to @code{fix_new}.  The latter can be done for example by defining
@code{TC_FRAG_TYPE} to include a pointer to it and defining @code{TC_FRAG_INIT}
to set the pointer.

Sometimes @code{fr_var} is increased instead, and @code{frag_wane} is not
called.  I'm not sure, but I think this is to keep @code{fr_fix} referring to
an earlier byte, and @code{fr_subtype} set to @code{rs_machine_dependent} so
that @code{md_convert_frag} will get called.

@node General relaxing
@subsection General relaxing

If using a simple table is not suitable, you may implement arbitrarily complex
relaxation semantics yourself.  For example, the MIPS backend uses this to emit
different instruction sequences depending upon the size of the symbol being
accessed.

When you assemble an instruction that may need relaxation, you should allocate
a frag using @code{frag_var} or @code{frag_variant} with a type of
@code{rs_machine_dependent}.  You should store some sort of information in the
@code{fr_subtype} field so that you can figure out what to do with the frag
later.

When GAS reaches the end of the input file, it will look through the frags and
work out their final sizes.

GAS will first call @code{md_estimate_size_before_relax} on each
@code{rs_machine_dependent} frag.  This function must return an estimated size
for the frag.

GAS will then loop over the frags, calling @code{md_relax_frag} on each
@code{rs_machine_dependent} frag.  This function should return the change in
size of the frag.  GAS will keep looping over the frags until none of the frags
changes size.

@node Broken words
@section Broken words
@cindex internals, broken words
@cindex broken words

Some compilers, including GCC, will sometimes emit switch tables specifying
16-bit @code{.word} displacements to branch targets, and branch instructions
that load entries from that table to compute the target address.  If this is
done on a 32-bit machine, there is a chance (at least with really large
functions) that the displacement will not fit in 16 bits.  The assembler
handles this using a concept called @dfn{broken words}.  This idea is well
named, since there is an implied promise that the 16-bit field will in fact
hold the specified displacement.

If broken word processing is enabled, and a situation like this is encountered,
the assembler will insert a jump ins