Subversion Repositories openrisc_me

\input texinfo

\input texinfo

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

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

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

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

@c  Free Software Foundation, Inc.

@c  Free Software Foundation, Inc.

@setfilename internals.info

@setfilename internals.info

@node Top

@node Top

@top Assembler Internals

@top Assembler Internals

@raisesections

@raisesections

@cindex internals

@cindex internals

This chapter describes the internals of the assembler.  It is incomplete, but

This chapter describes the internals of the assembler.  It is incomplete, but

it may help a bit.

it may help a bit.

This chapter is not updated regularly, and it may be out of date.

This chapter is not updated regularly, and it may be out of date.

@menu

@menu

* Data types::          Data types

* Data types::          Data types

* GAS processing::      What GAS does when it runs

* GAS processing::      What GAS does when it runs

* Porting GAS::         Porting GAS

* Porting GAS::         Porting GAS

* Relaxation::          Relaxation

* Relaxation::          Relaxation

* Broken words::        Broken words

* Broken words::        Broken words

* Internal functions::  Internal functions

* Internal functions::  Internal functions

* Test suite::          Test suite

* Test suite::          Test suite

@end menu

@end menu

@node Data types

@node Data types

@section Data types

@section Data types

@cindex internals, data types

@cindex internals, data types

This section describes some fundamental GAS data types.

This section describes some fundamental GAS data types.

@menu

@menu

* Symbols::             The symbolS structure

* Symbols::             The symbolS structure

* Expressions::         The expressionS structure

* Expressions::         The expressionS structure

* Fixups::              The fixS structure

* Fixups::              The fixS structure

* Frags::               The fragS structure

* Frags::               The fragS structure

@end menu

@end menu

@node Symbols

@node Symbols

@subsection Symbols

@subsection Symbols

@cindex internals, symbols

@cindex internals, symbols

@cindex symbols, internal

@cindex symbols, internal

@cindex symbolS structure

@cindex symbolS structure

The definition for the symbol structure, @code{symbolS}, is located in

The definition for the symbol structure, @code{symbolS}, is located in

@file{struc-symbol.h}.

@file{struc-symbol.h}.

In general, the fields of this structure may not be referred to directly.

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

Instead, you must use one of the accessor functions defined in @file{symbol.h}.

These accessor functions should work for any GAS version.

These accessor functions should work for any GAS version.

Symbol structures contain the following fields:

Symbol structures contain the following fields:

@table @code

@table @code

@item sy_value

@item sy_value

This is an @code{expressionS} that describes the value of the symbol.  It might

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

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

until @code{resolve_symbol_value} is called with @var{finalize_syms} non-zero

in @code{write_object_file}.

in @code{write_object_file}.

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

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

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.

(@pxref{Frags}).  Afterward, the frag address has been added in.

@item sy_resolved

@item sy_resolved

This field is non-zero if the symbol's value has been completely resolved.  It

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.

is used during the final pass over the symbol table.

@item sy_resolving

@item sy_resolving

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

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

@item sy_used_in_reloc

@item sy_used_in_reloc

This field is non-zero if the symbol is used by a relocation entry.  If a local

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

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

relocations to other symbols, or this symbol cannot be removed from the final

symbol list.

symbol list.

@item sy_next

@item sy_next

@itemx sy_previous

@itemx sy_previous

These pointers to other @code{symbolS} structures describe a doubly

These pointers to other @code{symbolS} structures describe a doubly

linked list.  These fields should be accessed with

linked list.  These fields should be accessed with

the @code{symbol_next} and @code{symbol_previous} macros.

the @code{symbol_next} and @code{symbol_previous} macros.

@item sy_frag

@item sy_frag

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

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

@item sy_used

@item sy_used

Whether the symbol is used as an operand or in an expression.  Note: Not all of

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

the backends keep this information accurate; backends which use this bit are

responsible for setting it when a symbol is used in backend routines.

responsible for setting it when a symbol is used in backend routines.

@item sy_mri_common

@item sy_mri_common

Whether the symbol is an MRI common symbol created by the @code{COMMON}

Whether the symbol is an MRI common symbol created by the @code{COMMON}

pseudo-op when assembling in MRI mode.

pseudo-op when assembling in MRI mode.

@item sy_volatile

@item sy_volatile

Whether the symbol can be re-defined.

Whether the symbol can be re-defined.

@item sy_forward_ref

@item sy_forward_ref

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

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

@item sy_weakrefr

@item sy_weakrefr

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

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

@item sy_weakrefd

@item sy_weakrefd

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

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

and has not had any direct references.

and has not had any direct references.

@item bsym

@item bsym

This points to the BFD @code{asymbol} that

This points to the BFD @code{asymbol} that

will be used in writing the object file.

will be used in writing the object file.

@item sy_obj

@item sy_obj

This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}.  If no macro by

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.

that name is defined in @file{obj-format.h}, this field is not defined.

@item sy_tc

@item sy_tc

This processor-specific data is of type @code{TC_SYMFIELD_TYPE}.  If no macro

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.

by that name is defined in @file{targ-cpu.h}, this field is not defined.

@end table

@end table

Here is a description of the accessor functions.  These should be used rather

Here is a description of the accessor functions.  These should be used rather

than referring to the fields of @code{symbolS} directly.

than referring to the fields of @code{symbolS} directly.

@table @code

@table @code

@item S_SET_VALUE

@item S_SET_VALUE

@cindex S_SET_VALUE

@cindex S_SET_VALUE

Set the symbol's value.

Set the symbol's value.

@item S_GET_VALUE

@item S_GET_VALUE

@cindex S_GET_VALUE

@cindex S_GET_VALUE

Get the symbol's value.  This will cause @code{resolve_symbol_value} to be

Get the symbol's value.  This will cause @code{resolve_symbol_value} to be

called if necessary.

called if necessary.

@item S_SET_SEGMENT

@item S_SET_SEGMENT

@cindex S_SET_SEGMENT

@cindex S_SET_SEGMENT

Set the section of the symbol.

Set the section of the symbol.

@item S_GET_SEGMENT

@item S_GET_SEGMENT

@cindex S_GET_SEGMENT

@cindex S_GET_SEGMENT

Get the symbol's section.

Get the symbol's section.

@item S_GET_NAME

@item S_GET_NAME

@cindex S_GET_NAME

@cindex S_GET_NAME

Get the name of the symbol.

Get the name of the symbol.

@item S_SET_NAME

@item S_SET_NAME

@cindex S_SET_NAME

@cindex S_SET_NAME

Set the name of the symbol.

Set the name of the symbol.

@item S_IS_EXTERNAL

@item S_IS_EXTERNAL

@cindex S_IS_EXTERNAL

@cindex S_IS_EXTERNAL

Return non-zero if the symbol is externally visible.

Return non-zero if the symbol is externally visible.

@item S_IS_EXTERN

@item S_IS_EXTERN

@cindex S_IS_EXTERN

@cindex S_IS_EXTERN

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

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

@item S_IS_WEAK

@item S_IS_WEAK

@cindex S_IS_WEAK

@cindex S_IS_WEAK

Return non-zero if the symbol is weak, or if it is a @code{weakref} alias or

Return non-zero if the symbol is weak, or if it is a @code{weakref} alias or

symbol that has not been strongly referenced.

symbol that has not been strongly referenced.

@item S_IS_WEAKREFR

@item S_IS_WEAKREFR

@cindex S_IS_WEAKREFR

@cindex S_IS_WEAKREFR

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

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

@item S_IS_WEAKREFD

@item S_IS_WEAKREFD

@cindex S_IS_WEAKREFD

@cindex S_IS_WEAKREFD

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

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

had any strong references.

had any strong references.

@item S_IS_VOLATILE

@item S_IS_VOLATILE

@cindex S_IS_VOLATILE

@cindex S_IS_VOLATILE

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

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

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

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

@item S_IS_FORWARD_REF

@item S_IS_FORWARD_REF

@cindex S_IS_FORWARD_REF

@cindex S_IS_FORWARD_REF

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

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

only be determined upon use.

only be determined upon use.

@item S_IS_COMMON

@item S_IS_COMMON

@cindex S_IS_COMMON

@cindex S_IS_COMMON

Return non-zero if this is a common symbol.  Common symbols are sometimes

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

represented as undefined symbols with a value, in which case this function will

not be reliable.

not be reliable.

@item S_IS_DEFINED

@item S_IS_DEFINED

@cindex S_IS_DEFINED

@cindex S_IS_DEFINED

Return non-zero if this symbol is defined.  This function is not reliable when

Return non-zero if this symbol is defined.  This function is not reliable when

called on a common symbol.

called on a common symbol.

@item S_IS_DEBUG

@item S_IS_DEBUG

@cindex S_IS_DEBUG

@cindex S_IS_DEBUG

Return non-zero if this is a debugging symbol.

Return non-zero if this is a debugging symbol.

@item S_IS_LOCAL

@item S_IS_LOCAL

@cindex S_IS_LOCAL

@cindex S_IS_LOCAL

Return non-zero if this is a local assembler symbol which should not be

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

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

@code{S_IS_EXTERNAL}.  The @samp{-L} assembler option affects the return value

of this function.

of this function.

@item S_SET_EXTERNAL

@item S_SET_EXTERNAL

@cindex S_SET_EXTERNAL

@cindex S_SET_EXTERNAL

Mark the symbol as externally visible.

Mark the symbol as externally visible.

@item S_CLEAR_EXTERNAL

@item S_CLEAR_EXTERNAL

@cindex S_CLEAR_EXTERNAL

@cindex S_CLEAR_EXTERNAL

Mark the symbol as not externally visible.

Mark the symbol as not externally visible.

@item S_SET_WEAK

@item S_SET_WEAK

@cindex S_SET_WEAK

@cindex S_SET_WEAK

Mark the symbol as weak.

Mark the symbol as weak.

@item S_SET_WEAKREFR

@item S_SET_WEAKREFR

@cindex S_SET_WEAKREFR

@cindex S_SET_WEAKREFR

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

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

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.

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

@item S_CLEAR_WEAKREFR

@item S_CLEAR_WEAKREFR

@cindex S_CLEAR_WEAKREFR

@cindex S_CLEAR_WEAKREFR

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

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

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

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

@item S_SET_WEAKREFD

@item S_SET_WEAKREFD

@cindex S_SET_WEAKREFD

@cindex S_SET_WEAKREFD

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

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

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.

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

@item S_SET_WEAKREFD

@item S_SET_WEAKREFD

@cindex S_SET_WEAKREFD

@cindex S_SET_WEAKREFD

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

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

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

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

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

@item S_SET_VOLATILE

@item S_SET_VOLATILE

@cindex S_SET_VOLATILE

@cindex S_SET_VOLATILE

Indicate that the symbol may be re-defined.

Indicate that the symbol may be re-defined.

@item S_CLEAR_VOLATILE

@item S_CLEAR_VOLATILE

@cindex S_CLEAR_VOLATILE

@cindex S_CLEAR_VOLATILE

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

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

@item S_SET_FORWARD_REF

@item S_SET_FORWARD_REF

@cindex S_SET_FORWARD_REF

@cindex S_SET_FORWARD_REF

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

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

be determined upon use.

be determined upon use.

@item S_GET_TYPE

@item S_GET_TYPE

@item S_GET_DESC

@item S_GET_DESC

@item S_GET_OTHER

@item S_GET_OTHER

@cindex S_GET_TYPE

@cindex S_GET_TYPE

@cindex S_GET_DESC

@cindex S_GET_DESC

@cindex S_GET_OTHER

@cindex S_GET_OTHER

Get the @code{type}, @code{desc}, and @code{other} fields of the symbol.  These

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

are only defined for object file formats for which they make sense (primarily

a.out).

a.out).

@item S_SET_TYPE

@item S_SET_TYPE

@item S_SET_DESC

@item S_SET_DESC

@item S_SET_OTHER

@item S_SET_OTHER

@cindex S_SET_TYPE

@cindex S_SET_TYPE

@cindex S_SET_DESC

@cindex S_SET_DESC

@cindex S_SET_OTHER

@cindex S_SET_OTHER

Set the @code{type}, @code{desc}, and @code{other} fields of the symbol.  These

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

are only defined for object file formats for which they make sense (primarily

a.out).

a.out).

@item S_GET_SIZE

@item S_GET_SIZE

@cindex S_GET_SIZE

@cindex S_GET_SIZE

Get the size of a symbol.  This is only defined for object file formats for

Get the size of a symbol.  This is only defined for object file formats for

which it makes sense (primarily ELF).

which it makes sense (primarily ELF).

@item S_SET_SIZE

@item S_SET_SIZE

@cindex S_SET_SIZE

@cindex S_SET_SIZE

Set the size of a symbol.  This is only defined for object file formats for

Set the size of a symbol.  This is only defined for object file formats for

which it makes sense (primarily ELF).

which it makes sense (primarily ELF).

@item symbol_get_value_expression

@item symbol_get_value_expression

@cindex symbol_get_value_expression

@cindex symbol_get_value_expression

Get a pointer to an @code{expressionS} structure which represents the value of

Get a pointer to an @code{expressionS} structure which represents the value of

the symbol as an expression.

the symbol as an expression.

@item symbol_set_value_expression

@item symbol_set_value_expression

@cindex symbol_set_value_expression

@cindex symbol_set_value_expression

Set the value of a symbol to an expression.

Set the value of a symbol to an expression.

@item symbol_set_frag

@item symbol_set_frag

@cindex symbol_set_frag

@cindex symbol_set_frag

Set the frag where a symbol is defined.

Set the frag where a symbol is defined.

@item symbol_get_frag

@item symbol_get_frag

@cindex symbol_get_frag

@cindex symbol_get_frag

Get the frag where a symbol is defined.

Get the frag where a symbol is defined.

@item symbol_mark_used

@item symbol_mark_used

@cindex symbol_mark_used

@cindex symbol_mark_used

Mark a symbol as having been used in an expression.

Mark a symbol as having been used in an expression.

@item symbol_clear_used

@item symbol_clear_used

@cindex symbol_clear_used

@cindex symbol_clear_used

Clear the mark indicating that a symbol was used in an expression.

Clear the mark indicating that a symbol was used in an expression.

@item symbol_used_p

@item symbol_used_p

@cindex symbol_used_p

@cindex symbol_used_p

Return whether a symbol was used in an expression.

Return whether a symbol was used in an expression.

@item symbol_mark_used_in_reloc

@item symbol_mark_used_in_reloc

@cindex symbol_mark_used_in_reloc

@cindex symbol_mark_used_in_reloc

Mark a symbol as having been used by a relocation.

Mark a symbol as having been used by a relocation.

@item symbol_clear_used_in_reloc

@item symbol_clear_used_in_reloc

@cindex symbol_clear_used_in_reloc

@cindex symbol_clear_used_in_reloc

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

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

@item symbol_used_in_reloc_p

@item symbol_used_in_reloc_p

@cindex symbol_used_in_reloc_p

@cindex symbol_used_in_reloc_p

Return whether a symbol was used in a relocation.

Return whether a symbol was used in a relocation.

@item symbol_mark_mri_common

@item symbol_mark_mri_common

@cindex symbol_mark_mri_common

@cindex symbol_mark_mri_common

Mark a symbol as an MRI common symbol.

Mark a symbol as an MRI common symbol.

@item symbol_clear_mri_common

@item symbol_clear_mri_common

@cindex symbol_clear_mri_common

@cindex symbol_clear_mri_common

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

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

@item symbol_mri_common_p

@item symbol_mri_common_p

@cindex symbol_mri_common_p

@cindex symbol_mri_common_p

Return whether a symbol is an MRI common symbol.

Return whether a symbol is an MRI common symbol.

@item symbol_mark_written

@item symbol_mark_written

@cindex symbol_mark_written

@cindex symbol_mark_written

Mark a symbol as having been written.

Mark a symbol as having been written.

@item symbol_clear_written

@item symbol_clear_written

@cindex symbol_clear_written

@cindex symbol_clear_written

Clear the mark indicating that a symbol was written.

Clear the mark indicating that a symbol was written.

@item symbol_written_p

@item symbol_written_p

@cindex symbol_written_p

@cindex symbol_written_p

Return whether a symbol was written.

Return whether a symbol was written.

@item symbol_mark_resolved

@item symbol_mark_resolved

@cindex symbol_mark_resolved

@cindex symbol_mark_resolved

Mark a symbol as having been resolved.

Mark a symbol as having been resolved.

@item symbol_resolved_p

@item symbol_resolved_p

@cindex symbol_resolved_p

@cindex symbol_resolved_p

Return whether a symbol has been resolved.

Return whether a symbol has been resolved.

@item symbol_section_p

@item symbol_section_p

@cindex symbol_section_p

@cindex symbol_section_p

Return whether a symbol is a section symbol.

Return whether a symbol is a section symbol.

@item symbol_equated_p

@item symbol_equated_p

@cindex symbol_equated_p

@cindex symbol_equated_p

Return whether a symbol is equated to another symbol.

Return whether a symbol is equated to another symbol.

@item symbol_constant_p

@item symbol_constant_p

@cindex symbol_constant_p

@cindex symbol_constant_p

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

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

some frag.

some frag.

@item symbol_get_bfdsym

@item symbol_get_bfdsym

@cindex symbol_get_bfdsym

@cindex symbol_get_bfdsym

Return the BFD symbol associated with a symbol.

Return the BFD symbol associated with a symbol.

@item symbol_set_bfdsym

@item symbol_set_bfdsym

@cindex symbol_set_bfdsym

@cindex symbol_set_bfdsym

Set the BFD symbol associated with a symbol.

Set the BFD symbol associated with a symbol.

@item symbol_get_obj

@item symbol_get_obj

@cindex symbol_get_obj

@cindex symbol_get_obj

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

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

@item symbol_set_obj

@item symbol_set_obj

@cindex symbol_set_obj

@cindex symbol_set_obj

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

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

@item symbol_get_tc

@item symbol_get_tc

@cindex symbol_get_tc

@cindex symbol_get_tc

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

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

@item symbol_set_tc

@item symbol_set_tc

@cindex symbol_set_tc

@cindex symbol_set_tc

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

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

@end table

@end table

GAS attempts to store local

GAS attempts to store local

symbols--symbols which will not be written to the output file--using a

symbols--symbols which will not be written to the output file--using a

different structure, @code{struct local_symbol}.  This structure can only

different structure, @code{struct local_symbol}.  This structure can only

represent symbols whose value is an offset within a frag.

represent symbols whose value is an offset within a frag.

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

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

structures and use the accessor functions.  The accessor functions correctly

structures and use the accessor functions.  The accessor functions correctly

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

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

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

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

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

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

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

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

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

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

local symbols from ordinary symbols.  The symbol accessor functions

local symbols from ordinary symbols.  The symbol accessor functions

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

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

@node Expressions

@node Expressions

@subsection Expressions

@subsection Expressions

@cindex internals, expressions

@cindex internals, expressions

@cindex expressions, internal

@cindex expressions, internal

@cindex expressionS structure

@cindex expressionS structure

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

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

defined in @file{expr.h}.

defined in @file{expr.h}.

@cindex expression

@cindex expression

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

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

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

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

@cindex make_expr_symbol

@cindex make_expr_symbol

@cindex expr_symbol_where

@cindex expr_symbol_where

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

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

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

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

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

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

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

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

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

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

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

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

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

@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

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

created.

created.

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

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

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

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

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

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

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

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

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

impossible to use floating point numbers or large expressions in complex

impossible to use floating point numbers or large expressions in complex

expressions.

expressions.

@node Fixups

@node Fixups

@subsection Fixups

@subsection Fixups

@cindex internals, fixups

@cindex internals, fixups

@cindex fixups

@cindex fixups

@cindex fixS structure

@cindex fixS structure

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

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,

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.

the fixup becomes a relocation entry in the object file.

@cindex fix_new

@cindex fix_new

@cindex fix_new_exp

@cindex fix_new_exp

A fixup is created by a call to @code{fix_new} or @code{fix_new_exp}.  Both

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

take a frag (@pxref{Frags}), a position within the frag, a size, an indication

of whether the fixup is PC relative, and a type.

of whether the fixup is PC relative, and a type.

The type is nominally a @code{bfd_reloc_code_real_type}, but several

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

targets use other type codes to represent fixups that can not be described as

relocations.

relocations.

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

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:

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

@table @code

@table @code

@item fx_frag

@item fx_frag

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

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

@item fx_where

@item fx_where

The location within the frag where the fixup occurs.

The location within the frag where the fixup occurs.

@item fx_addsy

@item fx_addsy

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

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

into the object contents.  This may be NULL.

into the object contents.  This may be NULL.

@item fx_subsy

@item fx_subsy

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

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

normally NULL.

normally NULL.

@item fx_offset

@item fx_offset

A number which is added into the fixup.

A number which is added into the fixup.

@item fx_addnumber

@item fx_addnumber

Some CPU backends use this field to convey information between

Some CPU backends use this field to convey information between

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

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

not use it.

not use it.

@item fx_next

@item fx_next

The next fixup in the section.

The next fixup in the section.

@item fx_r_type

@item fx_r_type

The type of the fixup.

The type of the fixup.

@item fx_size

@item fx_size

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

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

@item fx_pcrel

@item fx_pcrel

Whether the fixup is PC relative.

Whether the fixup is PC relative.

@item fx_done

@item fx_done

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

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

generated.

generated.

@item fx_file

@item fx_file

@itemx fx_line

@itemx fx_line

The file and line where the fixup was created.

The file and line where the fixup was created.

@item tc_fix_data

@item tc_fix_data

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

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

that macro.

that macro.

@end table

@end table

@node Frags

@node Frags

@subsection Frags

@subsection Frags

@cindex internals, frags

@cindex internals, frags

@cindex frags

@cindex frags

@cindex fragS structure.

@cindex fragS structure.

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

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

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

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.

fixups are processed to produce the final contents.

@table @code

@table @code

@item fr_address

@item fr_address

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

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

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

@code{relax_segment} fills in this field.

@code{relax_segment} fills in this field.

@item fr_next

@item fr_next

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

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

@item fr_fix

@item fr_fix

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

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

be zero.

be zero.

@item fr_var

@item fr_var

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

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

characters.  May be zero.

characters.  May be zero.

@item fr_offset

@item fr_offset

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

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}

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

characters are output @code{fr_offset} times.

characters are output @code{fr_offset} times.

@item line

@item line

Holds line number info when an assembler listing was requested.

Holds line number info when an assembler listing was requested.

@item fr_type

@item fr_type

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

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

@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

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

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

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

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

@item fr_subtype

@item fr_subtype

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

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

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

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.

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

@item fr_symbol

@item fr_symbol

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

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

@code{fr_type}.

@code{fr_type}.

@item fr_opcode

@item fr_opcode

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

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

@item tc_frag_data

@item tc_frag_data

Target specific fragment data of type TC_FRAG_TYPE.

Target specific fragment data of type TC_FRAG_TYPE.

Only present if @code{TC_FRAG_TYPE} is defined.

Only present if @code{TC_FRAG_TYPE} is defined.

@item fr_file

@item fr_file

@itemx fr_line

@itemx fr_line

The file and line where this frag was last modified.

The file and line where this frag was last modified.

@item fr_literal

@item fr_literal

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

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

hold the actual contents of the frag.

hold the actual contents of the frag.

@end table

@end table

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

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

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

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

fields:

fields:

@table @code

@table @code

@item rs_align

@item rs_align

@itemx rs_align_code

@itemx rs_align_code

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

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.

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}

(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

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

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

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

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

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

alignment differently.

alignment differently.

@item rs_broken_word

@item rs_broken_word

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

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

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

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

this enumerator value will not be defined.

this enumerator value will not be defined.

@item rs_cfa

@item rs_cfa

This state is used to implement exception frame optimizations.  The

This state is used to implement exception frame optimizations.  The

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

@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

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

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

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

the frag.

the frag.

@item rs_fill

@item rs_fill

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

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

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

have this type.

have this type.

@item rs_leb128

@item rs_leb128

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

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

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

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

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

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

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

that we can determine if the fragment changed size.

that we can determine if the fragment changed size.

@item rs_machine_dependent

@item rs_machine_dependent

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

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

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

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

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

@item rs_org

@item rs_org

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

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

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

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

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.

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

@end table

@end table

@cindex frchainS structure

@cindex frchainS structure

A chain of frags is built up for each subsection.  The data 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

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

fields:

fields:

@table @code

@table @code

@item frch_root

@item frch_root

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

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

this chain.

this chain.

@item frch_last

@item frch_last

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

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

@item frch_next

@item frch_next

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

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

@item frch_seg

@item frch_seg

Indicates the section this frag chain belongs to.

Indicates the section this frag chain belongs to.

@item frch_subseg

@item frch_subseg

Subsection (subsegment) number of this frag chain.

Subsection (subsegment) number of this frag chain.

@item fix_root, fix_tail

@item fix_root, fix_tail

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

@item frch_obstack

Not currently used.  Intended to be used for frag allocation for this

Not currently used.  Intended to be used for frag allocation for this

subsection.  This should reduce frag generation caused by switching sections.

subsection.  This should reduce frag generation caused by switching sections.

@item frch_frag_now

@item frch_frag_now

The current frag for this subsegment.

The current frag for this subsegment.

@end table

@end table

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

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

@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

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

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

section.

section.

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

@node GAS processing

@node GAS processing

@section What GAS does when it runs

@section What GAS does when it runs

@cindex internals, overview

@cindex internals, overview

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

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

@itemize @bullet

@itemize @bullet

@item

@item

The assembler initializes itself by calling various init routines.

The assembler initializes itself by calling various init routines.

@item

@item

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

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

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

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

farther.

farther.

@item

@item

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

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

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

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

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

to parse the instruction.

to parse the instruction.

@item

@item

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

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

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

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

@item

@item

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

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

@code{fix_new_exp}.

@code{fix_new_exp}.

@item

@item

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

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

store relaxation information (@pxref{Relaxation}).

store relaxation information (@pxref{Relaxation}).

@item

@item

When the input file is finished, the @code{write_object_file} routine is

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

called.  It assigns addresses to all the frags (@code{relax_segment}), resolves

all the fixups (@code{fixup_segment}), resolves all the symbol values (using

all the fixups (@code{fixup_segment}), resolves all the symbol values (using

@code{resolve_symbol_value}), and finally writes out the file.

@code{resolve_symbol_value}), and finally writes out the file.

@end itemize

@end itemize

@node Porting GAS

@node Porting GAS

@section Porting GAS

@section Porting GAS

@cindex porting

@cindex porting

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

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

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

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

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

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

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

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

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

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

@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

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

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

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

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

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

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

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

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

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

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

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

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

the compatibility with other COFF assemblers. A port can define

the compatibility with other COFF assemblers. A port can define

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

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

to follow the documented behavior.

to follow the documented behavior.

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

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

Porting GAS to a new object file format requires writing the

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

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

two files, but it is normally minimal.

two files, but it is normally minimal.

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

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.

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

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.

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

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.

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

@menu

@menu

* CPU backend::                 Writing a CPU backend

* CPU backend::                 Writing a CPU backend

* Object format backend::       Writing an object format backend

* Object format backend::       Writing an object format backend

* Emulations::                  Writing emulation files

* Emulations::                  Writing emulation files

@end menu

@end menu

@node CPU backend

@node CPU backend

@subsection Writing a CPU backend

@subsection Writing a CPU backend

@cindex CPU backend

@cindex CPU backend

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

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

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

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

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

processor.

processor.

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

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

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

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

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

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

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

@table @code

@table @code

@item TC_@var{CPU}

@item TC_@var{CPU}

@cindex TC_@var{CPU}

@cindex TC_@var{CPU}

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

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

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.

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

@item TARGET_FORMAT

@item TARGET_FORMAT

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

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.

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

@item TARGET_ARCH

@item TARGET_ARCH

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

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

@item TARGET_MACH

@item TARGET_MACH

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

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

it is not defined, GAS will use 0.

it is not defined, GAS will use 0.

@item TARGET_BYTES_BIG_ENDIAN

@item TARGET_BYTES_BIG_ENDIAN

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

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

zero if the target is little endian.

zero if the target is little endian.

@item md_shortopts

@item md_shortopts

@itemx md_longopts

@itemx md_longopts

@itemx md_longopts_size

@itemx md_longopts_size

@itemx md_parse_option

@itemx md_parse_option

@itemx md_show_usage

@itemx md_show_usage

@itemx md_after_parse_args

@itemx md_after_parse_args

@cindex md_shortopts

@cindex md_shortopts

@cindex md_longopts

@cindex md_longopts

@cindex md_longopts_size

@cindex md_longopts_size

@cindex md_parse_option

@cindex md_parse_option

@cindex md_show_usage

@cindex md_show_usage

@cindex md_after_parse_args

@cindex md_after_parse_args

GAS uses these variables and functions during option processing.

GAS uses these variables and functions during option processing.

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

@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

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

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

@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

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.

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

@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

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

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

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

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

@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

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.

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

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},

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

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

override settings done by the generic option parsing.

override settings done by the generic option parsing.

@item md_begin

@item md_begin

@cindex md_begin

@cindex md_begin

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

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

line arguments have been parsed and all the machine independent initializations

have been completed.

have been completed.

@item md_cleanup

@item md_cleanup

@cindex md_cleanup

@cindex md_cleanup

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

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

@item md_assemble

@item md_assemble

@cindex md_assemble

@cindex md_assemble

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

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

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

assemble the string as an instruction with operands.  Normally

assemble the string as an instruction with operands.  Normally

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

@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

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

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

purpose relaxation will call @code{frag_var}.

purpose relaxation will call @code{frag_var}.

@item md_pseudo_table

@item md_pseudo_table

@cindex md_pseudo_table

@cindex md_pseudo_table

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

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-op names to functions.  You should use this table to implement

pseudo-ops which are specific to the CPU.

pseudo-ops which are specific to the CPU.

@item tc_conditional_pseudoop

@item tc_conditional_pseudoop

@cindex tc_conditional_pseudoop

@cindex tc_conditional_pseudoop

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

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

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

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.

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

@item comment_chars

@item comment_chars

@cindex comment_chars

@cindex comment_chars

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

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

comment.

comment.

@item tc_comment_chars

@item tc_comment_chars

@cindex tc_comment_chars

@cindex tc_comment_chars

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

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

@item tc_symbol_chars

@item tc_symbol_chars

@cindex tc_symbol_chars

@cindex tc_symbol_chars

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

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

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

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

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

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

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

way in which GAS removes whitespace before passing the string to

way in which GAS removes whitespace before passing the string to

@samp{md_assemble}.

@samp{md_assemble}.

@item line_comment_chars

@item line_comment_chars

@cindex line_comment_chars

@cindex line_comment_chars

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

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

comment when they appear at the start of a line.

comment when they appear at the start of a line.

@item line_separator_chars

@item line_separator_chars

@cindex line_separator_chars

@cindex line_separator_chars

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

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

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

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

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

comment_chars.

comment_chars.

@item EXP_CHARS

@item EXP_CHARS

@cindex EXP_CHARS

@cindex EXP_CHARS

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

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

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

@code{"eE"}.

@code{"eE"}.

@item FLT_CHARS

@item FLT_CHARS

@cindex FLT_CHARS

@cindex FLT_CHARS

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

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

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

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.

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

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

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

@item LEX_AT

@item LEX_AT

@cindex LEX_AT

@cindex LEX_AT

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

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

default is zero.

default is zero.

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

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

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

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

appear at the beginning of a name.

appear at the beginning of a name.

@item LEX_BR

@item LEX_BR

@cindex LEX_BR

@cindex LEX_BR

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

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

@kbd{@}}, @kbd{[}, and @kbd{]}.  The default value is zero.

@kbd{@}}, @kbd{[}, and @kbd{]}.  The default value is zero.