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 cpu-backend, syntax- and output-module you are using. They will likely contain important additional information like data-representation or additional options.

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

vasm is run from the command line using the following syntax:

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

When the source file name is missing the assembler reads the source text from stdin until encountering EOF (end-of-file, which is CTRL-D in Unix shells, or CTRL-\ in AmigaOS shells). Note, that most debugging formats (DWARF, etc.) no longer function with such temporary source texts.

The following options are supported by the machine independent part of vasm. The most important ones are:

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

-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 occurrence on the command line, and always before any include paths defined in the source.

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

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

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

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

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

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

Other options:

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

-depend=<type>
     Print all dependencies while assembling the source with the given options. No output is generated. <type> may be the word 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 outname then vasm will also print outname: in front of it. Note that in contrast to option -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 also prints all include files with absolute paths.

-depfile <filename>
     Used together with -depend or -dependall and instructs vasm to output all dependencies into a new file, instead of stdout. Additionally, code will be generated in parallel to the dependencies output.

-dwarf[=<version>]
     Automatically generate DWARF debugging sections, suitable for source level debugging. When the version specification is missing, DWARF V3 will be emitted. The only difference to V2 is that it creates a .debug_ranges section, with address ranges for all sections, instead of using a workaround by specifying DW_AT_low_pc=0 and DW_AT_high_pc=~0. Note, that when you build vasm from source, you may have to set your host operating system with -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: AMIGA, ATARI, MSDOS,  UNIX, _WIN32. MacOSX works with UNIX.

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

-ibe
     Use big-endian order when reading target-bytes with more than 8 bits per byte from the host's file system (default).

-ignore-mult-inc
     When the same file is included multiple times, using 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.

-ile
     Use little-endian order when reading target-bytes with more than 8 bits per byte from the host's file system.

-Lall
     List all symbols, including unused equates. Default is to list all labels and all used expressions only.

-Lbpl=<n>
     Set the maximum number of bytes per line in a listing file to <n>. Defaults to 8 (fmt=wide).

-Lfmt=<fmt>
     Set the listing file format to <fmt>. Defaults to wide. Available are: wide, old.

-Llo
     Show only program labels in the sorted symbol listing. Default is to list all symbols, including absolute expressions.

-Lni
     Do not show included source files in the listing file (fmt=wide).

-Lns
     Do not include symbols in the listing file (fmt=wide).

-maxerrors=<n>
     Sets 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 number of recursion levels within a macro. Defaults to 1000.

-maxpasses=<n>
     Adjusts the maximum number of passes while resolving a section. Defaults to 1500.

-no-msrcdebug
     Disable source level debugging within a macro context. When generating output with source level debug information, the debugger will show the invoking source text line instead.

-nocompdir
     Do not search for include files relative to the compile directory (where the main input source is located).

-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 can make your code crash when executed! Only set when you know what you are doing!

-nomsg=<n>
     Disable the informational message <n>. <n> has to be the number of a valid informational message, like an optimization message.

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

-obe
     Write target-bytes with more than 8 bits per byte in big-endian order to the host's file system (default).

-ole
     Write target-bytes with more than 8 bits per byte in little-endian order to the host's file system.

-pad=<value>
     The given padding value can be one or multiple bytes (up to the cpu-backend's address size). It is used for alignment purposes and to fill gaps between absolute ORG sections in the binary output module. Defaults to a zero-byte.

-pic
     Try to generate position independent code. Every relocation position is flagged by an error message. This option overrides the absolute default mode (ORG 0) of binary output modules and doesn't work if you force the assembler into absolute mode by such a directive.

     Note, that this means you cannot do any PIC-checks in absolute mode, because no relocations are generated there.

-relpath
     Do not interpret a source path starting with '/' or '\', or including a colon, as absolute, but always attach it relative to defined include paths first.

-underscore
     Add a leading underscore in front of all imported and exported (also common, weak) symbol names, just before writing the output file.

-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. Is enabled automatically, when using an output-module which doesn't support section names. For example: aout, tos, xfile.

-unsshift
     The shift-right operator (>>) treats the value to shift as unsigned, which has the effect that only 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). This may already be the default for some syntax modules, like for example mot-syntax in Devpac-compatibility mode.

-uspc=<value>
     Uninitialized memory regions, declared by "space" directives (.space in std-syntax, ds in mot-syntax, etc.) are filled with the given value. Defaults to zero.

-w
     Hide all warning messages.

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

-v
     Print version and copyright messages from the assembler and all its modules, then exit.

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

Expressions
===========

Standard expressions are usually evaluated by vasm's core routines 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. Constants which exceed the target address range may be supported by some backends up to 128 bits.

Backends also have the option to support floating point constants directly and convert them to a backend-specific format which is described in the backend's documentation.

Warning: Be aware that the quality and precision of the backend's floating point output depends on the combination of host- and backend-format! If you need absolute precision, encode the floating point constants yourself in binary.

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 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. ^ ~ (two forms of bitwise exclusive-or)

 5. | ! (two forms bitwise inclusive-or)

 6. * / % // (multiply, divide, modulo, modulo)

 7. + - (plus, minus)

 8. < > <= >= (less, greater, less or equal, greater or equal)

 9. == = != <> (two forms of equality and 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 endianness 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 was changed to improve compatibility with other assemblers. Use -esc to assemble sources with escape character sequences. It is still the default in the std syntax module, though.

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 explicitly exported.

Label
     Labels are always addresses within 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.

Predefined Symbols
==================

Beginning with vasm V1.5c at least 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.

Since V1.8i there may be a second internal symbol which reflects the format of the paths in the host file system. Currently there may be one of:

__UNIXFS
     Host file system uses Unix-style paths.

__MSDOSFS
     Host file system uses MS-DOS-, Windows-, Atari-style paths.

__AMIGAFS
     Host file system uses AmigaDOS-style paths.

Note that such a path-style symbol must be configured by a -D option while compiling vasm from source. Refer to the section about building vasm (Interface chapter) for a listing of all supported host OS options.

There may be other internal symbols, which are defined by the syntax- or by the cpu module.

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 defines one or two default include paths: the current work directory and, when the main source is not located there, the compile directory.

Include paths are searched in the following order:

 1. Current work directory.

 2. Compile directory (path to main source).

 3. Paths specified by -I in the order of occurrence on the command line.

 4. Paths specified by directives in the source text (in the order of occurrence).

Additionally, all the relative paths, defined by -I or directives, are first appended to the current work directory name, then to the compile directory name, while searching for an include file.

Searching for include files in paths based on the compile directory can be completely disabled by -nocompdir.

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

Structures
==========

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

Conditional Assembly
====================

Has to be provided completely by the syntax module.

Known Problems
==============

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

  - None.

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):

  * Jordan Zebor

  * Joseph Zatarski

  * Frank Wille

  * Jim Westfall

  * Bernard Thibault

  * Dimitri Theulings

  * Yannick Stamm

  * Jens Schönfeld

  * Ross

  * Henryk Richter

  * Sebastian Pachuta

  * Thorsten Otto

  * Esben Norby

  * Tom Noorduin

  * Gunther Nikl

  * George Nakos

  * Timm S. Mueller

  * Gareth Morris

  * Dominic Morris

  * Garry Marshall

  * Jean-Paul Mari

  * Mauricio Muñoz Lucero

  * Grzegorz Mazur

  * Jörg van de Loo

  * Robert Leffmann

  * Andreas Larsson

  * Miro Kropáček

  * Olav Krömeke

  * Christoph Krc

  * Chester Kollschen

  * Richard Körber

  * Mikael Kalms

  * Mark Jones

  * Bert Jahn

  * Daniel Illgen

  * Jerome Hubert

  * Matthew Hey

  * Stefan Haubenthal

  * Søren Hannibal

  * John Hankinson

  * Philippe Guichardon

  * Luis Panadero Guardeño

  * Romain Giot

  * Daniel Gerdgren

  * François Galea

  * Tom Duin

  * Adrien Destugues

  * Kieran Connell

  * Jae Choon Cha

  * Fernando Cabrera

  * Patrick Bricout

  * Matthias Bock

  * Simone Bevilacqua

  * Karoly Balogh

  * Anomie-p

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: %s module doesn't support %d-bit bytes

  - 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 %s 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

  - 76: base %d numerical term expected

  - 77: section stack overflow

  - 78: section stack is empty

  - 79: illegal value for option: %s

  - 80: %s backend does not support floating point

  - 81: unknown listing file format "%s" ignored

  - 82: cannot export equate based on imported symbol: <%s>

  - 83: label definition not allowed here

  - 84: label defined on the same line as a new section

  - 85: no debug output possible with source from stdin

  - 86: external symbol <%s> must not be defined

  - 87: missing definition for symbol <%s>

  - 88: additional macro arguments ignored (expecting %d)

  - 89: macro previously defined at line %d of %s