This is the manual for the vasm assembler system.

Copyright 2002-2025 Volker Barthelmann

General
*******

Introduction
============

vasm is a portable and retargetable assembler able to create linkable objects in different formats as well as absolute code. Different CPU-, syntax and output-modules are supported.

Most common directives/pseudo-opcodes are supported (depending on the syntax module) as well as CPU-specific extensions.

The assembler supports optimizations and relaxations. For example, choosing the shortest possible branch instruction or addressing mode as well as converting a branch to an absolute jump if necessary.

It also supports target CPUs with more than 8 bits per byte (word-addressing) but requires that the host system has 8-bit bytes.

The concept is that you get a special vasm binary for any combination of CPU- and syntax-module. All output modules, which make sense for the selected CPU, are included in the vasm binary and you have to make sure to choose the output file format you need (refer to the next chapter and look for the -F option). The default is a test output format, only useful for debugging or analyzing the output.

Legal
=====

vasm is copyright in 2002-2025 by Volker Barthelmann.

This archive may be redistributed without modifications and used for non-commercial purposes.

An exception for commercial usage is granted, provided that the target CPU is M68k and the target OS is AmigaOS. Resulting binaries may be distributed commercially without further licensing.

In all other cases you need my written consent.

Certain modules may fall under additional copyrights.

Contact
=======

Responsible for the current version of vasm and contact address in case of bug reports or support requests:

  - Volker Barthelmann (vb@compilers.de)

  - Frank Wille (frank@phoenix.owl.de)

In case you have an issue with a specific cpu-, syntax- or output-module, please contact the module's author first, if possible.

Installation
============

The vasm binaries do not need additional files, so no further installation is necessary. To use vasm with vbcc, copy the binary to vbcc/bin after following the installation instructions for vbcc.

The vasm binaries are named vasm<cpu>_<syntax> with <cpu> representing the CPU-module and <syntax> the syntax-module, e.g. vasm for PPC with the standard syntax module is called vasmppc_std.

Sometimes the syntax-modifier may be omitted, e.g. vasmppc.

Detailed instructions how to build vasm can be found in the last chapter.

The Assembler
*************

     [file vasm_main.texi not included]

Standard Syntax Module
**********************

     [file syntax_std.texi not included]

Mot Syntax Module
*****************

     [file syntax_mot.texi not included]

Madmac Syntax Module
********************

     [file syntax_madmac.texi not included]

Oldstyle Syntax Module
**********************

     [file syntax_oldstyle.texi not included]

Test output module
******************

     [file output_test.texi not included]

ELF output module
*****************

     [file output_elf.texi not included]

a.out output module
*******************

     [file output_aout.texi not included]

TOS output module
*****************

     [file output_tos.texi not included]

GST output module
*****************

     [file output_gst.texi not included]

Hunk-format output module
*************************

     [file output_hunk.texi not included]

X68k output module
******************

     [file output_xfile.texi not included]

O65 output module
*****************

     [file output_o65.texi not included]

vobj output module
******************

     [file output_vobj.texi not included]

Simple binary output module
***************************

     [file output_bin.texi not included]

Motorola S-Record output module
*******************************

     [file output_srec.texi not included]

Intel Hex output module
***********************

     [file output_ihex.texi not included]

C #define output module
***********************

     [file output_cdef.texi not included]

Project Hans custom output module
*********************************

     [file output_hans.texi not included]

Wozmon output module
********************

     [file output_woz.texi not included]

MOS paper tape output module
****************************

     [file output_pap.texi not included]

M68k cpu module
***************

     [file cpu_m68k.texi not included]

PowerPC cpu module
******************

     [file cpu_ppc.texi not included]

c16x/st10 cpu module
********************

     [file cpu_c16x.texi not included]

6502 cpu module
***************

     [file cpu_6502.texi not included]

SPC700 cpu module
*****************

     [file cpu_spc700.texi not included]

ARM cpu module
**************

     [file cpu_arm.texi not included]

80x86 cpu module
****************

     [file cpu_x86.texi not included]

Z80 cpu module
**************

     [file cpu_z80.texi not included]

6800 cpu module
***************

     [file cpu_6800.texi not included]

6809/6309/68HC12 cpu module
***************************

     [file cpu_6809.texi not included]

Jaguar RISC cpu module
**********************

     [file cpu_jagrisc.texi not included]

PDP11 cpu module
****************

     [file cpu_pdp11.texi not included]

unSP cpu module
***************

     [file cpu_unsp.texi not included]

HANS cpu module
***************

     [file cpu_hans.texi not included]

Trillek TR3200 cpu module
*************************

     [file cpu_tr3200.texi not included]

Interface
*********

     [file interface.texi not included]