Chapter 3. LWASM

The LWTOOLS assembler is called LWASM. This chapter documents the various features of the assembler. It is not, however, a tutorial on 6x09 assembly language programming.

3.1. Command Line Options

The binary for LWASM is called "lwasm". Note that the binary is in lower case. lwasm takes the following command line arguments.

--6309, -3

This will cause the assembler to accept the additional instructions available on the 6309 processor. This is the default mode; this option is provided for completeness and to override preset command arguments.

This option is the same as if the first line of the source code is "PRAGMA 6309".

--6800compat

This is equivalent to --pragma=6800compat.

This will enable recognition of 6800 compatibility instructions.

--6809, -9

This will cause the assembler to reject instructions that are only available on the 6309 processor. This actually has the effect of starting the assembler as though the first line of the source is "PRAGMA 6809".

--decb, -b

Select the DECB output format target. Equivalent to --format=decb.

While this is the default output format currently, it is not safe to rely on that fact. Future versions may have different defaults. It is also trivial to modify the source code to change the default. Thus, it is recommended to specify this option if you need DECB output.

--format=type, -f type

Select the output format. Valid values are obj for the object file target, decb for the DECB LOADM format, os9 for creating OS9 modules, raw for a raw binary, hex for ASCII hexadecminal format, srec for Motorola S-Record format, and ihex for Intel Hex format.

--list[=file], -l[file]

Cause LWASM to generate a listing. If file is specified, the listing will go to that file. Otherwise it will go to the standard output stream. By default, no listing is generated. Unless --symbols is specified, the list will not include the symbol table.

--symbol-dump[=file]

Cause LWASM to output the global symbol table in assembly source format. If file is specified, the table output will go to the specified file. Otherwise, it will go to the standard output stream. Local symbols will not be included. Incomplete symbols will be defined to zero with a comment indicating incompleteness. Symbols defined with SET will also be listed using SET in the symbol dump. However, if the symbol is defined multiple times, the order of the definitions in the dump file is undefined.

--symbols, -s

Causes LWASM to generate a list of symbols when generating a listing. It has no effect unless a listing is being generated.

--symbols-nolocals

Behaves just like --symbols but with local labels omitted.

--map=FILE

This option generates a map file which can be used by debuggers and monitors to provide symbol information. A map file may be created independent of a listing file. (Patches are pending for MAME and exec09.)

--obj

Select the proprietary object file format as the output target.

--output=FILE, -o FILE

This option specifies the name of the output file. If not specified, the default is a.out.

--no-output

Do assembly as usual but suppress generation of the output file.

--pragma=pragma, -p pragma

Specify assembler pragmas. Multiple pragmas are separated by commas. The pragmas accepted are the same as for the PRAGMA assembler directive described below.

--raw, -r

Select raw binary as the output target.

--includedir=path, -I path

Add path to the end of the include path.

--define=SYM[=VAL], -D SYM[=VAL]

Pre-defines the symbol SYM as either the specified VAL. If VAL is omitted, the symbol is defined as 1. The symbol will be defined as though it were defined using the SET directive in the assembly source. That means it can be overridden by a SET directive within the source code. Attempting to redefine SYM using EQU will result in a multiply defined symbol error.

-t WIDTH, --tabs=WIDTH

Specifies the handling of tabs in listing files. --tabs=0 disables tab expansion. --tabs=8 is the default setting.

--help, -?

Present a help screen describing the command line options.

--usage

Provide a summary of the command line options.

--version, -V

Display the software version.

--debug, -d

Increase the debugging level. Only really useful to people hacking on the LWASM source code itself.