mist-devel.mist-board/tools/vasm/doc/vasm_main.texi

This chapter describes the module-independent part of the assembler. It
documents the options and extensions which are not specific to a certain
target, syntax or output driver. Be sure to also read the chapters on the
backend, syntax- and output-module you are using. They will
likely contain important additional information like data-representation
or additional options.

@node General Assembler Options
@section General Assembler Options

    @command{vasm} is run using the following syntax:

@example
      @command{vasm<target>_<syntax> [options] file}
@end example

    The following options are supported by the machine independent part
    of @command{vasm}:

@table @option

@item -D<name>[=expression]
        Defines a symbol with the name <name> and assigns the value of the
        expression when given. The assigned value defaults to 1 otherwise.

@item -F<fmt>
        Use module <fmt> as output driver. See the chapter on output
        drivers for available formats and options.

@item -I<path>
        Define another include path. They are searched in the order of
        occurence on the command line.

@item -ignore-mult-inc
        When the same file is included multiple times with the same path
        this is silently ignored, causing the file to be processed only
        once. Note that you can still include the same file twice when
        using different paths to access it.

@item -L <listfile>
        Enables generation of a listing file and directs the output into
        the file <listfile>.

@item -Ll<lines>
        Set the number of lines per listing file page to <lines>.

@item -Lnf
        Do not emit any form feed code into the listing file, for starting
        a new page.

@item -Lns
        Do not include symbols in the listing file.

@item -maxerrors=<n>
        Defines the maximum number of errors to display before assembly
        is aborted. When <n> is 0 then there is no limit. Defaults to 5.

@item -nocase
        Disables case-sensitivity for everything - identifiers, directives
        and instructions. Note that directives and instructions may already
        be case-insensitive by default in some modules.

@item -noesc
        No escape character sequences. This will make vasm treat the
        escape character \ as any other character. Might be useful for
        compatibility.

@item -nosym
        Strips all local symbols from the output file and doesn't include
        any other symbols than those which are required for external
        linkage.

@item -nowarn=<n>
        Disable warning message <n>. <n> has to be the number of a valid
        warning message, otherwise an error is generated.

@item -o <ofile>
        Write the generated assembler output to <ofile> rather than
        @file{a.out}.

@item -pic
        Try to generate position independant code. Every relocation is
        flagged by an error message.

@item -quiet      
        Do not print the copyright notice and the final statistics.

@item -unnamed-sections
        Sections are no longer distinguished by their name, but only by
        their attributes. This has the effect that when defining a second
        section with a different name but same attributes as a first one,
        it will switch to the first, instead of starting a new section.

@item -w
        Hide all warning messages.

@item -x
        Show an error message, when referencing an undefined symbol.
        The default behaviour is to declare this symbol as externally
        defined.

@end table

@section Expressions

Standard expressions are usually evaluated by the main part of vasm
rather than by one of the modules (unless this is necessary).

All expressions evaluated by the frontend are calculated in terms
of target address values, i.e. the range depends on the backend.

The available operators include all those which are common in assembler as
well as in C expressions.

C like operators:
@itemize
@item Unary: @code{+ - ! ~}
@item Arithmetic: @code{+ - * / % << >>}
@item Bitwise: @code{& | ^}
@item Logical: @code{&& ||}
@item Comparative: @code{< > <= >= == !=}
@end itemize

Assembler like operators:
@itemize
@item Unary: @code{+ - ~}
@item Arithmetic: @code{+ - * / // << >>}
@item Bitwise: @code{& ! ~}
@item Comparative: @code{< > <= >= = <>}
@end itemize

Up to version 1.4b the operators had the same precedence and associativity as
in the C language. Newer versions have changed the operator priorities to
comply with the common assembler behaviour. The expression evaluation
priorities, from highest to lowest, are:

@enumerate 1
@item @code{+ - ! ~} (unary +/- sign, not, complement)
@item @code{<< >>} (shift left, shift right)
@item @code{* / % //} (multiply, divide, modulo)
@item @code{&} (bitwise and)
@item @code{^ ~} (bitwise exclusive-or)
@item @code{| !} (bitwise inclusive-or)
@item @code{+ -} (plus, minus)
@item @code{< > <= >=} (less, greater, less or equal, greater or equal)
@item @code{== != = <>} (equality, inequality)
@item @code{&&} (logical and)
@item @code{||} (logical or)
@end enumerate

Operands are integral values of the target address type. They can either be
specified as integer constants of different bases (see the documentation
on the syntax module to see how the base is specified) or character
constants. Character constants are introduced by @code{'} or @code{"}
and have to be terminated by the same character that started them.

Multiple characters are allowed and a constant is built according to the
endianess of the target.

Inside character contants, the following escape sequences are allowed
(unless @option{-noesc} was specified):

@table @code

@item \\
        Produces a single @code{\}.

@item \b
        The bell character.

@item \f
        Form feed.

@item \n
        Line feed.

@item \r
        Carriage return.

@item \t
        Tabulator.

@item \"
        Produces a single @code{"}.
    
@item \'
        Produces a single @code{'}.

@item \e
        Escape character (27).

@item \<octal-digits>
        One character with the code specified by the digits
        as octal value.

@item \x<hexadecimal-digits>
        One character with the code specified by the digits
        as hexadecimal value.

@item \X<hexadecimal-digits>
        Same as @code{\x}.

@end table

@section Symbols

You can define as many symbols as your available memory permits. A symbol
may have any length and can be of global or local scope. Internally, there
are three types of symbols:
@table @code
@item Expression
      These symbols are usually not visible outside the
      source, unless they are explicitely exported.
@item Label
      Labels are always addresses inside a program section. By
      default they have local scope for the linker.
@item Imported
      These symbols are externally defined and must be
      resolved by the linker.
@end table

Beginning with vasm V1.5c one expression symbol is always defined to allow
conditional assembly depending on the assembler being used: @code{__VASM}.
Its value depends on the selected cpu module. There may be other symbols which
are pre-defined by the syntax- or by the cpu module.

@section Include Files

Vasm supports include files and defining include paths. Whether this
functionality is available depends on the syntax module, which has to
provide the appropriate directives.

@section Macros

Macros are supported by vasm, but the directives for defining them have
to be implemented in the syntax module. In any case the assembler core
allows up to 9 macro parameters by default (extendable to up to 36 parameters)
to be passed in the operand field.
They can be referenced inside the macro by @code{\1} to @code{\9}.
Additionally there is a special argument @code{\0} which is set to the
first qualifier (mnemonic extension) of the macro invocation when given.

A macro parameter which is enclosed inside @code{<} and @code{>} characters
is treated as a single parameter, even when it contains commas. @code{>}
characters within such a parameter may be specified by @code{>>}.

@code{\@@} inserts a unique id of the form @code{_nnnnnn} (where
'@code{n}' is a digit between 0 and 9) per macro invocation. Useful
for defining reusable labels in a macro.

@code{\@@!} does the same, but pushes the id onto an internal stack.

@code{\@@@@} insert the id from top of the id-stack.

@code{\#} is replaced by the number of parameters given to the current
macro invocation.

@code{\?n} represents the total length of parameter n in bytes. Note that the
quotes in a string parameter are included.

@section Structures

Vasm supports structures, but the directives for defining them
have to be implemented in the syntax module.

@section Conditional Assembly

Has to be provided completely by the syntax module.

@section Known Problems

    Some known module-independent problems of @command{vasm} at the moment:

@itemize @minus

@item None.

@end itemize

@section Credits

    All those who wrote parts of the @command{vasm} distribution, made suggestions,
    answered my questions, tested @command{vasm}, reported errors or were otherwise
    involved in the development of @command{vasm} (in descending alphabetical order,
    under work, not complete):

@itemize
    @item Frank Wille
    @item Sebastian Pachuta
    @item Gunther Nikl
    @item George Nakos
    @item Timm S. Mueller
    @item Gareth Morris
    @item Dominic Morris
    @item Mauricio Mu@~noz Lucero
    @item J@"org van de Loo
    @item Robert Leffmann
    @item Miro Kropacek
    @item Mikael Kalms
    @item Matthew Hey
    @item Romain Giot
    @item Francois Galea
    @item Tom Duin
    @item Karoly Balogh
@end itemize

@section Error Messages

The frontend has the following error messages:

@itemize @minus
@item 1: illegal operand types
@item 2: unknown mnemonic <%s>
@item 3: unknown section <%s>
@item 4: no current section specified
@item 5: internal error %d in line %d of %s
@item 6: symbol <%s> redefined
@item 7: %c expected
@item 8: cannot resolve section <%s>, maximum number of passes reached
@item 9: instruction not supported on selected architecture
@item 10: number or identifier expected
@item 11: could not initialize %s module
@item 12: multiple input files
@item 13: could not open <%s> for input
@item 14: could not open <%s> for output
@item 15: unknown option <%s>
@item 16: no input file specified
@item 17: could not initialize output module <%s>
@item 18: out of memory
@item 19: symbol <%s> recursively defined
@item 20: fail: %s
@item 21: section offset is lower than current pc
@item 22: character constant too long
@item 23: undefined local symbol
@item 24: trailing garbage after option -%c
@item 25: bad operand
@item 26: missing end directive for macro "%s"
@item 27: macro definition inside macro "%s"
@item 28: maximum number of %d macro arguments exceeded
@item 29: option -%c was specified twice
@item 30: read error on <%s>
@item 31: expression must be constant
@item 32: initialized data in bss
@item 33: missing end directive in repeat-block
@item 34: #%d is not a valid warning message
@item 35: relocation not allowed
@item 36: illegal escape sequence \%c
@item 37: no current macro to exit
@item 38: internal symbol %s redefined by user
@item 39: illegal relocation
@item 40: macro id stack overflow
@item 41: macro id pull without matching push
@item 42: division by zero
@item 43: illegal macro argument
@item 44: reloc org is already set
@item 45: reloc org was not set
@item 46: macro id insert on empty stack
@item 47: bad file-offset argument
@item 48: assertion "%s" failed: %s
@item 49: cannot declare structure within structure
@item 50: no structure
@item 51: instruction has been auto-aligned
@item 52: macro name conflicts with mnemonic
@item 53: macro name conflicts with directive

@end itemize