
@section Introduction

This chapter is under construction!


This chapter describes some of the internals of @command{vasm}
and tries to explain
what has to be done to write a cpu module, a syntax module
or an output module for @command{vasm}.
However, if someone wants to write one, I suggest to contact me first,
so that it can be integrated into the source tree.

Note that this documentation may mention explicit values when introducing
symbolic constants. This is due to copying and pasting from the source
code. These values may not be up to date and in some cases can be overridden.
Therefore do never use the absolute values but rather the symbolic
representations.


@section Building vasm

This section deals with the steps necessary to build the typical
@command{vasm} executable from the sources.

@subsection Directory Structure

    The vasm-directory contains the following important files and
    directories:
@table @file
@item    vasm/
The main directory containing the assembler sources.

@item    vasm/Makefile
The Makefile used to build @command{vasm}.

@item    vasm/syntax/<syntax-module>/
Directories for the syntax modules.

@item    vasm/cpus/<cpu-module>/
Directories for the cpu modules.

@item vasm/obj/
Directory the object files will be stored in.

@end table

    All compiling is done from the main directory and
    the executables will be placed there as well.
    The main assembler for a combination of @code{<cpu>} and
    @code{<syntax>} will be called @command{vasm<cpu>_<syntax>}.
    All output modules are usually integrated in every executable
    and can be selected at runtime. Otherwise you have to adapt
    the @code{OUTFMTS} definition in @file{make.rules} and select
    those you want.

@subsection Adapting the Makefile

    Before building anything you have to insert correct values for
    your compiler and operating system in the @file{Makefile}.

@table @code
    @item TARGET
       Here you may define an extension which is appended to the executable's
       name. Useful, if you build various targets in the same directory.

    @item TARGETEXTENSION
       Defines the file name extension for executable files. Not needed for
       most operating systems. For Windows it would be @file{.exe}.

    @item CC
       Here you have to insert a command that invokes an ANSI C
       compiler you want to use to build vasm. It must support
       the @option{-I} option in the same way like e.g. @command{vc} or
       @command{gcc}.

    @item COPTS
       Here you will usually define an option like @option{-c} to instruct
       the compiler to generate an object file.
       Additional options, like the optimization level, should also be
       inserted here as well. Specifying the host OS helps to determine
       work-directories for DWARF and defines the appropriate internal
       symbol for the host's file system path style. The following are
       supported:
       @table @code
          @item -DAMIGA
          AmigaOS (M68k or PPC), MorphOS, AROS.
          Defines the internal symbol @code{__AMIGAFS}.
          @item -DATARI
          Atari TOS.
          Defines the internal symbol @code{__MSDOSFS}.
          @item -DMSDOS
          CP/M, MS-DOS, Windows.
          Defines the internal symbol @code{__MSDOSFS}.
          @item -DUNIX
          All kinds of Unix (Linux, BSD) including MacOSX and Atari-MiNT.
          Defines the internal symbol @code{__UNIXFS}.
          @item -D_WIN32
          Windows.
          Defines the internal symbol @code{__MSDOSFS}.
       @end table
       Building without specifying a host-OS is allowed. Then vasm
       defaults to Unix-style path handling and will not define a
       file system symbol for conditional assembly.
       Other options:
       @table @code
          @item -DLOWMEM
          Builds for a host-OS with a low amount of memory. This will
          basically reduce all hash tables to minimal size.
       @end table

    @item CCOUT
       Here you define the option which is used to specify the name of
       an output file, which is usually @option{-o}.

    @item LD
       Here you insert a command which starts the linker. This may be the
       the same as under @code{CC}.

    @item LDFLAGS 
       Here you have to add options which are necessary for linking.
       E.g. some compilers need special libraries for floating-point.

    @item LDOUT
       Here you define the option which is used by the linker to specify
       the output file name.

    @item RM
      Specify a command to delete a file, e.g. @code{rm -f}.
@end table

    An example for the Amiga using @command{vbcc} would be:
@example
      TARGET = _os3
      TARGETEXTENSION =
      CC = vc +aos68k
      CCOUT = -o
      COPTS = -c -c99 -cpu=68020 -DAMIGA -O1
      LD = $(CC)
      LDOUT = $(CCOUT)
      LDFLAGS = -lmieee
      RM = delete force quiet
@end example

    An example for a typical Unix-installation would be:
@example
      TARGET =
      TARGETEXTENSION =
      CC = gcc
      CCOUT = -o
      COPTS = -c -O2
      LD = $(CC)
      LDOUT = $(CCOUT)
      LDFLAGS = -lm
      RM = rm -f
@end example

Open/Net/Free/Any BSD systems will probably require an additional
@option{-D_ANSI_SOURCE} in @code{COPTS}.


@subsection Building vasm

Note to users of BSD systems: You will probably have to use
GNU make instead of BSD make, i.e. in the following examples replace "make"
with "gmake".

    Type:
@example
      make CPU=<cpu> SYNTAX=<syntax>
@end example
    For example:
@example
      make CPU=ppc SYNTAX=std
@end example

The following CPU modules can be selected:
@itemize
@item @code{CPU=6502}
@item @code{CPU=6800}
@item @code{CPU=6809}
@item @code{CPU=arm}
@item @code{CPU=c16x}
@item @code{CPU=hans}
@item @code{CPU=jagrisc}
@item @code{CPU=m68k}
@item @code{CPU=pdp11}
@item @code{CPU=ppc}
@item @code{CPU=qnice}
@item @code{CPU=spc700}
@item @code{CPU=test}
@item @code{CPU=tr3200}
@item @code{CPU=unsp}
@item @code{CPU=vidcore}
@item @code{CPU=x86}
@item @code{CPU=z80}
@end itemize

The following syntax modules can be selected:
@itemize
@item @code{SYNTAX=std}
@item @code{SYNTAX=mot}
@item @code{SYNTAX=madmac}
@item @code{SYNTAX=oldstyle}
@item @code{SYNTAX=test}
@end itemize

For Windows and various Amiga targets there are already Makefiles included,
which you may either copy on top of the default @file{Makefile}, or call
it explicitly with @command{make}'s @option{-f} option:
@example
    make -f Makefile.OS4 CPU=ppc SYNTAX=std
@end example


@section vasm global variables

Important global variables, which may be read or modified by
syntax-, cpu- or output-modules.

@table @code

@item source *cur_src;
Pointer to the current source text instance (see structures below).

@item char *defsectname;
Name of a default section which vasm creates when a label or code occurs
in the source without any preceding @code{section} or @code{org} directive.
Assigning NULL means that the default is an absolute section and its
base address is taken from @code{defsectorg}.
These @code{defsect...} variables can be overridden by syntax- or
output-modules.

@item taddr defsectorg;
Used when @code{defsectname==NULL}. Defines the base address of a default
absolute @code{org} section.

@item char *defsecttype;
Attributes of the default section (see above). May be NULL to indicate
that no default has been defined and vasm will show an error.

@item char emptystr[];
An empty string (zero length).

@item int exec_out;
Non-zero, when the output file is an executable and not an object file.

@item char *filename;
Defaults to the file part of the input source file name. Syntax modules
may modify it with @code{setfilename(char *)} and output modules may
use it for their own purpose.

@item char *inname;
Input source file name.

@item int octetsperbyte;
Number of 8-bit bytes used to represent a backend's target-byte. The macro
@code{OCTETS(n)} may be used to calculate the number of 8-bit bytes for
@code{n} target-bytes.

@item char *outname;
Output object file name.

@item int output_bitsperbyte;
May be assigned by an output module with @code{1} during its init function,
to indicate that it supports target-bytes with @code{BITSPERBYTE}.
Otherwise an output module is expected to support 8-bit bytes only.

@end table


@section General data structures

This section describes the fundamental data structures used in vasm
which are usually necessary to understand for writing any kind of
module (cpu, syntax or output). More detailed information is given in
the respective sections on writing specific modules where necessary.

@subsection Source

A source structure represents a source text module, which can be
either the main source text, an included file, a macro or a repetition.
There is always a link to the parent source from where the current
source context was included or called.

@table @code
@item struct source *parent;
        Pointer to the parent source context. Assembly continues there
        when the current source context ends.

@item int parent_line;
        Line number in the parent source context, from where we were called.
        This information is needed, because line numbers are only reliable
        during parsing and later from the atoms. But an include directive
        doesn't create an atom.

@item struct source_file *srcfile;
        The @code{source_file} structure has the unique file name, index
        and text-pointer for this source text instance.
        Used for debugging output, like DWARF.

@item char *name;
        File name of the main source or include file, or macro name.

@item char *text;
        Pointer to the source text start.

@item size_t size;
        Size of the source text to assemble in bytes.

@item struct source *defsrc;
        This is a @code{NULL}-pointer for real source text files. Otherwise
        it is a reference to the source which defines the current macro
        or repetition.

@item int defline;
        Valid when @code{defsrc} is not @code{NULL}. Contains the starting
        line number of a macro or repetition in a source text file.

@item macro *macro;
        Pointer to macro structure, when currently inside a macro
        (see also @code{num_params}).

@item unsigned long repeat;
        Number of repetitions of this source text. Usually this is 1, but
        for text blocks between a @code{rept} and @code{endr} (or similar)
        directive it allows any number of repetitions, which is decremented
        every time the end of the source text block is reached.

@item long reptn;
        Current value of the repetition
        counter symbol in this source instance. So it can be restored when
        reentering this instance.

@item char *reptcntname;
        Name of an optional iterator symbol (when @code{reptcntname} is not
        @code{NULL}), which is set to the current value of @code{reptn}.

@item char *irpname;
        Name of the iterator symbol in special repeat loops, which use a
        sequence of arbitrary values, being assigned to this symbol within
        the loop. Example: @code{irp} directive in std-syntax.

@item struct macarg *irpvals;
        A list of arbitrary values to iterate over in a loop. With each
        iteration the frontmost value is removed from the list until it is
        empty.

@item int cond_level;
        Current level of conditional nesting while entering this source
        text. It is automatically restored to the previous level when
        leaving the source prematurely through @code{end_source()}.

@item struct macarg *argnames;
        The current list of named macro arguments.

@item int num_params;
        Number of macro parameters passed at the invocation point from
        the parent source. For normal source files this entry will be -1.
        For macros 0 (no parameters) or higher.

@item char *param[MAXMACPARAMS];
        Pointers to the macro arguments.

@item int param_len[MAXMACPARAMS];
        Number of characters per macro argument.

@item int num_quals;
        (If @code{MAX_QUALIFIERS!=0}.) Number of qualifiers for a macro.
        when not passed on invocation these are the default qualifiers.

@item char *qual[MAX_QUALIFIERS];
        (If @code{MAX_QUALIFIERS!=0}.) Pointer to macro qualifiers.

@item int qual_len[MAX_QUALIFIERS];
        (If @code{MAX_QUALIFIERS!=0}.) Number of characters per macro qualifier.

@item unsigned long id;
        Every source has its unique id. Useful for macros supporting
        the special @code{\@@} argument for creating unique labels.

@item char *srcptr;
        The current source text pointer, pointing to the beginning of
        the next line to assemble.

@item int line;
        Line number in the current source context. After parsing, the
        line number of the current atom is stored here.

@item size_t bufsize;
        Current size of the line buffer (@code{linebuf}). The size of the
        line buffer is extended automatically, when an overflow happens.

@item char *linebuf;
        A buffer for the current line being assembled
        in this source text. A child-source, like a macro, can refer to
        arguments from this buffer, so every source has got its own.
        When returning to the parent source, the linebuf is deallocated
        to save memory.

@item expr *cargexp;
        (If @code{CARGSYM} was defined.) Pointer to the current expression
        assigned to the CARG-symbol (used to select a macro argument) in
        this source instance. So it can be restored when reentering this
        instance.
@end table

@subsection Sections

One of the top level structures is a linked list of sections describing
continuous blocks of memory. A section is specified by an object of
type @code{section} with the following members that can be accessed by
the modules:

@table @code
@item  struct section *next;
        A pointer to the next section in the list.

@item  char *name;
        The name of the section.

@item  char *attr;
        A string describing the section flags in ELF notation (see,
        for example, documentation of the @code{.section} directive in
        the standard syntax module).

@item  atom *first;
@itemx atom *last;
        Pointers to the first and last atom of the section. See following
        sections for information on atoms.

@item  atom *end;
        To be used by output modules. If not @code{NULL}, then it marks the
        end of initialized data and the first atom which belongs to
        uninitialized space. Uninitialized space is usually not written
        to the output file.

@item  taddr align;
        Alignment of the section in target-bytes.

@item  uint32_t flags;
        Flags of the section. Currently available flags are:
@table @code
@item HAS_SYMBOLS
        At least one symbol is defined in this section.
@item RESOLVE_WARN
        The current atom changed its size multiple times, so atom_size()
        is now called with this flag set in its section to make the
        backend (e.g. @code{instruction_size()}) aware of it and do less
        aggressive optimizations.
@item UNALLOCATED
        Section is unallocated, which means it doesn't use any memory space
        in the output file. Such a section will be removed before creating
        the output file and all its labels converted into absolute expression
        symbols. Used for "offset" sections. Refer to
        @code{switch_offset_section()}.
@item LABELS_ARE_LOCAL
        As long as this flag is set new labels in a section are defined
        as local labels, with the section name as global parent label.
@item ABSOLUTE
        Section is loaded at an absolute address in memory.
@item PREVABS
        Remembers state of the @code{ABSOLUTE} flag before entering
        relocated-@code{org} mode (@code{IN_RORG}). So it can be restored later.
@item IN_RORG
        Section has entered relocated-org mode, which also sets the
        @code{ABSOLUTE} flag. In this mode code is written into the current
        section, but relocated to an absolute address. No relocation
        table entries are generated.
@item NEAR_ADDRESSING
        Section is marked as suitable for cpu-specific "near" addressing
        modes. For example, base-register relative or zero/direct-page.
        The cpu backend can use this information as an optimization hint
        when referencing symbols from this section.
@item FAR_ADDRESSING
        Section requires cpu-specific "far" addressing modes. For example
        an addressing mode including the bank or "segment". The cpu backend
        may use this information to select appropriate addressing modes
        when referencing symbols from this section.
@end table

@item  taddr org;
        Start address of a section. Usually zero.
        Set to an absolute start address in @code{ABSOLUTE} mode.

@item  taddr pc;
        Current address in this section. Can be used
        while traversing through the section. Has to be updated by a
        module using it. Is set to @code{org} at the beginning.

@item   unsigned long idx;
        A member usable by the output module for private purposes.

@item   section_extc extc;
        (if @code{HAVE_CPU_SECT_EXTENSION} is set.)
        Backend-specifc extension of the section.
@end table

@subsection Symbols

Symbols are represented by a linked list of type @code{symbol} with the
following members that can be accessed by the modules:.

@table @code

@item  int type;
        Type of the symbol. Available are:
@table @code
@item #define LABSYM 1
        The symbol is a label defined at a specific location.

@item #define IMPORT 2
        The symbol is externally defined and its value is unknown.

@item #define EXPRESSION 3
        The symbol is defined using an expression (equate).
@end table

@item  uint32_t flags;
        Flags of this symbol. Available are:
@table @code
@item #define TYPE_UNKNOWN  0
        The symbol has no type information.

@item #define TYPE_OBJECT   1
        The symbol defines an object.

@item #define TYPE_FUNCTION 2
        The symbol defines a function.

@item #define TYPE_SECTION  3
        The symbol defines a section.

@item #define TYPE_FILE     4
      The symbol defines a file.  

@item #define EXPORT (1<<3)
        The symbol is exported to other object files.

@item #define INEVAL (1<<4)
        Used internally.

@item #define COMMON (1<<5)
        The symbol is a common symbol and also has a size.
        It will be allocated by the linker.

@item #define WEAK (1<<6)
        The symbol is weak, which means the linker may overwrite it with
        any global definition of the same name. Weak symbols may also stay
        undefined, in which case the linker would assign them a value of
        zero.

@item #define LOCAL (1<<7)
        Only informational. A symbol can be explicitly declared as local
        by a syntax-module directive. Otherwise all symbols without the
        @code{EXPORT} flag are not considered for object linking.

@item #define VASMINTERN (1<<8)
        Vasm-internal symbol, which must not be exported into an object
        file.

@item #define PROTECTED (1<<9)
        Used internally to protect the current-PC symbol from deletion.

@item #define REFERENCED (1<<10)
        Symbol was referenced in the source and a relocation entry has
        been created.

@item #define ABSLABEL (1<<11)
        Label was defined inside an absolute section, or during a code block
        in relocated-org mode. Therefore it has an absolute address and will
        not generate a relocation entry when being referenced.

@item #define EQUATE (1<<12)
        Symbols flagged as @code{EQUATE} are constant expressions and their
        value must not be changed.

@item #define REGLIST (1<<13)
        Symbol is a register list definition.

@item #define USED (1<<14)
        Symbol appeared in an expression. Symbols which were only defined,
        (as label or equate) and otherwise never appear throughout the
        whole source, don't get this flag set.

@item #define NEAR (1<<15)
        Symbol may be referenced by "near" addressing mode. For example,
        base register relative. Used as an optimization hint to the cpu
        backend.

@item #define XDEF (1<<16)
        This symbol must become defined in the source. Which means
        its @code{type} must not remain @code{IMPORT}. Otherwise a
        warning is displayed.

@item #define XREF (1<<17)
        Symbol is externally defined and its @code{type} must never
        become something else than @code{IMPORT}. Otherwise an error
        is displayed.

@item #define SYMINDIR (1<<18)
        For @code{EXPRESSION} symbols only: the expression's base-symbol
        represents the referenced indirect symbol name.

@item #define RSRVD_S (1L<<24)
        The range from bit 24 to 27 (counted from the LSB) is reserved for
        use by the syntax module.

@item #define RSRVD_O (1L<<28)
        The range from bit 28 to 31 (counted from the LSB) is reserved for
        use by the output module.
@end table

The type-flags can be extracted using the @code{TYPE()} macro which
expects a pointer to a symbol as argument.

@item  char *name;
        The name of the symbol.

@item   expr *expr;
        The expression in case of @code{EXPRESSION} symbols.

@item   expr *size;
        The size of the symbol in target-bytes, if specified.
        Common symbols always have a size.

@item  section *sec;
        The section a @code{LABSYM} symbol is defined in.

@item  taddr pc;
        The address of a @code{LABSYM} symbol.

@item  taddr align;
        The alignment of the symbol in target-bytes.

@item  unsigned long idx;
        A member usable by the output module for private purposes.

@end table

The case-sensitivity of symbols defaults to case-sensitive, which can be
changed by the command line option @option{-nocase}. Syntax- or cpu-modules
may change it in their init-function, or even during parsing, by calling
@code{set_nocase_symbols(int nc)} (where @code{nc=1} means case-insensitive,
@code{nc=0} means case-sensitive and @code{nc=-1} resets to the state defined
by the command line). But note, that you cannot expect to access symbols from
a part of the input source with different case-sensitivity.

@subsection Register symbols

Optional register symbols are available when the backend defines
@code{HAVE_REGSYMS} in @file{cpu.h} and initializes the system before
first use, typically during @code{init_cpu()}.

For initialization you have to specify the hash table size and the
case-sensitivity, using one of the following functions:
@table @code
@item int init_regsyms(size_t htsize,int no_case)
  Initializes the register symbol hash table with the given size and
  case-sensitivity (nonzero for case-insensitive).
  Returns non-zero on success.
@item int init_regsyms_c(size_t htsize)
  Same as above, for case-sensitive symbols.
@item int init_regsyms_nc(size_t htsize)
  Same as above, for case-insensitive symbols.
@item int init_regsyms_sc(size_t htsize)
  Uses the symbol default case-sensitivity.
@item void set_nocase_regsyms(int nc)
  Change case-sensitivity for register symbols to case-insensitive (@code{nc==1}),
  case-sensitive (@code{nc==0}) or using the symbol default (@code{nc==-1}).
  The same note as for @code{set_nocase_symbols()} (see above) applies.
@end table

A register symbol is defined by an object of type @code{regsym}
with the following members that can be accessed by the modules:

@table @code
@item char *reg_name;
      Symbol name.
@item int reg_type;
      Optional type of register.
@item unsigned int reg_flags;
      Optional register symbol flags.
@item unsigned int reg_num;
      Register number or value.
@end table

Refer to @file{symbol.h} for functions to create and find register
symbols.

@subsection Atoms

The contents of each section are a linked list built out of non-separable
atoms. The general structure of an atom is:

@example
struct atom @{
  struct atom *next;
  int type;
  taddr align;
  taddr lastsize;
  unsigned changes;
  source *src;
  int line;
  listing *list;
  union @{
    instruction *inst;
    dblock *db;
    symbol *label;
    sblock *sb;
    defblock *defb;
    void *opts;
    int srcline;
    char *ptext;
    printexpr *pexpr;
    expr *roffs;
    taddr *rorg;
    assertion *assert;
    aoutnlist *nlist;
  @} content;
@};
@end example

The members have the following meaning:

@table @code
@item  struct atom *next;
Pointer to the following atom (@code{NULL} if last).

@item  int type;
The type of the atom. Can be one of
@table @code
@item #define VASMDEBUG 0
Used for internal debugging.

@item #define LABEL 1
A label is defined here.

@item #define DATA  2
A fixed number of target-bytes with constant data are put here.

@item #define INSTRUCTION 3
Generally refers to a machine instruction or pseudo/opcode. These atoms
can change their size during optimization passes and will be translated to
@code{DATA}-atoms later.

@item #define SPACE 4
Defines a block of data filled with one value of a given size (up to
@code{MAXPADSIZE} 8-bit bytes). BSS sections usually contain only such atoms,
but they are also sometimes useful as shorter versions of
@code{DATA}-atoms in other sections.

@item #define DATADEF 5
Defines data of fixed size which can contain cpu specific operands and
expressions. Usually generated by data in a source text, which are no
machine instructions. Will be translated to @code{DATA}-atoms later.

@item #define LINE 6
A source text line number (usually from a higher level language) is bound
to the atom's address. Useful for source level debugging in certain ABIs.

@item #define OPTS 7
A means to change assembler options at a specific source text line.
For example optimization settings, or the cpu type to generate code for.
The cpu backend has to define @code{HAVE_CPU_OPTS} and export the required
functions if it wants to use this type of atom.

@item #define PRINTTEXT 8
A string is printed to stdout during the final assembler pass. A newline
is automatically appended.

@item #define PRINTEXPR 9
Prints the value of an expression during the final assembler pass to stdout.

@item #define ROFFS 10
Set the program counter to an address relative to the section's start
address. These atoms will be translated into @code{SPACE} atoms in the
final pass.

@item #define RORG 11
Assemble this block under the given base address, while the code is still
written into the original memory region.

@item #define RORGEND 12
Ends a RORG block and returns to the original addressing.

@item #define ASSERT 13
The assertion expression is checked in the final pass and an error message
is generated (using the expression string and an optional message out of
this atom) when it evaluates to 0.

@item #define NLIST 14
Defines a stab-entry for the a.out object file format. nlist-style stabs
can also occur embedded in other object file formats, like ELF.
@end table

@item taddr align;
The alignment of this atom. Address must be dividable by @code{align}.

@item taddr lastsize;
The size of this atom in the last resolver pass. When the size has
changed in the current pass, the assembler will request another resolver
run through the section.

@item unsigned changes;
Number of changes in the size of this atom since pass number
@code{FASTOPTPHASE}. An increasing number usually indicates a problem in
the cpu backend's optimizer and will be flagged by setting
@code{RESOLVE_WARN} in the Section flags, as soon as @code{changes} exceeds
@code{MAXSIZECHANGES}. So the backend can choose not to optimize this atom
as aggressive as before.

@item source *src;
Pointer to the source text object to which this atom belongs.

@item  int line;
The source line number that created this atom.

@item listing *list;
Pointer to the listing file object to which this atom belongs.

@item    instruction *inst;
(In union @code{content}.) Pointer to an instruction structure in the case
of an @code{INSTRUCTION}-atom. Contains the following elements:
@table @code
@item  int code;
The cpu specific code of this instruction.

@item  char *qualifiers[MAX_QUALIFIERS];
(If @code{MAX_QUALIFIERS!=0}.) Pointer to the qualifiers of this instruction.

@item  operand *op[MAX_OPERANDS];
(If @code{MAX_OPERANDS!=0}.) The cpu-specific operands of this instruction.

@item  instruction_ext ext;
(If the cpu backend defines @code{HAVE_INSTRUCTION_EXTENSION}.)
A cpu-specific typedef. Typically used to store appropriate
opcodes, allowed addressing modes, supported cpu derivates etc.
@end table

@item    dblock *db;
(In union @code{content}.) Pointer to a dblock structure in the case
of a @code{DATA}-atom. Contains the following elements:
@table @code
@item  taddr size;
The number of target-bytes stored in this atom.

@item    uint8_t *data;
A pointer to the constant data. Consider using @code{writebyte()} or
@code{setval()} to write target-bytes which are different from 8 bits.
The internal ordering of target-bytes on an 8-bit host is big-endian,
and a target-byte will always allocate the next minimal number of
8-bit host-bytes. The macro @code{OCTETS(n)} may be used to calculate
the number of host-bytes required to represent @code{n} target-bytes.

@item  rlist *relocs;
A pointer to relocation information for the data.
@end table

@item    symbol *label;
(In union @code{content}.) Pointer to a symbol structure in the case
of a @code{LABEL}-atom.

@item    sblock *sb;
(In union @code{content}.) Pointer to a sblock structure in the case
of a @code{SPACE}-atom. Contains the following elements:
@table @code
@item size_t space;
The number of space-elements (see below) to generate here.

@item expr *space_exp;
The above size as an expression, which will be evaluated during assembly
and copied to @code{space} in the final pass.

@item size_t size;
The size of each space-element and of the fill-pattern in target-bytes.

@item uint8_t fill[MAXPADSIZE];
The fill pattern, up to MAXPADSIZE 8-bit bytes.

@item expr *fill_exp;
Optional. Evaluated and copied to @code{fill} in the final pass, when not null.

@item rlist *relocs;
A pointer to relocation information for the space.

@item taddr maxalignbytes;
An optional number of maximum padding bytes to fulfil the atom's alignment
requirement. Zero means there is no restriction.

@item uint32_t flags;
@table @code
@item SPC_UNINITIALIZED
        This space is completely uninitialized. May be used as a hint by
        output modules.
@item SPC_DATABSS
        The output module should not allocate any file space for this
        atom, when possible (example: DataBss section, as supported by
        the "hunkexe" output file format). It is not needed to set this
        flag when the output section is BSS.
@end table

@end table

@item    defblock *defb;
(In union @code{content}.) Pointer to a defblock structure in the case
of a @code{DATADEF}-atom. Contains the following elements:
@table @code
@item  taddr bitsize;
The size of the definition in bits.

@item  operand *op;
Pointer to a cpu-specific operand structure.

@end table

@item    void *opts;
(In union @code{content}.) Points to a cpu-backend specific options object
in the case of a @code{OPTS}-atom.

@item    int srcline;
(In union @code{content}.) Line number for source level debugging in the
case of a @code{LINE}-atom.

@item    char *ptext;
(In union @code{content}.) A string to print to stdout in case of a
@code{PRINTTEXT}-atom.

@item    printexpr *pexpr;
(In union @code{content}.) Pointer to a printexpr structure in the case of
a @code{PRINTEXPR}-atom. Contains the following elements:
@table @code
@item expr *print_exp;
Pointer to an expression to evaluate and print.

@item short type;
Format type of the printed value. We can print as hexadecimal
(@code{PEXP_HEX}), signed decimal (@code{PEXP_SDEC}),
unsigned decimal (@code{PEXP_UDEC}), binary (@code{PEXP_BIN}) OR
ASCII (@code{PEXP_ASC}).

@item short size;
Size (precision) of the printed value in bits. Excessive bits will be
masked out, and sign-extended when requested.
@end table

@item    expr *roffs;
(In union @code{content}.) The expression holds the relative section offset
to align to in case of a @code{ROFFS}-atom.

@item    taddr *rorg;
(In union @code{content}.) Assemble the code under the base address in
@code{rorg} in case of a @code{RORG}-atom.

@item    assertion *assert;
(In union @code{content}.) Pointer to an assertion structure in the case of
an @code{ASSERT}-atom. Contains the following elements:
@table @code
@item expr *assert_exp;
Pointer to an expression which should evaluate to non-zero.

@item char *exprstr;
Pointer to the expression as text (to be used in the output).

@item char *msgstr;
Pointer to the message, which would be printed when @code{assert_exp} evaluates
to zero.
@end table

@item    aoutnlist *nlist;
(In union @code{content}.) Pointer to an nlist structure, describing an
aout stab entry, in case of an @code{NLIST}-atom. Contains the following
elements:
@table @code
@item char *name;
Name of the stab symbol.
@item int type;
Symbol type. Refer to @code{stabs.h} for definitions.
@item int other;
Defines the nature of the symbol (function, object, etc.).
@item int desc;
Debugger information.
@item expr *value;
Symbol's value.
@end table

@end table

@subsection Relocations

@code{DATA} and @code{SPACE} atoms can have a relocation list attached
that describes how this data must be modified when linking/relocating.
They always refer to the data in this atom only.

There are a number of predefined standard relocations and it is possible
to add other cpu-specific relocations. Note however, that it is always
preferable to use standard relocations, if possible. Chances that an
output module supports a certain relocation are much higher if it is a
standard relocation.

A relocation list uses this structure:

@example
typedef struct rlist @{
  struct rlist *next;
  void *reloc;
  int type;
@} rlist;
@end example

@code{type} identifies the relocation type. All the standard relocations have
type numbers between @code{FIRST_STANDARD_RELOC} and 
@code{LAST_STANDARD_RELOC}. Consider @file{reloc.h} to see which
standard relocations are available.

Standard types may be combined with the modifier flags @code{REL_MOD_S}
for signed and @code{REL_MOD_U} for unsigned relocations. The default,
when both flags are missing, is to check the value being inserted into
the given relocation field against both ranges, signed and unsigned.
Setting both flags together is illegal!

Typical signed relocations are PC-relative. An example for an
unsigned relocation would be a zero- or direct-page addressing mode
on the 6502/6809 families. If you are unsure, just don't set any of
these flags.

To get access to the real standard relocation type, without any
flags, you have to use the @code{STD_REL_TYPE(type)} macro.

The detailed information can be accessed
via the pointer @code{reloc}. It will point to a structure that depends
on the relocation type, so a module must only use it if it knows the
relocation type.

All standard relocations point to a type @code{nreloc} structure
with the following members:
@table @code
@item  size_t byteoffset;
Offset in target-bytes, from the start of the current @code{DATA} atom, to
the beginning of the relocation field. This may also be the address which is
used as a basis for PC-relative relocations. Or a common basis for multiple
separated relocation fields, which will be translated into a single
relocation type by the output module.

@item  size_t bitoffset;
Offset in bits to the beginning of the relocation field. Adds to
@code{byteoffset*BITSPERBYTE}. Bits are counted in a bit-stream from lower
to higher address bytes. But note, that within a little-endian byte bits
are counted from the LSB to the MSB, while they are counted from the MSB to
the LSB for big-endian targets.

@item  int size;
The size of the relocation field in bits.

@item  taddr mask; 
The mask defines which portion of the relocated value is set by this
relocation field.

@item taddr addend;
Value to be added to the symbol value.

@item  symbol *sym;
The symbol referred by this relocation

@end table

To describe the meaning of these entries, we will define the steps that
shall be executed when performing a relocation:

@enumerate 1
@item Extract @code{size} number of bits from the @code{DATA} atom, starting
        with bit number @code{byteoffset*BITSPERBYTE+bitoffset}.
        We start counting bits from the lowest to the highest numbered byte
        in memory.
        Within a big-endian byte we count from the MSB to the LSB. Within
        a little-endian byte we count from the LSB to the MSB.

@item Determine the relocation value of the symbol. For a simple absolute
        relocation, this will be the value of the symbol @code{sym} plus
        the @code{addend}. For other relocation types, more complex
        calculations will be needed.
        For example, in a program-counter relative relocation,
        the value will be obtained by subtracting the address of the data
        atom plus @code{byteoffset} from the value
        of @code{sym} plus @code{addend}.

@item Calculate the bit-wise @code{AND} of the value obtained in the step
        above and the @code{mask} value.

@item Normalize, i.e. shift the value above right as many bit positions as
        there are low order zero bits in @code{mask}.

@item Add this value to the value extracted in step 1.

@item Insert the low order @code{size} bits of this value into the @code{DATA}
        atom starting with bit @code{byteoffset*BITSPERBYTE+bitoffset}.
@end enumerate


@subsection CPU-specific Relocations

Whenever a CPU module requires a relocation type which cannot be
expresssed by any standard type you have the option to define your own,
beginning with @code{FIRST_CPU_RELOC} (defined in @code{reloc.h}).
The last CPU-specific relocation has to be defined in your backend's
@code{cpu.h} by @code{LAST_CPU_RELOC}, which is also a hint for the
assembler's core routines that CPU-specific relocations do exist.

Example:
@example
/* PPC specific relocations */
#define REL_PPCEABI_SDA2 (FIRST_CPU_RELOC)
#define REL_PPCEABI_SDA21 (FIRST_CPU_RELOC+1)
#define REL_PPCEABI_SDAI16 (FIRST_CPU_RELOC+2)
#define REL_PPCEABI_SDA2I16 (FIRST_CPU_RELOC+3)
#define REL_MORPHOS_DREL (FIRST_CPU_RELOC+4)
#define REL_AMIGAOS_BREL (FIRST_CPU_RELOC+5)
#define LAST_CPU_RELOC REL_AMIGAOS_BREL
@end example

Also the CPU module must implement and export the following functions:
@table @code
@item size_t cpu_reloc_size(rlist *)
  Return the size of your cpu-specific relocation in 8-bit host-bytes for
  the given type. If this type uses the standard @code{nreloc} structure,
  just return zero.
@item void cpu_reloc_print(FILE *,rlist *)
  Print the relocation name and its parameters to the given file.
  Usually it has the form:
  @code{rname(startbyte,startbit-endbit,mask,addend,symbol)}.
  When using @code{nreloc} you may call @code{print_nreloc()}
  (refer to @code{reloc.h}) to simplify output.
@item void cpu_reloc_write(FILE *,rlist *)
  If this relocation type uses a cpu-specific structure, write it to
  the object file's relocation table in @code{VOBJ} format.
@end table

And the following data needs to be exported:
@table @code
@item extern const char *cpu_reloc_names[];
  An array of short string pointers with the name of each cpu-specific
  relocation type. The first element (index 0) is @code{FIRST_CPU_RELOC}.
@end table

Example:
@example
const char *cpu_reloc_names[(LAST_CPU_RELOC+1)-FIRST_CPU_RELOC] = {
  "sd2","sd21","sdi16","sd2i16","drel","brel"
};
@end example

Note, that support for cpu-specific relocations has to be added to
other tools reading and writing the @code{VOBJ} format, like
@command{vlink} and @command{vobjdump}, as well.
Otherwise they will be ignored (but do not cause any failure).

Also, if you want cpu-specific relocations to be recognized in other
output modules, you have to handle these types there appropriately.


@subsection Errors

Each module can provide a list of possible error messages contained
e.g. in @file{syntax_errors.h} or @file{cpu_errors.h}. They are a
comma-separated list of a printf-format string and error flags. Allowed
flags are @code{WARNING}, @code{ERROR}, @code{FATAL}, @code{MESSAGE} and
@code{NOLINE}.
They can be combined using or (@code{|}). @code{NOLINE} has to be set for
error messages during initialization or while writing the output, when
no source context is available. Errors cause the assembler to return false.
@code{FATAL} causes the assembler to terminate
immediately.

The errors can be emitted using the function @code{syntax_error(int n,...)},
@code{cpu_error(int n,...)} or @code{output_error(int n,...)}. The first
argument is the number of the error message (starting from zero). Additional
arguments must be passed according to the format string of the
corresponding error message.


@section Support Functions

Useful support functions for writing CPU-, Syntax- and Output-modules.

@subsection Memory Functions
@table @code
@item void *mymalloc(size_t sz)
  Allocate memory. See also @code{mycalloc()} and @code{myrealloc()}.
@item void myfree(void *p)
  Free an allocated memory block with one of the functions above.
@item uint64_t readval(int be,void *src,size_t size)
  Reads an unsigned value with @code{size} target-bytes and byte-ordering
  @code{be} from the @code{src} pointer (0 is little-, 1 is big-endian).
@item void *setval(int be,void *dest,size_t size,uint64_t val)
  Stores the value @code{val} to @code{dest}, which has a size of
  @code{size} target-bytes, using a byte-ordering of @code{be}
  (0 is little-, 1 is big-endian).
@item uint64_t readbits(int be,void *p,unsigned bfsize,unsigned offset,unsigned size)
  Reads an unsigned value from the bitfield with @code{bfsize} bits at
  @code{p}. @code{size} bits at bit-offset @code{offset} will be extracted.
  Use endianness @code{be} while reading the bitfield.
@item void setbits(int be,void *p,unsigned bfsize,unsigned offset,unsigned size,uint64_t d)
  Writes the value @code{d} with @code{size} bits into a bitfield at @code{p}
  with @code{bfsize} bits, starting at bit-offset @code{offset}, following
  the rules of the given endianness @code{be}.
@item utaddr readbyte(void *src)
  Reads an unsigned target-byte from @code{src}.
@item void writebyte(void *dest,utaddr val)
  Stores the value @code{val} into a target-byte at @code{dest}.
@item OCTETS(n)
  This macro expands to the number of 8-bit host-bytes required for @code{n}
  target-bytes.
@end table

@subsection Expressions
@table @code
@item expr *parse_expr(char **pp)
  Parses any expression starting at @code{*pp}. Updates @code{*pp} to point
  at the next character after the expression.
@item expr *parse_expr_tmplab(char **pp)
  Same as @code{parse_expr()}, but defines a temporary label for the PC
  symbol, so it does not change its value when this expression is
  evaluated at other section locations.
@item expr *parse_expr_huge(char **pp)
  Parses a constant expression (no labels allowed) with 128 bit integers.
@item expr *parse_expr_float(char **pp)
  Parses a floating point expression (no labels allowed), if the
  backend supports floating point constants (defines @code{FLOAT_PARSER}).
@item taddr parse_constexpr(char **pp)
  Parses an expression which is immediately evaluated to a constant value.
  Generates an error message and returns zero when it depends on
  non-constant, 128-bit (huge) or floating point values.
@item void free_expr(expr *tree)
  Free an expression.
@item int type_of_expr(expr *tree)
  Returns the type of an expression, which may be either @code{NUM},
  @code{HUG} (128 bit constant) or @code{FLT} (floating point). This
  will tell you which evaluation function to use (see below).
@item void simplify_expr(expr *tree)
  Try to evaluate the expression as far as possible. Subexpressions
  only containing constants or absolute symbols are simplified.
@item int eval_expr(expr *tree,taddr *result,section *sec,taddr pc)
  Evaluate an expression using the @code{pc} in section @code{sec} and
  store the result in @code{*result}. The return value is non-zero
  when the result is constant (i.e. only depends on constants or absolute
  symbols).
@item int eval_expr_huge(expr *tree,thuge *result)
  Evaluate a constant 128-bit integer expression, which is written to
  @code{*result}. The return value becomes zero when there were problems
  (like unsupported operations).
@item int eval_expr_float(expr *tree,tfloat *result)
  Evaluate a constant floating point expression and write the result to
  @code{*result}. The return value becomes zero when there were problems
  (like unsupported operations).
@item int find_base(expr *p,symbol **base,section *sec,taddr pc)
  Tests, if an expression is based only on one non-absolute symbol
  plus constants or minus label. Writes either that symbol-pointer to
  @code{*base} or @code{NULL}.
  The return value defines the type of base-relative
  operation, which is @code{BASE_OK} (normal base plus constant),
  @code{BASE_PCREL} (base minus label is pc-relative) or
  @code{BASE_ILLEGAL} (illegal arithmetic operation with base symbol).
@item expr *number_expr(taddr val)
  Create a constant expression from @code{val}.
@item expr *huge_expr(thuge val)
  Create a constant 128-bit expression from @code{val}.
@item expr *float_expr(tfloat val)
  Create a constant floating point expression from @code{val}.
@end table

Syntax modules may overwrite the default operator tokens from @file{expr.h}.
Every token macro follows the syntax @code{T_NAME(s)}, where @code{char *s}
points to the next token from the stream. The macro has to return the token
length in characters on match or zero otherwise. Note, that the result of
logical operations is transformed by the @code{BOOLEAN(x)} macro, which may
be overwritten by a backend, for example to define True as -1 instead of
the default 1.
The following token macros are known (default token follows the macro name):
@table @code
@item T_LOR(s) ||
  Logical Or.
@item T_LAND(s) &&
  Logical And.
@item T_EQ(s) ==
  Equality.
@item T_NEQ(s) !=
  Not equal.
@item T_LEQ(s) <=
  Lesser or equal.
@item T_GEQ(s) >=
  Greater or equal.
@item T_LT(s) <
  Lesser than.
@item T_GT(s) >
  Greater than.
@item T_ADD(s) +
  Addition.
@item T_SUB(s) -
  Subtraction.
@item T_MUL(s) *
  Multiplication.
@item T_DIV(s) /
  Division.
@item T_MOD(s) %
  Modulo.
@item T_BOR(s) |
  Bitwise Or.
@item T_XOR(s) ^
  Bitwise Exclusive Or.
@item T_BORN(s) 0
  Bitwise Or-Not, i.e. @code{|~}. Undefined by default.
@item T_BAND(s) &
  Bitwise And.
@item T_LSH(s) <<
  Shift Left.
@item T_RSH(s) >>
  Shift Right. May be signed or unsigned. A backend may set the global
  variable @code{unsigned_shift} to non-zero. Defaults to signed.
@item T_PLUS(s) +
  Unary Plus operator. Is ignored.
@item T_MINUS(s) -
  Unary Negation operator.
@item T_NOT(s) !
  Unary logical Not.
@item T_CPL(s) ~
  Unary bitwise Complementation.
@end table

Expression evalulation priority for all these tokens cannot be modified,
and is defined from highest to lowest:
@enumerate 1
@item @code{T_PLUS}, @code{T_MINUS}, @code{T_NOT}, @code{T_CPL}
@item @code{T_LSH}, @code{T_RSH}
@item @code{T_BAND}
@item @code{T_XOR}, @code{T_BORN}
@item @code{T_BOR}
@item @code{T_MUL}, @code{T_DIV}, @code{T_MOD}
@item @code{T_ADD}, @code{T_SUB}
@item @code{T_LEQ}, @code{T_GEQ}, @code{T_LT}, @code{T_GT}
@item @code{T_EQ}, @code{T_NEQ}
@item @code{T_LAND}
@item @code{T_LOR}
@end enumerate

@subsection Symbols
@table @code
@item symbol *new_abs(const char *name,expr *tree)
  Create a new absolute symbol (type @code{EXPRESSION}).
@item symbol *new_equate(const char *name,expr *tree)
  Same as @code{new_abs()} but set the @code{EQUATE} flag to indicate that
  the symbol must not change its value (unlike a @code{.set} symbol).
@item symbol *new_import(const char *name)
  Add an externally defined symbol name.
@item symbol *new_labsym(section *sec,const char *name)
  Create a label symbol (type @code{LABSYM}) for the current PC in the given
  section. Uses the current/default section when @code{sec} is @code{NULL}.
@item symbol *new_tmplabel(section *sec)
  Create a temporary label symbol with a unique name for the given section.
@item symbol *internal_abs(const char *name)
  Create an internal absolute symbol (type @code{EXPRESSION}), which gets
  the flag @code{VASMINTERN}, so it is never written into object files.
@item regsym *new_regsym(int redef,const char *name,int type,unsigned int flags,unsigned int num)
  (If @code{HAVE_REGSYMS} is set.)
  Create a new CPU register symbol with name @code{name} and number
  @code{num}. The @code{type} and @code{flags} can be used by the
  backend as needed (for example integer and floating point register type).
  A non-zero @code{redef} allows redefinition of a register symbol without
  error message.
@item regsym *find_regsym(const char *name,int len)
  (If @code{HAVE_REGSYMS} is set.)
  Find register symbol with @code{name} and @code{len} characters.
@end table

@subsection Macros, Structures and Repetitions
@table @code
@item macro *new_macro(char *name,struct namelen *maclist,struct namelen *endmlist,char *args)
  Make the parser read a new macro with the given @code{name}, which has
  @code{namelen} characters. @code{maclist} is a list of @code{struct namelen}
  structures, which define all macro directive names currently known to the
  syntax module and @code{endmlist} defines the directives which terminate a
  macro definition. The parser will use these lists to parse and store the
  body of the macro definition.
  @code{args} may optionally point to a string of named macro arguments.
  It is parsed by using the macros @code{SKIP_MACRO_ARGNAME},
  @code{MACROS_ARG_OPTS} and @code{MACRO_ARG_SEP} from @file{syntax.h}.
@item macro *find_macro(char *name,int name_len)
  Find the macro using the name at @code{name} with @code{name_len}
  characters.
@item int execute_macro(char *name,int name_len,char **q,int *q_len,int nq,char *p)
  Execute the macro with the given name (which is @code{name_len} characters
  long).
  If @code{nq} is greater than zero, @code{q} points to a list of qualifiers
  (with their length in characters defined by @code{q_len}), provided the
  cpu-backend supports qualifiers and they are not disabled for macros
  (@code{NO_MACROS_QUALIFIERS}). Missing qualifiers are set to the CPU's
  default (e.g. @code{.w} for m68k).
  Finally, @code{p} points to a string of parameters passed into the macro.
  An optional @code{EXEC_MACRO()} macro is called just before execution, when
  defined by the syntax module.
@item int leave_macro(void)
  Terminate execution of the current macro (e.g. by a @code{mexit}
  directive).
@item int undef_macro(char *name)
  Undefine this macro. It will be unknown for the remaining source text.
@item int new_structure(char *name)
  Start a structure definition using an offset-section with called @code{name}.
@item int end_structure(section **prev)
  End a structure definition and return the previously active section in
  @code{prev}. The syntax module may then do some finalizing tasks and
  switch back to this section.
@item section *find_structure(char *name,int name_len)
  Find and return the offset-section for the given structure name.
  The functionality for "executing" the structure is in the syntax module.
@item void new_repeat(int rcnt,char *name,char *vals,struct namelen *reptlist,struct namelen *endrlist)
  Make the parser repeat the source text between the following line and any
  end-repeat directive defined by @code{endrlist} @code{rcnt} times. Valid
  repeat directives are defined by @code{reptlist} for nesting.
  If @code{name} is not @code{NULL} then it defines an additional symbol name
  to be set to the current iteration counter.
  If @code{rcnt} is set to @code{REPT_IRP} then @code{vals} points to a
  string of comma separated values, which are assigned one by one for every
  iteration to the symbol with @code{name} (prefixed by a backslash).
  If @code{rcnt} is set to @code{REPT_IRPC} then @code{vals} points to a
  string of comma separated characters instead.
@item void set_nocase_macros(int nc)
  Change case-sensitivity for macro and structure names to case-insensitive
  (@code{nc==1}), case-sensitive (@code{nc==0}) or using the symbol default
  (@code{nc==-1}).
@end table

@subsection Hash Tables
Modules may create hash tables for their own purpose with any size or
case-sensitivity. Hash table entries have the type @code{hashdata}, which
is a union with currently at least the following choices:
@example
typedef union hashdata @{
  void *ptr;
  unsigned idx;
@} hashdata;
@end example

@table @code
@item hashtable *new_hashtable(size_t sz, int no_case)
  Create a new hash table with @code{sz} entries. The @code{no_case} parameter
  defines whether names will be handled case-sensitive (@code{no_case==0})
  or case-insensitive (@code{no_case==1}).
@item hashtable *new_hashtable_c(size_t sz)
  Create a new hash table with @code{sz} case-sensitive entries.
@item hashtable *new_hashtable_nc(size_t sz)
  Create a new hash table with @code{sz} case-insensitive entries.
@item hashtable *new_hashtable_sc(size_t sz)
  Create a new hash table with @code{sz} entries using the symbol default case-sensitivity.

@item void add_hashentry(hashtable *ht,const char *name,hashdata d)
  Make a hash table entry with @code{d} for the given @code{name}.
@item void rem_hashentry(hashtable *ht,const char *name)
  Remove the entry for @code{name} from the given hash table.
@item int find_name(hashtable *ht,const char *name,hashdata *d)
  Find @code{name} in the given hash table and return its hashdata in
  @code{d}. The return code is zero when @code{name} doesn't exist.
@item int find_namelen(hashtable *ht,const char *name,int len,hashdata *d)
  Find an entry which matches the string at @code{name} with @code{len}
  characters in the given hash table and return its hashdata in @code{d}.
  The return code is zero when @code{name} doesn't exist.
@end table

@subsection Atoms
@table @code
@item instruction *new_inst(const char *inst,int len,int op_cnt,char **op,int *op_len)
  Traverses the backend's mnemonic table for instructions called @code{inst}
  and tries to parse @code{op_cnt} operands using the cpu module's
  @code{parse_operand()} function. Returns an instruction pointer when the
  requirements from the mnemonic table were met or @code{NULL}.
@item dblock *new_dblock(void)
  Allocate a new @code{dblock} structure for storing constant data.
@item sblock *new_sblock(expr *space,size_t size,expr *fill)
  Allocate a new @code{sblock} structure for storing @code{space} elements
  of @code{size} target-bytes, filled with @code{fill}, or zeros when
  @code{fill} is @code{NULL}.
@item atom *new_inst_atom(instruction *p)
  Allocate a new @code{INSTRUCTION} atom from @code{p}.
@item atom *new_data_atom(dblock *p,taddr align)
  Allocate a new @code{DATA} atom with alignment @code{align} atom from
  @code{p}.
@item atom *new_label_atom(symbol *p)
  Allocate a new @code{LABEL} atom from symbol @code{p}.
@item atom *new_space_atom(expr *space,size_t size,expr *fill)
  Allocate a new @code{SPACE} atom with @code{space} elements of
  @code{size} target-bytes, filled with @code{fill}, or zeros when
  @code{fill} is @code{NULL}.
@item atom *new_datadef_atom(size_t bitsize,operand *op)
  Allocate a new @code{DATADEF} atom from operand @code{op} with
  @code{bitsize} bits.
@item atom *new_atom(int type,taddr align)
  Allocate a new atom with given type and alignment.
@item void add_atom(section *sec,atom *a)
  Adds a new atom to the end of the specified section. If @code{sec} is
  @code{NULL} then the current section is used. If there is no current
  section yet, then a default section is created.
@end table

@section Syntax modules

A new syntax module must have its own subdirectory under @file{vasm/syntax}.
At least the files @file{syntax.h}, @file{syntax.c} and @file{syntax_errors.h}
must be written.

@subsection The file @file{syntax.h}

@table @code

@item #define ISIDSTART(x)/ISIDCHAR(x)
These macros should return non-zero if and only if the argument is a
valid character to start an identifier or a valid character inside an
identifier, respectively.
@code{ISIDCHAR} must be a superset of @code{ISIDSTART}.

@item #define ISBADID(p,l)
Even with @code{ISIDSTART} and @code{ISIDCHAR} checked, there may be
combinations of characters which do not form a valid initializer (for
example, a single character). This macro returns non-zero, when this is
the case. First argument is a pointer to the new identifier and second
is its length.

@item #define ISEOL(x)
This macro returns true when the string pointing at @code{x} is either
a comment character or end-of-line.

@item #define CHKIDEND(s,e) chkidend((s),(e))
Defines an optional function to be called at the end of the identifier
recognition process. It allows you to adjust the length of the identifier
by returning a modified @code{e}. Default is to return @code{e}. The
function is defined as @code{char *chkidend(char *startpos,char *endpos)}.

@item #define BOOLEAN(x) -(x)
Defines the result of boolean operations. Usually this is @code{(x)}, as
in C, or @code{-(x)} to return -1 for True.

@item #define NARGSYM "NARG"
Defines the name of an optional symbol which contains the number of
arguments in a macro.

@item #define CARGSYM "CARG"
Defines the name of an optional symbol which can be used to select a
specific macro argument with @code{\.}, @code{\+} and @code{\-}.

@item #define REPTNSYM "REPTN"
Defines the name of an optional symbol containing the counter of the
current repeat iteration.

@item #define EXPSKIP(s) exp_skip(s)
Defines an optional replacement for skip() to be used in expr.c, to skip
blanks in an expression. Useful to forbid blanks in an expression and to
ignore the rest of the line (e.g. to treat the rest as comment). The
function is defined as @code{char *exp_skip(char *stream)}.

@item #define IGNORE_FIRST_EXTRA_OP 1
Should be defined as non-zero (true) if the syntax module wants to ignore
the operand field on instructions without an operand. Useful, when everything
following the operand should be regarded as comment, without requiring a
comment character.

@item #define MAXMACPARAMS 35
Optionally defines the maximum number of macro arguments, if you need more than
the default number of 9.

@item #define SKIP_MACRO_ARGNAME(p) skip_identifier(p)
An optional function to skip a named macro argument in the macro
definition.
Argument is the current source stream pointer.
The default is to skip an identifier.

@item #define MACRO_ARG_OPTS(m,n,a,p) NULL
An optional function to parse and skip options, default values and
qualifiers for each macro argument. Returns @code{NULL} when no argument
options have been found.
Arguments are:
  @table @code
    @item struct macro *m;
      Pointer to the macro structure being currently defined.
    @item int n;
      Argument index, starting with zero.
    @item char *a;
      Name of this argument.
    @item char *p;
      Current source stream pointer. An updated pointer will be returned.
  @end table
Defaults to unused.

@item #define MACRO_ARG_SEP(p) (*p==',' ? skip(p+1) : NULL)
An optional function to skip a separator between the macro argument
names in the macro definition. Returns NULL when no valid separator is
found.
Argument is the current source stream pointer.
Defaults to using comma as the only valid separator.

@item #define MACRO_PARAM_SEP(p) (*p==',' ? skip(p+1) : NULL)
An optional function to skip a separator between the macro parameters
in a macro call. Returns NULL when no valid separator is found.
Argument is the current source stream pointer.
Defaults to using comma as the only valid separator.

@item #define EXEC_MACRO(s)
An optional function to be called just before a macro starts execution.
Parameters and qualifiers are already parsed.
Argument is the @code{source} pointer of the new macro.
Defaults to unused.

@item #define CHAR_CONST_TRANSFORM(c,q) (c)
Define this if you want to transform character constant @code{c} in expressions
according to the current state of the module and/or the character constant
prefix @code{q}. Example: Set bit 7 on characters whenever the constant was
prefixed by a @code{"} instead of @code{'}.

@end table

@subsection The file @file{syntax.c}

A syntax module has to provide the following elements (all other functions
should be @code{static} to prevent name clashes):

@table @code

@item const char *syntax_copyright;
A string that will be emitted as part of the copyright message.

@item hashtable *dirhash;
A pointer to the hash table with all directives.

@item char commentchar;
A character used to introduce a comment until the end of the line.

@item int dotdirs;
Define @code{dotdirs} as non-zero, when the syntax module works with
directives starting with a dot (@code{.}).

@item int init_syntax(void);
Will be called during startup, after argument parsing Must return zero if
initializations failed, non-zero otherwise.

@item int syntax_args(char *);
This function will be called with the command line arguments (unless they
were already recognized by other modules). If an argument was recognized,
return non-zero.

@item int syntax_defsect(void);
Lets the syntax module define a default section, which is used when no
section was created by any @code{section} or @code{org} directive, before
the first code or data is defined.
May set @code{defsectname}, @code{defsecttype} and @code{defsectorg}
accordingly and return with non-zero. Or return with zero and accept
the defaults, which are: @code{defsectname=".text"} and
@code{defsecttype="acrx"}.

@item char *skip(char *);
A function to skip whitespace etc.

@item void eol(char *);
This function should check that the argument points to the end of a line
(only comments or whitespace following). If not, an error or warning
message should be omitted.

@item char *const_prefix(char *,int *);
Check if the first argument points to the start of a constant. If yes
return a pointer to the real start of the number (i.e. skip a prefix
that may indicate the base) and write the base of the number through the
pointer passed as second argument. Return zero if it does not point to a
number.

@item char *const_suffix(char *,char *);
First argument points to the start of the constant (including prefix) and
the second argument to first character after the constant (excluding suffix).
Checks for a constant-suffix and skips it. Return pointer to the first
character after that constant. Example: constants with a 'h' suffix to
indicate a hexadecimal base.

@item void parse(void);
This is the main parsing function. It has to read source text lines via
the @code{read_next_line()} function, parse them and create sections,
atoms and symbols. Pseudo directives are usually handled by the syntax 
module. Instructions can be parsed by the cpu module using
@code{parse_instruction()}.

@item char *parse_macro_arg(struct macro *,char *,struct namelen *,struct namelen *);
Called to parse a macro parameter by using the source stream pointer in
the second argument. The start pointer and length of a single passed
parameter is written to the first @code{struct namelen}, while the optionally
selected named macro argument is passed in the second @code{struct namelen}.
When the @code{len} field of the second @code{namelen} is zero, then the
argument is selected by position instead by name. Returns the updated
source stream pointer after successful parsing.

@item int expand_macro(source *,char **,char *,int);
Expand parameters and special commands inside a macro source. The second
argument is a pointer to the current source stream pointer, which is
updated on any successful expansion. The function will return the
number of characters written to the destination buffer (third argument)
in this case. Returning @code{-1} means: no expansion took place.
The last argument defines the space in characters which is left in the
destination buffer.

@item char *get_local_label(char **);
Gets a pointer to the current source pointer. Has to check if a valid
local label is found at this point. If yes return a pointer to the
vasm-internal symbol name representing the local label and update
the current source pointer to point behind the label.

Have a look at the support functions provided by the frontend to help.

@end table

Syntax modules may support additional features, which can be enabled or
disabled by a preprocessor define.
Like allowing the @code{#} character for introducing comments in the
std-syntax module, when the CPU's operand parser doesn't need it
(Example: PPC or x86).
Defines for these optional features follow the general syntax
@code{[module type]_[module name]_[feature name]}.
@example
#define SYNTAX_STD_COMMENTCHAR_HASH
@end example

@section CPU modules

A new cpu module must have its own subdirectory under @file{vasm/cpus}.
At least the files @file{cpu.h}, @file{cpu.c} and @file{cpu_errors.h}
must be written.

@subsection The file @file{cpu.h}

A cpu module has to provide the following elements (all other functions
should be @code{static} to prevent name clashes) in @code{cpu.h}:

@table @code
@item #define LITTLEENDIAN 1
@itemx #define BIGENDIAN 0
Define these according to the target endianness. For CPUs which support big-
and little-endian, you may assign a global variable here. So be aware of
it, and never use @code{#if BIGENDIAN}, but always @code{if(BIGENDIAN)} in
your code.

@item #define VASM_CPU_<cpu> 1
Defines a cpu-specific macro. May be used to perform special handling in
syntax- or output-modules.

@item #define BITSPERBYTE 8
The number of bits per byte of the target cpu. Usually 8. We require
that vasm is running on a host architecture and file system which uses
8-bit bytes. When writing output for a backend with @code{BITSPERBYTE > 8}
the vasm-internal ordering of 8-bit host-bytes within a target-byte
is big-endian.

@item #define MAX_OPERANDS 3
Maximum number of operands of one instruction.

@item #define MAX_QUALIFIERS 0
Maximum number of mnemonic-qualifiers per mnemonic.

@item #define NO_MACRO_QUALIFIERS
Define this, when qualifiers shouldn't be allowed for macros. For some
architectures, like ARM, macro qualifiers make no sense.

@item typedef int32_t taddr;
Data type to represent a target-address. Preferably use the types from
@file{stdint.h}. Does not necessarily have to match the cpu's address
bus size (refer to @code{bytespertaddr}), but choose it according to the
largest data you will be able to do calculations with. For example, you may
want to allow 32-bit data definitions for an 8-bit cpu.

@item typedef uint32_t utaddr;
Unsigned data type to represent a target-address.

@item #define INST_ALIGN 2
Minimum instruction alignment.

@item #define DATA_ALIGN(n) ...
Default alignment for @code{n}-bit data. Can also be a function.

@item #define DATA_OPERAND(n) ...
Operand class for n-bit data definitions. Can also be a function.
Negative values denote a floating point data definition of -n bits.

@item typedef ... operand;
Structure to store an operand for a machine instruction or a
data constant. Stores, for example, addressing modes and expressions.

@item typedef ... mnemonic_extension;
Mnemonic extension for the cpu's instruction table. Often used for the
actual opcode or cpu-model flags.
@end table

Optional features, which can be enabled by defining the following macros:

@table @code
@item #define FLOAT_PARSER 1
Enables the floating point parser and floating point evalulation in the
expression module. With this option the backend has to be prepared that
expressions may contain floating point constants, which can be checked
by testing the result of @code{type_of_expr(expression)} for @code{FLT}.
Then use @code{eval_expr_float(expression,&float_val)} to retrieve the
floating point value with type @code{tfloat}.
It is up to the backend to convert the host's floating point format,
which should be IEEE, into the backend's native format. The vasm frontend
only supports IEEE to IEEE conversion via @code{conv2ieee32()} and
@code{conv2ieee64()}.

@item #define HAVE_INSTRUCTION_EXTENSION 1
If cpu-specific data should be added to all instruction atoms.

@item typedef ... instruction_ext;
Type for the above extension.

@item #define HAVE_CPU_SECT_EXTENSION 1
If cpu-specific data should be added to all sections.

@item typedef ... section_extc;
Type for the above extension.

@item #define HAVE_CPU_CLEANUP_PARSE 1
When defined, vasm calls the function @code{cpu_cleanup_parse(section *)},
with a pointer to the first section, directly after parsing has finished
and all atoms have been created. You can use it to modify the sections
before assembly begins.

@item #define CLEAR_OPERANDS_ON_START 1
Backend requires zeroed operand structures when calling @code{parse_operand()}
for the first time. Might be useful to parse operands only once.
Defaults to undefined.

@item #define CLEAR_OPERANDS_ON_MNEMO 1
Backend requires zeroed operand structures when calling @code{parse_operand()}
for any new mnemonic. Useful to parse the same operand multiple times on
the current mnemonic, but reset everything for the next mnemonic.
Defaults to undefined.

@item START_PARENTH(x)
Valid opening parenthesis for instruction operands. Defaults to @code{'('}.

@item END_PARENTH(x)
Valid closing parenthesis for instruction operands. Defaults to @code{')'}.

@item #define MNEMONIC_VALID(idx)
An optional function with the arguments @code{(int idx)}. Returns true
when the mnemonic with index @code{idx} is valid for the current state of
the backend (e.g. it is available for the selected cpu model).

@item #define MNEMOHTABSIZE 0x4000
You can optionally overwrite the default hash table size defined in
@file{vasm.h}. May be necessary for larger mnemonic tables.
Run vasm with option @option{-debug} to print the number of collisions
in the hash tables.

@item #define OPERAND_OPTIONAL(p,t)
When defined, this is a function with the arguments
@code{(operand *op,int type)}, which returns true when the given operand
type (@code{type}) is optional. The function is only called for missing
operands and should also initialize @code{op} with default values (e.g. 0).
@end table

Implementing additional target-specific unary operations is done by defining
the following optional macros:

@table @code
@item #define EXT_UNARY_NAME(s)
Should return True when the string in @code{s} points to an operation name
we want to handle.

@item #define EXT_UNARY_TYPE(s)
Returns the operation type code for the string in @code{s}. Note that the
last valid standard operation is defined as @code{LAST_EXP_TYPE}, so the
target-specific types will start with @code{LAST_EXP_TYPE+1}.

@item #define EXT_UNARY_EVAL(t,v,r,c)
Defines a function with the arguments @code{(int t, taddr v, taddr *r, int c)}
to handle the operation type @code{t} returning an @code{int} to indicate
whether this type has been handled or not. Your operation will by applied on
the value @code{v} and the result is stored in @code{*r}. The flag @code{c}
is passed as 1 when the value is constant (no relocatable addresses involved).

@item #define EXT_FIND_BASE(b,e,s,p)
Defines a function with the arguments
@code{(symbol **b, expr *e, section *s, taddr p)}
to save a pointer to the base symbol of expression @code{e} into the
symbol pointer, pointed to by @code{b}. The type of this base is given
by an @code{int} return code. Further on, @code{e->type} has to checked
to be one of the operations to handle.
The section pointer @code{s} and the current pc @code{p} are needed to call
the standard @code{find_base()} function.
@end table

@subsection The file @file{cpu.c}

A cpu module has to provide the following elements (all other functions
and data should be @code{static} to prevent name clashes) in @code{cpu.c}:

@table @code
@item int bytespertaddr;
The number of bytes per target address. Note, that this really
defines the size of a backend's address pointer in target-bytes and
might differ from the actual size of @code{taddr} (see above).

@item mnemonic mnemonics[];
The mnemonic table keeps a list of mnemonic names and operand types the
assembler will match against using @code{parse_operand()}. It may also
include a target specific @code{mnemonic_extension}.

@item const char *cpu_copyright;
A string that will be emitted as part of the copyright message.

@item const char *cpuname;
A string describing the target cpu.

@item int init_cpu(void);
Will be called during startup, after argument parsing. Must return zero if
initializations failed, non-zero otherwise.

@item int cpu_args(char *);
This function will be called with the command line arguments (unless they
were already recognized by other modules). If an argument was recognized,
return non-zero.

@item char *parse_cpu_special(char *);
This function will be called with a source line as argument and allows
the cpu module to handle cpu-specific directives etc. Functions like
@code{eol()} and @code{skip()} from the syntax-module should be used to
keep the syntax consistent.

@item operand *new_operand();
Allocate and initialize a new operand structure.

@item int parse_operand(char *text,int len,operand *op,int requires);
Parses the source text for an instruction's operand at @code{text} with length
@code{len} to fill the target specific operand structure pointed to by @code{op},
whenever the operand's type matches the type from @code{requires}.
Return with one of the following codes:
@table @code
@item PO_NOMATCH
The source did no match the operand type given in @code{requires}.
@item PO_CORRUPT
The source was definitely identified as garbage, making it useless to
try matching it against any other operand types.
@item PO_MATCH
The parsed source matches the operand type in @code{requires}. As soon
as all the instruction's operands have been matched, the instruction
is successfully recognized.
@item PO_SKIP
Works like @code{PO_MATCH}, but skips the next operand from the mnemonic
table. For example, because it was already handled together with the
current operand.
@item PO_COMB_OPT
Works like @code{PO_MATCH}, but requests parsing of the next argument from
the source text, if any, with a pointer to the same @code{operand} structure
as before. This makes it possible to merge multiple operands into a
single operand structure.
@item PO_COMB_REQ
Like @code{PO_COMB_OPT}, requests parsing of the next argument
with a pointer to the same @code{operand} structure. But this time the
additional argument is mandatory.
@item PO_NEXT
Source did not match the given operand type in @code{requires}. Request
parsing the same chunk of source text again, but using the following
operand type. Can be used to break a @code{PO_COMB_OPT} or @code{PO_COMB_REQ}
attempt and continue normally.
@end table

@item size_t instruction_size(instruction *ip, section *sec, taddr pc);
Returns the size of the instruction @code{ip} in target-bytes, which, in the
final pass, must be identical to the number of bytes written by
@code{eval_instruction()}
(see below).

@item dblock *eval_instruction(instruction *ip, section *sec, taddr pc);
Converts the instruction @code{ip} into a DATA atom, including relocations
when necessary.

@item dblock *eval_data(operand *op, taddr bitsize, section *sec, taddr pc);
Converts a data operand into a DATA atom, including relocations.

@item void init_instruction_ext(instruction_ext *);
(If @code{HAVE_INSTRUCTION_EXTENSION} is set.)
Initialize an instruction extension.

@item char *parse_instruction(char *,int *,char **,int *,int *);
(If @code{MAX_QUALIFIERS} is greater than 0.)
Parses instruction and saves extension locations.

@item int set_default_qualifiers(char **,int *);
(If @code{MAX_QUALIFIERS} is greater than 0.)
Saves pointers and lengths of default qualifiers for the selected CPU and
returns the number of default qualifiers. Example: for a M680x0 CPU this
would be a single qualifier, called "w". Used by @code{execute_macro()}.

@item cpu_opts_init(section *);
(If @code{HAVE_CPU_OPTS} is set.)
Gives the cpu module the chance to write out @code{OPTS} atoms with
initial settings before the first atom for a section is generated.

@item cpu_opts(void *);
(If @code{HAVE_CPU_OPTS} is set.)
Apply option modifications from an @code{OPTS} atom. For example:
change cpu type or optimization flags.

@item print_cpu_opts(FILE *,void *);
(If @code{HAVE_CPU_OPTS} is set.)
Called from @code{print_atom()} to print an @code{OPTS} atom's contents.

@item cpu_init_section(section *);
(if @code{HAVE_CPU_SECT_EXTENSION} is set.)
Gives you the possibility to initialize cpu-specific elements for any
new sections. Refer to @code{section_extc} typedef.

@end table


@section Output modules

Output modules can be chosen at runtime rather than compile time. Therefore,
several output modules are linked into one vasm executable and their
structure differs somewhat from syntax and cpu modules.

Usually, an output module for some object format @code{fmt} should be contained
in a file @file{output_<fmt>.c} (it may use/include other files if necessary).
To automatically include this format in the build process, the
@code{OUTFMTS} definition in @file{make.rules} has to be extended.
The module should be added to the @code{OBJS} variable
at the start of @file{make.rules}. Also, a dependency line should be added
(see the existing output modules).

An output module must only export a single function which will return
pointers to necessary data/functions. This function should have the
following prototype:
@example
int init_output_<fmt>(
      char **copyright,
      void (**write_object)(FILE *,section *,symbol *),
      int (**output_args)(char *)
    );
@end example

In case of an error, zero must be returned.
Otherwise, It should perform all necessary initializations, return non-zero
and return the following output parameters via the pointers passed as arguments:

@table @code
@item copyright
A pointer to the copyright string.

@item write_object
A pointer to a function emitting the output. It will be called after the
assembler has completed and will receive pointers to the output file,
to the first section of the section list and to the first symbol
in the symbol list. See the section on general data structures for further
details.


@item output_args
A pointer to a function checking arguments. It will be called with all
command line arguments (unless already handled by other modules). If the
output module recognizes an appropriate option, it has to handle it
and return non-zero. If it is not an option relevant to this output module,
zero must be returned.

@end table

At last, a call to the @code{init_output_<fmt>()} has to be added in the
@code{init_output()} function in @file{vasm.c} (should be self-explanatory).
Besides assigning the above mentioned function pointers, this function
can be used to redefine the assembler's behaviour.
For example you may optionally set the following global variables:

@table @code
@item asciiout = 1;
  Set when the output module likes the output file to be opened in
  text-mode instead of binary-mode.
@item unnamed_sections = 1;
  Set when the output module cannot handle section names. Usually such
  an output module differentiates sections by their type only:
  text, data or bss.
@item secname_attr = 1;
  Set when the section attributes are used to differentiate between
  two sections with the same name.
@item output_bitsperbyte = 1;
  Set when the output module supports target-bytes with @code{BITSPERBYTE}.
  Otherwise it is expected that all output modules do work at least
  with 8-bit target-bytes.
@item output_indirect = 1;
  Set when the output module supports indirect symbols. They can be
  recognized as a symbol of type @code{EXPRESSION} with the flag @code{SYMINDIR}.
  The expression's base-symbol provides the referenced indirect symbol.
@end table

Writing a section's contents is typically done by traversing over all
the section's atoms, establish alignment and write the contents of
a @code{DATA} or @code{SPACE} atom using @code{fwdblock()} or
@code{fwsblock()} into the output file.
@example
  section *s;
  atom *p;

  for (p=s->first,pc=(unsigned long long)s->org; p; p=p->next) @{
    npc = fwpcalign(f,p,s,pc);

    if (p->type == DATA)
      fwdblock(f,p->content.db);
    else if (p->type == SPACE)
      fwsblock(f,p->content.sb);

    pc = npc + atom_size(p,s,npc);
  @}
@end example

Useful support functions for output modules, when writing data into the
output file:

@table @code
@item void fw8(FILE *f,uint8_t x)
  Write 8 bits of data.
@item void fw16(FILE *f,uint16_t x,int be)
  Write 16 bits of data with endianness @code{be} (0 is little, 1 is big).
@item void fw24(FILE *f,uint32_t x,int be)
  Write 24 bits of data with endianness @code{be} (0 is little, 1 is big).
@item void fw32(FILE *f,uint32_t x,int be)
  Write 32 bits of data with endianness @code{be} (0 is little, 1 is big).
@item void fwdata(FILE *f,const void *buf,size_t n)
  Write @code{n} 8-bit bytes of data.
@item void fwspace(FILE *f,size_t n)
  Write @code{n} zeroed 8-bit bytes.
@item void fwbytes(FILE *f,void *buf,size_t n)
  Write @code{n} target-bytes (@code{BITSPERBYTE}).
@item void fwdblock(FILE *f,dblock *db)
  Write the target-bytes within a @code{dblock}.
@item void fwsblock(FILE *f,sblock *sb)
  Write the target-bytes within a @code{sblock}.
@item void fwalign(FILE *f,taddr n,taddr align)
  Write as many zero target-bytes as required to align address @code{n}
  to @code{align} bytes.
@item int fwpattern(FILE *f,taddr n,uint8_t *pat,int patlen)
  Write @code{n} target-bytes, which are initialized with pattern @code{pat}.
  The @code{patlen} is given in target-bytes as well. Note, that the
  pattern output may be preceded by a number of zero-bytes when @code{n}
  is not a multiple of @code{patlen}. The function returns non-zero if
  that happened.
@item taddr fwpcalign(FILE *f,atom *a,section *sec,taddr pc)
  Write as many target-bytes as required to achieve proper alignment
  for atom @code{a}. This space will either be filled by a @code{SPACE}
  atom's fill-pattern, or otherwise by the section's default pattern
  (@code{section.pad}).
  The newly aligned @code{pc} is returned.
@end table

Some remarks:
@itemize @minus

@item
Note, that the output of atoms and target-bytes, using the functions from
above, is done by writing 8-bit bytes to the host's file system. The
order of 8-bit bytes within target-bytes which are greater than 8 bits
can be selected by the options @option{-obe} for big-endian and @option{-ole}
for little-endian. The target-bytes are automatically written in that
selected order, when using the @code{fw*} functions from above. Otherwise
you can check the global variable @code{output_bytes_le}, which will be
zero for big-endian and non-zero for little-endian target-byte output.
The default is vasm's internal target-byte endianness, which is big-endian.

@item
Some output modules cannot handle all supported CPUs. Nevertheless,
they have to be written in a way that they can be compiled. If code
references CPU-specifics, they have to be enclosed in
@code{#ifdef VASM_CPU_MYCPU} ... @code{#endif} or similar.

Also, if the selected CPU is not supported, the init function should fail.

@item
Error/warning messages can be emitted with the @code{output_error} function.
As all output modules are linked together, they have a common list of error
messages in the file @file{output_errors.h}. If a new message is needed, this
file has to be extended (see the section on general data structures for
details).
When the cause for an error relates to an @code{atom} you may also use
the @code{output_atom_error} function instead, which additionally prints
the atom's source text line.
In @file{output_errors.h} use the @code{NOLINE} flag when no atom is
available.

@item
@command{vasm} has a mechanism to specify rather complex relocations in a
standard way (see the section on general data structures). They can be
extended with CPU-specific relocations, but usually CPU modules will
try to create standard relocations (sometimes several standard relocations
can be used to implement a CPU-specific relocation). An output
module should try to find appropriate relocations supported by the
object format. The goal is to avoid special CPU-specific
relocations as much as possible.

@end itemize

Volker Barthelmann                                      vb@@compilers.de

@bye
