6502/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 -chklabels
        Issues a warning when a label matches a mnemonic or directive name
        in either upper or lower case.

@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 -depend=<type>
        Print all dependencies while assembling the source with the given
        options. No output is generated. <type> may be @option{list} for
        printing one file name in each new line, or @option{make} for printing
        a sequence of file names on a single line, suitable for Makefiles.
        When the output file name is given by @option{-o} then
        @command{vasm} will also print @code{outname:} in front of it.
        Note that unlike with @option{-dependall} only relative include
        file dependencies will be listed (which is the common case).

@item -dependall=<type>
        Prints dependencies in the same way as @option{-depend}, but
        will also print all include files with absolute paths.

@item -depfile <filename>
        Used together with @option{-depend} or @option{-dependall} and
        instructs vasm to output all dependencies to a new file, instead
        of stdout. Code will be generated in parallel to the dependencies
        output.

@item -dwarf[=<version>]
        Automatically generate DWARF debugging sections, suitable for
        source level debugging. When the version specification is missing
        DWARF V3 will be generated. The only difference to V2 is that it
        creates a @code{.debug_ranges} section, with address ranges for all
        sections, instead of a bad workaround by specifying
        @code{DW_AT_low_pc=0} and @code{DW_AT_high_pc=~0}.
        Note that when you build vasm from source, you may have to specify
        your host operating system with @code{-Dname} in the Makefile to
        include the appropriate code which can determine the current
        work directory. Otherwise, the default would be to set the current
        work directory to an empty string. Currently supported are:
        @code{UNIX}, @code{AMIGA}, @code{ATARI}, @code{MSDOS},
        @code{_WIN32}.

@item -esc
        Enable escape character sequences. This will make vasm treat the
        escape character \ in string constants similar as in the C language.

@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 -maxmacrecurs=<n>
        Defines the maximum of number of recursions within a macro.
        Defaults to 1000.

@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 -noialign
        Perform no automatic alignment for instructions. Note that
        unaligned instructions make your code crash when executed!
        Only set when you know what you do!

@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 -unsshift
        The shift-right operator (@code{>>}) treats the value to shift as
        unsigned, which has the effect that 0-bits are inserted on the
        left side. The number of bits in a value depend on the target
        address type (refer to the appropriate cpu module documentation).

@item -w
        Hide all warning messages.

@item -wfail
        The return code of vasm will no longer be 0 (success), when there
        was a warning. Errors always make the return code fail.

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

@end table

Note that while most options allow an argument without any separating blank,
some others require it (e.g. @option{-o} and @option{-L}).

@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{&} (bitwise and)
@item @code{^ ~} (bitwise exclusive-or)
@item @code{| !} (bitwise inclusive-or)
@item @code{* / % //} (multiply, divide, modulo)
@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.

When the @option{-esc} option was specified, or automatically enabled by
a syntax module, vasm interprets escape character sequences as in the
C language:

@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

Note, that the default behaviour of vasm has changed since V1.7! Escape
sequence handling has been the default in older versions. This has been
changed to increase compatibility with other assemblers. Use @option{-esc}
to assemble sources with escape character sequences. It is still the
default in the @code{std} syntax module, though.

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

On startup vasm will define at least one default include path: the
current working directory, where the assembler program was launched from.
When the input file is loaded from a different directory, i.e. the input
file is a relative or absolute path and not a single file name, then the
path to the input file name will be added as another include path.

Include paths are searched in the following order:
@enumerate 1
@item Current work directory.
@item Paths specified by @option{-I} in the order of occurence on the
      command line.
@item Path to the input source file.
@item Paths specified by directives inside the source text (in the order
      of occurence).
@end enumerate

@section Macros

Macros are supported by vasm, but the directives for defining them have
to be implemented in the syntax module. The assembler core supports 9
macro arguments by default to be passed in the operand field,
which can be extended to any number by the syntax module.
They can be referenced inside the macro either by name (@code{\name}) or by
number (@code{\1} to @code{\9}), or both, depending on the syntax module.
Recursions and early exits are supported.

Refer to the selected syntax module for more details.

@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 Jordan Zebor
    @item Joseph Zatarski
    @item Frank Wille
    @item Henryk Richter
    @item Sebastian Pachuta
    @item Esben Norby
    @item Gunther Nikl
    @item George Nakos
    @item Timm S. Mueller
    @item Gareth Morris
    @item Dominic Morris
    @item Jean-Paul Mari
    @item Mauricio Mu@~noz Lucero
    @item J@"org van de Loo
    @item Robert Leffmann
    @item Andreas Larsson
    @item Miro Kropacek
    @item Mikael Kalms
    @item Matthew Hey
    @item Philippe Guichardon
    @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: target data type overflow (%d bits)
@item 23: undefined symbol <%s>
@item 24: trailing garbage after option -%c
@item 25: missing pacro parameters
@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 %s 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: label name conflicts with mnemonic
@item 41: label name conflicts with directive
@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: address space overflow
@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
@item 54: non-relocatable expression in equate <%s>
@item 55: initialized data in offset section
@item 56: illegal structure recursion
@item 57: maximum number of macro recursions (%d) reached
@item 58: data has been auto-aligned
@item 59: register symbol <%s> redefined
@item 60: cannot evaluate constant huge integer expression
@item 61: cannot evaluate floating point expression
@item 62: imported symbol <%s> was not referenced
@item 63: symbol <%s> already defined with %s scope
@item 64: unexpected "else" without "if"
@item 65: unexpected "endif" without "if"
@item 66: maximum if-nesting depth exceeded (%d levels)
@item 67: "endif" missing for conditional block started at %s line %d
@item 68: repeatedly defined symbol <%s>
@item 69: macro <%s> does not exist
@item 70: register <%s> does not exist
@item 71: register symbol <%s> has wrong type
@item 72: cannot mix positional and keyword arguments
@item 73: undefined macro argument name
@item 74: required macro argument %d was left out
@item 75: label <%s> redefined

@end itemize