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.

1 General Assembler Options
===========================

‘vasm’ is run using the following syntax:

           vasm<target>_<syntax> [options] file

   The following options are supported by the machine independent part
of ‘vasm’:

‘-chklabels’
     Issues a warning when a label matches a mnemonic or directive name
     in either upper or lower case.

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

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

‘-dependall=<type>’
     Prints dependencies in the same way as ‘-depend’, but will also
     print all include files with absolute paths.

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

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

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

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

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

‘-Ll<lines>’
     Set the number of lines per listing file page to <lines>.

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

‘-Lns’
     Do not include symbols in the listing file.

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

‘-maxmacrecurs=<n>’
     Defines the maximum of number of recursions within a macro.
     Defaults to 1000.

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

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

‘-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!

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

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

‘-o <ofile>’
     Write the generated assembler output to <ofile> rather than
     ‘a.out’.

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

‘-quiet’
     Do not print the copyright notice and the final statistics.

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

‘-unsshift’
     The shift-right operator (‘>>’) 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).

‘-w’
     Hide all warning messages.

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

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

2 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:
   • Unary: ‘+ - ! ~’
   • Arithmetic: ‘+ - * / % << >>’
   • Bitwise: ‘& | ^’
   • Logical: ‘&& ||’
   • Comparative: ‘< > <= >= == !=’

   Assembler like operators:
   • Unary: ‘+ - ~’
   • Arithmetic: ‘+ - * / // << >>’
   • Bitwise: ‘& ! ~’
   • Comparative: ‘< > <= >= = <>’

   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:

  1. ‘+ - ! ~’ (unary +/- sign, not, complement)
  2. ‘<< >>’ (shift left, shift right)
  3. ‘&’ (bitwise and)
  4. ‘^ ~’ (bitwise exclusive-or)
  5. ‘| !’ (bitwise inclusive-or)
  6. ‘* / % //’ (multiply, divide, modulo)
  7. ‘+ -’ (plus, minus)
  8. ‘< > <= >=’ (less, greater, less or equal, greater or equal)
  9. ‘== != = <>’ (equality, inequality)
  10. ‘&&’ (logical and)
  11. ‘||’ (logical or)

   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 ‘'’ or ‘"’
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 ‘-esc’ option was specified, or automatically enabled by a
syntax module, vasm interprets escape character sequences as in the C
language:

‘\\’
     Produces a single ‘\’.

‘\b’
     The bell character.

‘\f’
     Form feed.

‘\n’
     Line feed.

‘\r’
     Carriage return.

‘\t’
     Tabulator.

‘\"’
     Produces a single ‘"’.

‘\'’
     Produces a single ‘'’.

‘\e’
     Escape character (27).

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

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

‘\X<hexadecimal-digits>’
     Same as ‘\x’.

   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
‘-esc’ to assemble sources with escape character sequences.  It is still
the default in the ‘std’ syntax module, though.

3 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:
‘Expression’
     These symbols are usually not visible outside the source, unless
     they are explicitely exported.
‘Label’
     Labels are always addresses inside a program section.  By default
     they have local scope for the linker.
‘Imported’
     These symbols are externally defined and must be resolved by the
     linker.

   Beginning with vasm V1.5c one expression symbol is always defined to
allow conditional assembly depending on the assembler being used:
‘__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.

4 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:
  1. Current work directory.
  2. Paths specified by ‘-I’ in the order of occurence on the command
     line.
  3. Path to the input source file.
  4. Paths specified by directives inside the source text (in the order
     of occurence).

5 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 (‘\name’) or by number (‘\1’ to ‘\9’),
or both, depending on the syntax module.  Recursions and early exits are
supported.

   Refer to the selected syntax module for more details.

6 Structures
============

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

7 Conditional Assembly
======================

Has to be provided completely by the syntax module.

8 Known Problems
================

Some known module-independent problems of ‘vasm’ at the moment:

   − None.

9 Credits
=========

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

   • Joseph Zatarski
   • Frank Wille
   • Henryk Richter
   • Sebastian Pachuta
   • Esben Norby
   • Gunther Nikl
   • George Nakos
   • Timm S. Mueller
   • Gareth Morris
   • Dominic Morris
   • Mauricio Muñoz Lucero
   • Jörg van de Loo
   • Robert Leffmann
   • Andreas Larsson
   • Miro Kropacek
   • Mikael Kalms
   • Matthew Hey
   • Philippe Guichardon
   • Romain Giot
   • Francois Galea
   • Tom Duin
   • Karoly Balogh

10 Error Messages
=================

The frontend has the following error messages:

   − 1: illegal operand types
   − 2: unknown mnemonic <%s>
   − 3: unknown section <%s>
   − 4: no current section specified
   − 5: internal error %d in line %d of %s
   − 6: symbol <%s> redefined
   − 7: %c expected
   − 8: cannot resolve section <%s>, maximum number of passes reached
   − 9: instruction not supported on selected architecture
   − 10: number or identifier expected
   − 11: could not initialize %s module
   − 12: multiple input files
   − 13: could not open <%s> for input
   − 14: could not open <%s> for output
   − 15: unknown option <%s>
   − 16: no input file specified
   − 17: could not initialize output module <%s>
   − 18: out of memory
   − 19: symbol <%s> recursively defined
   − 20: fail: %s
   − 21: section offset is lower than current pc
   − 22: target data type overflow (%d bits)
   − 23: undefined symbol <%s>
   − 24: trailing garbage after option -%c
   − 25: missing pacro parameters
   − 26: missing end directive for macro "%s"
   − 27: macro definition inside macro "%s"
   − 28: maximum number of %d macro arguments exceeded
   − 29: option -%c was specified twice
   − 30: read error on <%s>
   − 31: expression must be constant
   − 32: initialized data in bss
   − 33: missing end directive in repeat-block
   − 34: #%d is not a valid warning message
   − 35: relocation not allowed
   − 36: illegal escape sequence \%c
   − 37: no current macro to exit
   − 38: internal symbol %s redefined by user
   − 39: illegal relocation
   − 40: label name conflicts with mnemonic
   − 41: label name conflicts with directive
   − 42: division by zero
   − 43: illegal macro argument
   − 44: reloc org is already set
   − 45: reloc org was not set
   − 46: address space overflow
   − 47: bad file-offset argument
   − 48: assertion "%s" failed: %s
   − 49: cannot declare structure within structure
   − 50: no structure
   − 51: instruction has been auto-aligned
   − 52: macro name conflicts with mnemonic
   − 53: macro name conflicts with directive
   − 54: non-relocatable expression in equate <%s>
   − 55: initialized data in offset section
   − 56: illegal structure recursion
   − 57: maximum number of macro recursions (%d) reached
   − 58: data has been auto-aligned
   − 59: register symbol <%s> redefined
   − 60: cannot evaluate constant huge integer expression
   − 61: cannot evaluate floating point expression
   − 62: imported symbol <%s> was not referenced
   − 63: symbol <%s> already defined with %s scope
   − 64: unexpected "else" without "if"
   − 65: unexpected "endif" without "if"
   − 66: maximum if-nesting depth exceeded (%d levels)
   − 67: "endif" missing for conditional block started at %s line %d
   − 68: repeatedly defined symbol <%s>
   − 69: macro <%s> does not exist
   − 70: register <%s> does not exist
   − 71: register symbol <%s> has wrong type
   − 72: cannot mix positional and keyword arguments
   − 73: undefined macro argument name
   − 74: required macro argument %d was left out
   − 75: label <%s> redefined

