Subversion Repositories openrisc_me

\input texinfo

@c  Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,

@c  2001, 2002, 2003, 2004, 2005, 2006

@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

* 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 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 with @var{finalize_syms} non-zero

in @code{write_object_file}.

The expression is often simply a constant.  Before @code{resolve_symbol_value}

is called with @var{finalize_syms} set, 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 doubly

linked list.  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 sy_volatile

Whether the symbol can be re-defined.

@item sy_forward_ref

Whether the symbol's value must only be evaluated upon use.

@item sy_weakrefr

Whether the symbol is a @code{weakref} alias to another symbol.

@item sy_weakrefd

Whether the symbol is or was referenced by one or more @code{weakref} aliases,

and has not had any direct references.

@item bsym

This points to the BFD @code{asymbol} that

will be used in writing the object file.

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

@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, or if it is a @code{weakref} alias or

symbol that has not been strongly referenced.

@item S_IS_WEAKREFR

@cindex S_IS_WEAKREFR

Return non-zero if the symbol is a @code{weakref} alias.

@item S_IS_WEAKREFD

@cindex S_IS_WEAKREFD

Return non-zero if the symbol was aliased by a @code{weakref} alias and has not

had any strong references.

@item S_IS_VOLATILE

@cindex S_IS_VOLATILE

Return non-zero if the symbol may be re-defined. Such symbols get created by

the @code{=} operator, @code{equ}, or @code{set}.

@item S_IS_FORWARD_REF

@cindex S_IS_FORWARD_REF

Return non-zero if the symbol is a forward reference, that is its value must

only be determined upon use.

@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_SET_WEAKREFR

@cindex S_SET_WEAKREFR

Mark the symbol as the referrer in a @code{weakref} directive.  The symbol it

aliases must have been set to the value expression before this point.  If the

alias has already been used, the symbol is marked as used too.

@item S_CLEAR_WEAKREFR

@cindex S_CLEAR_WEAKREFR

Clear the @code{weakref} alias status of a symbol.  This is implicitly called

whenever a symbol is defined or set to a new expression.

@item S_SET_WEAKREFD

@cindex S_SET_WEAKREFD

Mark the symbol as the referred symbol in a @code{weakref} directive.

Implicitly marks the symbol as weak, but see below.  It should only be called

if the referenced symbol has just been added to the symbol table.

@item S_SET_WEAKREFD

@cindex S_SET_WEAKREFD

Clear the @code{weakref} aliased status of a symbol.  This is implicitly called

whenever the symbol is looked up, as part of a direct reference or a

definition, but not as part of a @code{weakref} directive.

@item S_SET_VOLATILE

@cindex S_SET_VOLATILE

Indicate that the symbol may be re-defined.

@item S_CLEAR_VOLATILE

@cindex S_CLEAR_VOLATILE

Indicate that the symbol may no longer be re-defined.

@item S_SET_FORWARD_REF

@cindex S_SET_FORWARD_REF

Indicate that the symbol is a forward reference, that is its value must only

be determined upon use.

@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

Return whether a symbol was used in an expression.

@item symbol_mark_used_in_reloc

@cindex symbol_mark_used_in_reloc

Mark a symbol as having been used by a relocation.

@item symbol_clear_used_in_reloc

@cindex symbol_clear_used_in_reloc

Clear the mark indicating that a symbol was used in a relocation.

@item symbol_used_in_reloc_p

@cindex symbol_used_in_reloc_p

Return whether a symbol was used in a relocation.

@item symbol_mark_mri_common

@cindex symbol_mark_mri_common

Mark a symbol as an MRI common symbol.

@item symbol_clear_mri_common

@cindex symbol_clear_mri_common

Clear the mark indicating that a symbol is an MRI common symbol.

@item symbol_mri_common_p

@cindex symbol_mri_common_p

Return whether a symbol is an MRI common symbol.

@item symbol_mark_written

@cindex symbol_mark_written

Mark a symbol as having been written.

@item symbol_clear_written

@cindex symbol_clear_written

Clear the mark indicating that a symbol was written.

@item symbol_written_p

@cindex symbol_written_p

Return whether a symbol was written.

@item symbol_mark_resolved

@cindex symbol_mark_resolved

Mark a symbol as having been resolved.

@item symbol_resolved_p

@cindex symbol_resolved_p

Return whether a symbol has been resolved.

@item symbol_section_p

@cindex symbol_section_p

Return whether a symbol is a section symbol.

@item symbol_equated_p

@cindex symbol_equated_p

Return whether a symbol is equated to another symbol.

@item symbol_constant_p

@cindex symbol_constant_p

Return whether a symbol has a constant value, including being an offset within

some frag.

@item symbol_get_bfdsym

@cindex symbol_get_bfdsym

Return the BFD symbol associated with a symbol.

@item symbol_set_bfdsym

@cindex symbol_set_bfdsym

Set the BFD symbol associated with a symbol.

@item symbol_get_obj

@cindex symbol_get_obj

Return a pointer to the @code{OBJ_SYMFIELD_TYPE} field of a symbol.

@item symbol_set_obj

@cindex symbol_set_obj

Set the @code{OBJ_SYMFIELD_TYPE} field of a symbol.

@item symbol_get_tc

@cindex symbol_get_tc

Return a pointer to the @code{TC_SYMFIELD_TYPE} field of a symbol.

@item symbol_set_tc

@cindex symbol_set_tc

Set the @code{TC_SYMFIELD_TYPE} field of a symbol.

@end table

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.

Code outside of the symbol handler will always deal with @code{symbolS}

structures and use the accessor functions.  The accessor functions correctly

deal with local symbols.  @code{struct local_symbol} is much smaller than

@code{symbolS} (which also automatically creates a bfd @code{asymbol}

structure), so this saves space when assembling large files.

The first field of @code{symbolS} is @code{bsym}, the pointer to the BFD

symbol.  The first field of @code{struct local_symbol} is a pointer which is

always set to NULL.  This is how the symbol accessor functions can distinguish

local symbols from ordinary symbols.  The symbol accessor functions

automatically convert a local symbol into an ordinary symbol when necessary.

@node Expressions

@subsection Expressions

@cindex internals, expressions

@cindex expressions, internal

@cindex expressionS structure

Expressions are stored in an @code{expressionS} structure.  The structure is

defined in @file{expr.h}.

@cindex expression

The macro @code{expression} will create an @code{expressionS} structure based

on the text found at the global variable @code{input_line_pointer}.

@cindex make_expr_symbol

@cindex expr_symbol_where

A single @code{expressionS} structure can represent a single operation.

Complex expressions are formed by creating @dfn{expression symbols} and

combining them in @code{expressionS} structures.  An expression symbol is

created by calling @code{make_expr_symbol}.  An expression symbol should

naturally never appear in a symbol table, and the implementation of

@code{S_IS_LOCAL} (@pxref{Symbols}) reflects that.  The function

@code{expr_symbol_where} returns non-zero if a symbol is an expression symbol,

and also returns the file and line for the expression which caused it to be

created.

The @code{expressionS} structure has two symbol fields, a number field, an

operator field, and a field indicating whether the number is unsigned.

The operator field is of type @code{operatorT}, and describes how to interpret

the other fields; see the definition in @file{expr.h} for the possibilities.

An @code{operatorT} value of @code{O_big} indicates either a floating point

number, stored in the global variable @code{generic_floating_point_number}, or

an integer too large to store in an @code{offsetT} type, stored in the global

array @code{generic_bignum}.  This rather inflexible approach makes it

impossible to use floating point numbers or large expressions in complex

expressions.

@node Fixups

@subsection Fixups

@cindex internals, fixups

@cindex fixups

@cindex fixS structure

A @dfn{fixup} is basically anything which can not be resolved in the first

pass.  Sometimes a fixup can be resolved by the end of the assembly; if not,

the fixup becomes a relocation entry in the object file.

@cindex fix_new

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

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.

The @code{fixS} structure has a number of fields, several of which are obsolete

or are only used by a particular target.  The important fields are:

@table @code

@item fx_frag

The frag (@pxref{Frags}) this fixup is in.

@item fx_where

The location within the frag where the fixup occurs.

@item fx_addsy

The symbol this fixup is against.  Typically, the value of this symbol is added

into the object contents.  This may be NULL.

@item fx_subsy

The value of this symbol is subtracted from the object contents.  This is

normally NULL.

@item fx_offset

A number which is added into the fixup.

@item fx_addnumber

Some CPU backends use this field to convey information between

@code{md_apply_fix} and @code{tc_gen_reloc}.  The machine independent code does

not use it.

@item fx_next

The next fixup in the section.

@item fx_r_type

The type of the fixup.

@item fx_size

The size of the fixup.  This is mostly used for error checking.

@item fx_pcrel

Whether the fixup is PC relative.

@item fx_done

Non-zero if the fixup has been applied, and no relocation entry needs to be

generated.

@item fx_file

@itemx fx_line

The file and line where the fixup was created.

@item tc_fix_data

This has the type @code{TC_FIX_TYPE}, and is only defined if the target defines

that macro.

@end table

@node Frags

@subsection Frags

@cindex internals, frags

@cindex frags

@cindex fragS structure.

The @code{fragS} structure is defined in @file{as.h}.  Each frag represents a

portion of the final object file.  As GAS reads the source file, it creates

frags to hold the data that it reads.  At the end of the assembly the frags and

fixups are processed to produce the final contents.

@table @code

@item fr_address

The address of the frag.  This is not set until the assembler rescans the list

of all frags after the entire input file is parsed.  The function

@code{relax_segment} fills in this field.

@item fr_next

Pointer to the next frag in this (sub)section.

@item fr_fix

Fixed number of characters we know we're going to emit to the output file.  May

be zero.

@item fr_var

Variable number of characters we may output, after the initial @code{fr_fix}

characters.  May be zero.

@item fr_offset

The interpretation of this field is controlled by @code{fr_type}.  Generally,

if @code{fr_var} is non-zero, this is a repeat count: the @code{fr_var}

characters are output @code{fr_offset} times.

@item line

Holds line number info when an assembler listing was requested.

@item fr_type

Relaxation state.  This field indicates the interpretation of @code{fr_offset},

@code{fr_symbol} and the variable-length tail of the frag, as well as the

treatment it gets in various phases of processing.  It does not affect the

initial @code{fr_fix} characters; they are always supposed to be output

verbatim (fixups aside).  See below for specific values this field can have.

@item fr_subtype

Relaxation substate.  If the macro @code{md_relax_frag} isn't defined, this is

assumed to be an index into @code{TC_GENERIC_RELAX_TABLE} for the generic

relaxation code to process (@pxref{Relaxation}).  If @code{md_relax_frag} is

defined, this field is available for any use by the CPU-specific code.

@item fr_symbol

This normally indicates the symbol to use when relaxing the frag according to

@code{fr_type}.

@item fr_opcode

Points to the lowest-addressed byte of the opcode, for use in relaxation.

@item tc_frag_data

Target specific fragment data of type TC_FRAG_TYPE.

Only present if @code{TC_FRAG_TYPE} is defined.

@item fr_file

@itemx fr_line

The file and line where this frag was last modified.

@item fr_literal

Declared as a one-character array, this last field grows arbitrarily large to

hold the actual contents of the frag.

@end table

These are the possible relaxation states, provided in the enumeration type

@code{relax_stateT}, and the interpretations they represent for the other

fields:

@table @code

@item rs_align

@itemx rs_align_code

The start of the following frag should be aligned on some boundary.  In this

frag, @code{fr_offset} is the logarithm (base 2) of the alignment in bytes.

(For example, if alignment on an 8-byte boundary were desired, @code{fr_offset}

would have a value of 3.)  The variable characters indicate the fill pattern to

be used.  The @code{fr_subtype} field holds the maximum number of bytes to skip

when doing this alignment.  If more bytes are needed, the alignment is not

done.  An @code{fr_subtype} value of 0 means no maximum, which is the normal

case.  Target backends can use @code{rs_align_code} to handle certain types of

alignment differently.

@item rs_broken_word

This indicates that ``broken word'' processing should be done (@pxref{Broken

words}).  If broken word processing is not necessary on the target machine,

this enumerator value will not be defined.

@item rs_cfa

This state is used to implement exception frame optimizations.  The

@code{fr_symbol} is an expression symbol for the subtraction which may be

relaxed.  The @code{fr_opcode} field holds the frag for the preceding command

byte.  The @code{fr_offset} field holds the offset within that frag.  The

@code{fr_subtype} field is used during relaxation to hold the current size of

the frag.

@item rs_fill

The variable characters are to be repeated @code{fr_offset} times.  If

@code{fr_offset} is 0, this frag has a length of @code{fr_fix}.  Most frags

have this type.

@item rs_leb128

This state is used to implement the DWARF ``little endian base 128''

variable length number format.  The @code{fr_symbol} is always an expression

symbol, as constant expressions are emitted directly.  The @code{fr_offset}

field is used during relaxation to hold the previous size of the number so

that we can determine if the fragment changed size.

@item rs_machine_dependent

Displacement relaxation is to be done on this frag.  The target is indicated by

@code{fr_symbol} and @code{fr_offset}, and @code{fr_subtype} indicates the

particular machine-specific addressing mode desired.  @xref{Relaxation}.

@item rs_org

The start of the following frag should be pushed back to some specific offset

within the section.  (Some assemblers use the value as an absolute address; GAS

does not handle final absolute addresses, but rather requires that the linker

set them.)  The offset is given by @code{fr_symbol} and @code{fr_offset}; one

character from the variable-length tail is used as the fill character.

@end table

@cindex frchainS structure

A chain of frags is built up for each subsection.  The data structure

describing a chain is called a @code{frchainS}, and contains the following

fields:

@table @code

@item frch_root

Points to the first frag in the chain.  May be NULL if there are no frags in

this chain.

@item frch_last

Points to the last frag in the chain, or NULL if there are none.

@item frch_next

Next in the list of @code{frchainS} structures.

@item frch_seg

Indicates the section this frag chain belongs to.

@item frch_subseg

Subsection (subsegment) number of this frag chain.

@item fix_root, fix_tail

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.

@item frch_frag_now

The current frag for this subsegment.

@end table

A @code{frchainS} corresponds to a subsection; each section has a list of

@code{frchainS} records associated with it.  In most cases, only one subsection

of each section is used, so the list will only be one element long, but any

processing of frag chains should be prepared to deal with multiple chains per

section.

After the input files have been completely processed, and no more frags are to

be generated, the frag chains are joined into one per section for further

processing.  After this point, it is safe to operate on one chain per section.

The assembler always has a current frag, named @code{frag_now}.  More space is

allocated for the current frag using the @code{frag_more} function; this

returns a pointer to the amount of requested space.  The function

@code{frag_room} says by how much the current frag can be extended.

Relaxing is done using variant frags allocated by @code{frag_var}

or @code{frag_variant} (@pxref{Relaxation}).

@node GAS processing

@section What GAS does when it runs

@cindex internals, overview

This is a quick look at what an assembler run looks like.

@itemize @bullet

@item

The assembler initializes itself by calling various init routines.

@item

For each source file, the @code{read_a_source_file} function reads in the file

and parses it.  The global variable @code{input_line_pointer} points to the

current text; it is guaranteed to be correct up to the end of the line, but not

farther.

@item

For each line, the assembler passes labels to the @code{colon} function, and

isolates the first word.  If it looks like a pseudo-op, the word is looked up

in the pseudo-op hash table @code{po_hash} and dispatched to a pseudo-op

routine.  Otherwise, the target dependent @code{md_assemble} routine is called

to parse the instruction.

@item

When pseudo-ops or instructions output data, they add it to a frag, calling

@code{frag_more} to get space to store it in.

@item

Pseudo-ops and instructions can also output fixups created by @code{fix_new} or

@code{fix_new_exp}.

@item

For certain targets, instructions can create variant frags which are used to

store relaxation information (@pxref{Relaxation}).

@item

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.

@end itemize

@node Porting GAS

@section Porting GAS

@cindex porting

Each GAS target specifies two main things: the CPU file and the object format

file.  Two main switches in the @file{configure.in} file handle this.  The

first switches on CPU type to set the shell variable @code{cpu_type}.  The

second switches on the entire target to set the shell variable @code{fmt}.

The configure script uses the value of @code{cpu_type} to select two files in

the @file{config} directory: @file{tc-@var{CPU}.c} and @file{tc-@var{CPU}.h}.

The configuration process will create a file named @file{targ-cpu.h} in the

build directory which includes @file{tc-@var{CPU}.h}.

The configure script also uses the value of @code{fmt} to select two files:

@file{obj-@var{fmt}.c} and @file{obj-@var{fmt}.h}.  The configuration process

will create a file named @file{obj-format.h} in the build directory which

includes @file{obj-@var{fmt}.h}.

You can also set the emulation in the configure script by setting the @code{em}

variable.  Normally the default value of @samp{generic} is fine.  The

configuration process will create a file named @file{targ-env.h} in the build

directory which includes @file{te-@var{em}.h}.

There is a special case for COFF. For historical reason, the GNU COFF

assembler doesn't follow the documented behavior on certain debug symbols for

the compatibility with other COFF assemblers. A port can define

@code{STRICTCOFF} in the configure script to make the GNU COFF assembler

to follow the documented behavior.

Porting GAS to a new CPU requires writing the @file{tc-@var{CPU}} files.

Porting GAS to a new object file format requires writing the

@file{obj-@var{fmt}} files.  There is sometimes some interaction between these

two files, but it is normally minimal.

The best approach is, of course, to copy existing files.  The documentation

below assumes that you are looking at existing files to see usage details.

These interfaces have grown over time, and have never been carefully thought

out or designed.  Nothing about the interfaces described here is cast in stone.

It is possible that they will change from one version of the assembler to the

next.  Also, new macros are added all the time as they are needed.

@menu

* CPU backend::                 Writing a CPU backend

* Object format backend::       Writing an object format backend

* Emulations::                  Writing emulation files

@end menu

@node CPU backend

@subsection Writing a CPU backend

@cindex CPU backend

@cindex @file{tc-@var{CPU}}

The CPU backend files are the heart of the assembler.  They are the only parts

of the assembler which actually know anything about the instruction set of the

processor.

You must define a reasonably small list of macros and functions in the CPU

backend files.  You may define a large number of additional macros in the CPU

backend files, not all of which are documented here.  You must, of course,

define macros in the @file{.h} file, which is included by every assembler

source file.  You may define the functions as macros in the @file{.h} file, or

as functions in the @file{.c} file.

@table @code

@item TC_@var{CPU}

@cindex TC_@var{CPU}

By convention, you should define this macro in the @file{.h} file.  For

example, @file{tc-m68k.h} defines @code{TC_M68K}.  You might have to use this

if it is necessary to add CPU specific code to the object format file.

@item TARGET_FORMAT

This macro is the BFD target name to use when creating the output file.  This

will normally depend upon the @code{OBJ_@var{FMT}} macro.

@item TARGET_ARCH

This macro is the BFD architecture to pass to @code{bfd_set_arch_mach}.

@item TARGET_MACH

This macro is the BFD machine number to pass to @code{bfd_set_arch_mach}.  If

it is not defined, GAS will use 0.

@item TARGET_BYTES_BIG_ENDIAN

You should define this macro to be non-zero if the target is big endian, and

zero if the target is little endian.

@item md_shortopts

@itemx md_longopts

@itemx md_longopts_size

@itemx md_parse_option

@itemx md_show_usage

@itemx md_after_parse_args

@cindex md_shortopts

@cindex md_longopts

@cindex md_longopts_size

@cindex md_parse_option

@cindex md_show_usage

@cindex md_after_parse_args

GAS uses these variables and functions during option processing.

@code{md_shortopts} is a @code{const char *} which GAS adds to the machine

independent string passed to @code{getopt}.  @code{md_longopts} is a

@code{struct option []} which GAS adds to the machine independent long options

passed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in

@file{as.h}, as the start of a set of long option indices, if necessary.

@code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}.

GAS will call @code{md_parse_option} whenever @code{getopt} returns an

unrecognized code, presumably indicating a special code value which appears in

@code{md_longopts}.  This function should return non-zero if it handled the

option and zero otherwise.  There is no need to print a message about an option

not being recognized.  This will be handled by the generic code.

GAS will call @code{md_show_usage} when a usage message is printed; it should

print a description of the machine specific options. @code{md_after_pase_args},

if defined, is called after all options are processed, to let the backend

override settings done by the generic option parsing.

@item md_begin

@cindex md_begin

GAS will call this function at the start of the assembly, after the command

line arguments have been parsed and all the machine independent initializations

have been completed.

@item md_cleanup

@cindex md_cleanup

If you define this macro, GAS will call it at the end of each input file.

@item md_assemble

@cindex md_assemble

GAS will call this function for each input line which does not contain a

pseudo-op.  The argument is a null terminated string.  The function should

assemble the string as an instruction with operands.  Normally

@code{md_assemble} will do this by calling @code{frag_more} and writing out

some bytes (@pxref{Frags}).  @code{md_assemble} will call @code{fix_new} to

create fixups as needed (@pxref{Fixups}).  Targets which need to do special

purpose relaxation will call @code{frag_var}.

@item md_pseudo_table

@cindex md_pseudo_table

This is a const array of type @code{pseudo_typeS}.  It is a mapping from

pseudo-op names to functions.  You should use this table to implement

pseudo-ops which are specific to the CPU.

@item tc_conditional_pseudoop

@cindex tc_conditional_pseudoop

If this macro is defined, GAS will call it with a @code{pseudo_typeS} argument.

It should return non-zero if the pseudo-op is a conditional which controls

whether code is assembled, such as @samp{.if}.  GAS knows about the normal

conditional pseudo-ops, and you should normally not have to define this macro.

@item comment_chars

@cindex comment_chars

This is a null terminated @code{const char} array of characters which start a

comment.

@item tc_comment_chars

@cindex tc_comment_chars

If this macro is defined, GAS will use it instead of @code{comment_chars}.

@item tc_symbol_chars

@cindex tc_symbol_chars

If this macro is defined, it is a pointer to a null terminated list of

characters which may appear in an operand.  GAS already assumes that all

alphanumeric characters, and @samp{$}, @samp{.}, and @samp{_} may appear in an

operand (see @samp{symbol_chars} in @file{app.c}).  This macro may be defined

to treat additional characters as appearing in an operand.  This affects the

way in which GAS removes whitespace before passing the string to

@samp{md_assemble}.

@item line_comment_chars

@cindex line_comment_chars

This is a null terminated @code{const char} array of characters which start a

comment when they appear at the start of a line.

@item line_separator_chars

@cindex line_separator_chars

This is a null terminated @code{const char} array of characters which separate

lines (null and newline are such characters by default, and need not be

listed in this array).  Note that line_separator_chars do not separate lines

if found in a comment, such as after a character in line_comment_chars or

comment_chars.

@item EXP_CHARS

@cindex EXP_CHARS

This is a null terminated @code{const char} array of characters which may be

used as the exponent character in a floating point number.  This is normally

@code{"eE"}.

@item FLT_CHARS

@cindex FLT_CHARS

This is a null terminated @code{const char} array of characters which may be

used to indicate a floating point constant.  A zero followed by one of these

characters is assumed to be followed by a floating point number; thus they

operate the way that @code{0x} is used to indicate a hexadecimal constant.

Usually this includes @samp{r} and @samp{f}.

@item LEX_AT

@cindex LEX_AT

You may define this macro to the lexical type of the @kbd{@@} character.  The

default is zero.

Lexical types are a combination of @code{LEX_NAME} and @code{LEX_BEGIN_NAME},

both defined in @file{read.h}.  @code{LEX_NAME} indicates that the character

may appear in a name.  @code{LEX_BEGIN_NAME} indicates that the character may

appear at the beginning of a name.

@item LEX_BR

@cindex LEX_BR

You may define this macro to the lexical type of the brace characters @kbd{@{},