maz

Macro Assembler for Z80

Maz is a Z80 macro assembler, which is currently under development. I wouldn't advise using it until it's at version 1, or at least until I change this message.

Command Line

If using a new version of npm, you can run maz using npx: 'npx maz ...'. The command line parameters are:

| Option (short and long) | Description | |--------|-------------| | -s filename--src filename | The source file to assemble | | -o filename--out filename | The binary file to output to | | -l filename--list filename | The listing file to create | | -b--brief | Show brief error messages | | -u--undoc | Show warnings when undocumented instructions are used | | -p path--path path | Specify a directory to search in when looking for files to include. This option can be specified multiple times. |

Numbers

Numbers are decimal unless one of the following applies:

• Numbers which start with $ or end with h are in hex
• Numbers which end with o are in octal
• Numbers which start with % or end with b are in binary

Numbers can have _ in them to improve readability: eg: 1101_0100_1010_1111b

Strings

Source files are expected to be encoded in UTF-8, and so all strings are processed as UTF-8 strings. Characters in the range 00-7F are the same as ASCII characters. Example:

68           db "h"
c3 9f        db "ß"
e2 84 a2     db "™"
f0 9f 98 81  db "😁"

Strings can be entered just like JavaScript strings. They can be enclosed in double or single quotes, and support the following escape sequences:

|Code |Output | |-------|---------| |\0 | a NULL character (0) | |\' | a single quote | |\" | a double quote | |\\ | a backslash | |\n | a newline (10) | |\r | a carriage return (13) | |\v | a vertical tab (11) | |\t | a tab (9) | |\b | a backspace (8) | |\f | a formfeed (12) | |\xXX | a Latin-1 character | |\uXXXX | a Unicode character |

Note that although you can enter a latin character such as \xFF, because the string is encoded at UTF-8 it will actually be made up of two bytes: C3 BF.

One and two character strings can be used as numbers, where the first byte is the low order byte and the second is the high order byte. For example, "ab" is the equivalent of $6261. (When I say two character strings, I really mean two bytes, when encoded in UTF-8).

You can also repeat a string using the multiplication operator: "ho! " * 3 results in "ho! ho! ho!" (However, "ho" * 3 produces a number).

Labels

Labels contains any of the following: a-z, A-Z, 0-9, _

$ can be used to refer to the address of the current statement. In the case of DBs, it refers to the address of the start of the DBs.

When defining a label in a block, you can prefix it with an at symbol (@) to make it public. This makes it get declared at the top level instead of in the block's scope.

Macros may have the same name as a label.

There are no reserved words, so you may have labels which are the same as registers, and macros which are the same as instructions. This will be very confusing though, and will cause you to end up with ridiculous bugs in your code.

Addresses

When assembling the code, there are two addresses which are tracked: the output address, and the code address. The output address defines where the generated bytes go in memory and in the output file. The code address initially is the same as the output address, but it is possible to change this using the PHASE directive. When this happens then the code is assembled as if it were to go in memory at the code address, but it still get places at the output address. This is useful if the assembled code is going to get copied to a different location before execution. The output and code addresses both start at 0 until set by ORG or PHASE.

Some example code, including the output on the left (output address, followed by bytes). Notice how the second jump instruction jumps to $200, despite the fact that the 'two' label is output at location $105.

                  .org $100
0100 3e01         one:   ld a,1
0102 c30001              jp one
                  .phase $200
0105 3e01         two:   ld a,1
0107 c30002              jp two

Directives

Any directive shown below without a leading full stop (period) may also be written with a leading full stop. The full stop is not optional if it is shown.

db 0,1,100,$12,"hello\n",$1234
00 01 64 12 68 65 6c 6c 6f 0a 34

dw 0,$1234,"hello",$12345
00 00 34 12 68 65 6c 6c 6f 00 45 23

ds 12

org $100

macro add a,b

.include "something/routines.z80"

Note that the if expression must be evaluable on the first pass of assembly. Also, weird things might happen if an .if-.else-.endif block crosses a macro boundary.

Expressions

Maz supports expressions with proper precedence, and various different syntaxes for operators. The operators are, in order of precedence (highest first):

| Operators | Description | |-----------|-------------| | ( ) function() | ( ) → bracketsfunction() → various functions (see below) | | ! ~ + - | Unary operators! → logical not~ → bitwise not + → unary plus- → unary minus | * / % mod | * → multiply/ → divide% or mod → modulus | | + - | + → add- → subtract | | << shl >> shr | << or shl → shift left>> or shr → shift right | | < lt > gt <= le >= ge | < or lt → less than> or gt → greater than<= or le → less than or equal>= or ge → greater than or equal | | & and | & or and → bitwise and | | ^ xor | ^ or xor → bitwise xor | | | or | | or or → bitwise or | | && | && → logical and | | || | || → logical or | | ?: | ?: → ternary operator |

Textual operators must be followed by either some whitespace or an open bracket.

Functions

There are some functions which you can use in expressions:

| Function | Description | |----------|-------------| | min(x, y, ...) | Returns the smallest value | | max(x, y, ...) | Returns the largest value | | swp(x) | Swaps high and low order bytes of number x | | cat(x, y, ...) | Concatenates the strings | | rpt(s, n) | Repeat string s, n times |

Instructions

Maz supports all undocumented Z80 instructions. See this website for a list of undocumented instructions: http://clrhome.org/table/

The Z80 instruction syntax is a little inconsitent around some 8-bit instructions, for example ADD A,B includes the accumulator, but SUB B doesn't. When using Maz the "A," is optional for all of the following instructions: ADD, ADC, SUB, SBC, AND, XOR, OR, CP.