Go to the first, previous, next, last section, table of contents.


Data types

This section describes some fundamental GAS data types.

Symbols

The definition for struct symbol, also known as symbolS, is located in `struc-symbol.h'. Symbol structures contain the following fields:

sy_value
This is an 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 resolve_symbol_value is called in write_object_file. The expression is often simply a constant. Before resolve_symbol_value is called, the value is the offset from the frag (see section Frags). Afterward, the frag address has been added in.
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.
sy_resolving
This field is used to detect loops while resolving the symbol's value.
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.
sy_next
sy_previous
These pointers to other symbolS structures describe a singly or doubly linked list. (If SYMBOLS_NEED_BACKPOINTERS is not defined, the sy_previous field will be omitted; SYMBOLS_NEED_BACKPOINTERS is always defined if BFD_ASSEMBLER.) These fields should be accessed with the symbol_next and symbol_previous macros.
sy_frag
This points to the frag (see section Frags) that this symbol is attached to.
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.
sy_mri_common
Whether the symbol is an MRI common symbol created by the COMMON pseudo-op when assembling in MRI mode.
bsym
If BFD_ASSEMBLER is defined, this points to the BFD asymbol that will be used in writing the object file.
sy_name_offset
(Only used if BFD_ASSEMBLER is not defined.) This is the position of the symbol's name in the string table of the object file. On some formats, this will start at position 4, with position 0 reserved for unnamed symbols. This field is not used until write_object_file is called.
sy_symbol
(Only used if BFD_ASSEMBLER is not defined.) This is the format-specific symbol structure, as it would be written into the object file.
sy_number
(Only used if BFD_ASSEMBLER is not defined.) This is a 24-bit symbol number, for use in constructing relocation table entries.
sy_obj
This format-specific data is of type OBJ_SYMFIELD_TYPE. If no macro by that name is defined in `obj-format.h', this field is not defined.
sy_tc
This processor-specific data is of type TC_SYMFIELD_TYPE. If no macro by that name is defined in `targ-cpu.h', this field is not defined.
TARGET_SYMBOL_FIELDS
If this macro is defined, it defines additional fields in the symbol structure. This macro is obsolete, and should be replaced when possible by uses of OBJ_SYMFIELD_TYPE and TC_SYMFIELD_TYPE.

There are a number of access routines used to extract the fields of a symbolS structure. When possible, these routines should be used rather than referring to the fields directly. These routines will work for any GAS version.

S_SET_VALUE
Set the symbol's value.
S_GET_VALUE
Get the symbol's value. This will cause resolve_symbol_value to be called if necessary, so S_GET_VALUE should only be called when it is safe to resolve symbols (i.e., after the entire input file has been read and all symbols have been defined).
S_SET_SEGMENT
Set the section of the symbol.
S_GET_SEGMENT
Get the symbol's section.
S_GET_NAME
Get the name of the symbol.
S_SET_NAME
Set the name of the symbol.
S_IS_EXTERNAL
Return non-zero if the symbol is externally visible.
S_IS_EXTERN
A synonym for S_IS_EXTERNAL. Don't use it.
S_IS_WEAK
Return non-zero if the symbol is weak.
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.
S_IS_DEFINED
Return non-zero if this symbol is defined. This function is not reliable when called on a common symbol.
S_IS_DEBUG
Return non-zero if this is a debugging symbol.
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 S_IS_EXTERNAL. The `-L' assembler option affects the return value of this function.
S_SET_EXTERNAL
Mark the symbol as externally visible.
S_CLEAR_EXTERNAL
Mark the symbol as not externally visible.
S_SET_WEAK
Mark the symbol as weak.
S_GET_TYPE
S_GET_DESC
S_GET_OTHER
Get the type, desc, and other fields of the symbol. These are only defined for object file formats for which they make sense (primarily a.out).
S_SET_TYPE
S_SET_DESC
S_SET_OTHER
Set the type, desc, and other fields of the symbol. These are only defined for object file formats for which they make sense (primarily a.out).
S_GET_SIZE
Get the size of a symbol. This is only defined for object file formats for which it makes sense (primarily ELF).
S_SET_SIZE
Set the size of a symbol. This is only defined for object file formats for which it makes sense (primarily ELF).

Expressions

Expressions are stored in an expressionS structure. The structure is defined in `expr.h'.

The macro expression will create an expressionS structure based on the text found at the global variable input_line_pointer.

A single expressionS structure can represent a single operation. Complex expressions are formed by creating expression symbols and combining them in expressionS structures. An expression symbol is created by calling make_expr_symbol. An expression symbol should naturally never appear in a symbol table, and the implementation of S_IS_LOCAL (see section Symbols) reflects that. The function 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 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 operatorT, and describes how to interpret the other fields; see the definition in `expr.h' for the possibilities.

An operatorT value of O_big indicates either a floating point number, stored in the global variable generic_floating_point_number, or an integer to large to store in an offsetT type, stored in the global array generic_bignum. This rather inflexible approach makes it impossible to use floating point numbers or large expressions in complex expressions.

Fixups

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

A fixup is created by a call to fix_new or fix_new_exp. Both take a frag (see section Frags), a position within the frag, a size, an indication of whether the fixup is PC relative, and a type. In a BFD_ASSEMBLER GAS, the type is nominally a bfd_reloc_code_real_type, but several targets use other type codes to represent fixups that can not be described as relocations.

The fixS structure has a number of fields, several of which are obsolete or are only used by a particular target. The important fields are:

fx_frag
The frag (see section Frags) this fixup is in.
fx_where
The location within the frag where the fixup occurs.
fx_addsy
The symbol this fixup is against. Typically, the value of this symbol is added into the object contents. This may be NULL.
fx_subsy
The value of this symbol is subtracted from the object contents. This is normally NULL.
fx_offset
A number which is added into the fixup.
fx_addnumber
Some CPU backends use this field to convey information between md_apply_fix and tc_gen_reloc. The machine independent code does not use it.
fx_next
The next fixup in the section.
fx_r_type
The type of the fixup. This field is only defined if BFD_ASSEMBLER, or if the target defines NEED_FX_R_TYPE.
fx_size
The size of the fixup. This is mostly used for error checking.
fx_pcrel
Whether the fixup is PC relative.
fx_done
Non-zero if the fixup has been applied, and no relocation entry needs to be generated.
fx_file
fx_line
The file and line where the fixup was created.
tc_fix_data
This has the type TC_FIX_TYPE, and is only defined if the target defines that macro.

Frags

The fragS structure is defined in `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.

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 relax_segment fills in this field.
fr_next
Pointer to the next frag in this (sub)section.
fr_fix
Fixed number of characters we know we're going to emit to the output file. May be zero.
fr_var
Variable number of characters we may output, after the initial fr_fix characters. May be zero.
fr_offset
The interpretation of this field is controlled by fr_type. Generally, if fr_var is non-zero, this is a repeat count: the fr_var characters are output fr_offset times.
line
Holds line number info when an assembler listing was requested.
fr_type
Relaxation state. This field indicates the interpretation of fr_offset, 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 fr_fix characters; they are always supposed to be output verbatim (fixups aside). See below for specific values this field can have.
fr_subtype
Relaxation substate. If the macro md_relax_frag isn't defined, this is assumed to be an index into TC_GENERIC_RELAX_TABLE for the generic relaxation code to process (see section Relaxation). If md_relax_frag is defined, this field is available for any use by the CPU-specific code.
fr_symbol
This normally indicates the symbol to use when relaxing the frag according to fr_type.
fr_opcode
Points to the lowest-addressed byte of the opcode, for use in relaxation.
fr_pcrel_adjust
fr_bsr
These fields are only used in the NS32k configuration. But since struct frag is defined before the CPU-specific header files are included, they must unconditionally be defined.
fr_file
fr_line
The file and line where this frag was last modified.
fr_literal
Declared as a one-character array, this last field grows arbitrarily large to hold the actual contents of the frag.

These are the possible relaxation states, provided in the enumeration type relax_stateT, and the interpretations they represent for the other fields:

rs_align
rs_align_code
The start of the following frag should be aligned on some boundary. In this frag, fr_offset is the logarithm (base 2) of the alignment in bytes. (For example, if alignment on an 8-byte boundary were desired, fr_offset would have a value of 3.) The variable characters indicate the fill pattern to be used. The 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 fr_subtype value of 0 means no maximum, which is the normal case. Target backends can use rs_align_code to handle certain types of alignment differently.
rs_broken_word
This indicates that "broken word" processing should be done (see section Broken words). If broken word processing is not necessary on the target machine, this enumerator value will not be defined.
rs_fill
The variable characters are to be repeated fr_offset times. If fr_offset is 0, this frag has a length of fr_fix. Most frags have this type.
rs_machine_dependent
Displacement relaxation is to be done on this frag. The target is indicated by fr_symbol and fr_offset, and fr_subtype indicates the particular machine-specific addressing mode desired. See section Relaxation.
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 fr_symbol and fr_offset; one character from the variable-length tail is used as the fill character.

A chain of frags is built up for each subsection. The data structure describing a chain is called a frchainS, and contains the following fields:

frch_root
Points to the first frag in the chain. May be NULL if there are no frags in this chain.
frch_last
Points to the last frag in the chain, or NULL if there are none.
frch_next
Next in the list of frchainS structures.
frch_seg
Indicates the section this frag chain belongs to.
frch_subseg
Subsection (subsegment) number of this frag chain.
fix_root, fix_tail
(Defined only if BFD_ASSEMBLER is defined). Point to first and last fixS structures associated with this subsection.
frch_obstack
Not currently used. Intended to be used for frag allocation for this subsection. This should reduce frag generation caused by switching sections.
frch_frag_now
The current frag for this subsegment.

A frchainS corresponds to a subsection; each section has a list of 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 frag_now. More space is allocated for the current frag using the frag_more function; this returns a pointer to the amount of requested space. Relaxing is done using variant frags allocated by frag_var or frag_variant (see section Relaxation).


Go to the first, previous, next, last section, table of contents.