To reduce clutter and command line options, all zmac output is put into an (auto-created) zout subdirectory. For file.z the listing will be in zout/file.lst, the TRS-80 executable format in zout/file.cmd and so on.
Undocumented Z-80 instructions are supported as well as 8080 code.
zmac strives to be a powerful assembler with expressions familiar to C programmers while providing good backward compatibility with original assemblers such as Edtasm, MRAS and Macro-80.
--help | Display a list of options and a terse description of what the options do. |
--version | Print zmac version name. |
--mras | MRAS compatibility mode. Any ? in a label will be expanded to the current module identifier as set by *mod. |
--rel | Output ".rel" (relocatable object file) format only. |
--zmac | zmac compatibility mode. defl labels are undefined after each pass. Quotes and double quotes are stripped from macro arguments before expansion. $ is ignored in identifiers allowing foo$bar to construct identifiers in macro expansions. Use ` (backquote) instead in normal mode. Labels starting with "." are temporary and are reset whenever a non-temporary label is defined (thus they may be reused). Labels starting with "_" are local to their file thus avoid multiple definition when brought in with include. |
--dep | Print all files read by include and incbin. |
--doc | Print this documentation in HTML format to standard output. |
-8 | Accept 8080 mnemonics preferentially. Equivalent to .8080 pseudo-op. |
-b | Don't generate any machine code output at all. |
-c | Make the listing continuous, i.e., don't generate any page breaks or page headers. Can make things less confusing if you're going to consult the listing online rather than printing it. This is the default. |
-e | Omit the "error report" section in the listing. |
-f | List instructions not assembled due to "if" expressions being false. (Normally these are not shown in the listing.) |
-g | List only the first line of equivalent hex for a source line. |
-h | Display a list of options and a terse description of what the options do. (same as --help) |
-i | Don't list files included with include or read. |
-I dir | Add dir to the end of the include file search path. |
-j | Promote relative jumps and DJNZ to absolute equivalents as needed. |
-J | Error if an absolute jump could be replaced with a relative jump. |
-l | Don't generate a listing at all. |
-L | Generate listing no matter what. Overrides any conflicting options. |
-m | List macro expansions. |
-n | Omit line numbers from listing. |
-o | List to standard output. |
-p | Use a few linefeeds for page break in listing rather than ^L. |
-P | Output listing for a printer with headers, multiple symbols per column, etc. |
-s | Omit the symbol table from the listing. |
-t | Only output number of errors instead list of each one. |
-z | Accept Z-80 mnemonics preferentially. Equivalent to .z80 pseudo-op. |
zmac uses the standard Zilog mnemonics, and the pseudo-ops are also largely as you'd expect.
A "." may optionally preceeed any psuedo-op. For example, ".org" and "org" are treated as equivalent.
Input can be upper or lowercase.
Comments start with ; and carry on to the end of the line.
Number constants can take a trailing h or a leading $ or 0x for hex, a trailing b for binary, a trailing o or q for octal, or a trailing d for decimal.
'LH' (any length 2 string) can be treated as a number whose value is 'H' * 256 + 'L'.
Labels are declared with label: or just label - indentation is unimportant. Labels can be up to 40 chars long. They can start with and contain letters, digits, $, ., ?, @ and _. Ambiguous identifiers like $FCB will be treated as hex constants unless defined as a label. Labels declared with two colons (label::) make the label public.
Here is how other things work. Numbers are used as examples, but a full expression can be used in their place.
defb 42
A byte. ascii, byte, db, defm and text are synonyms.
defb 'foobar'
An ASCII character string (not NUL-terminated). Double quotes can also be used.
defb 'Who needs anything more than CP/M?',13,10,'$'
Strings and bytes can mix together.
defw 2112
defw $123,0x456
A word (16 bits). word and dw are synonyms.
defd $12345678
A double word (32 bits). dword is a synonym.
defs 500
Skip output ahead 500 bytes. This will insert 500 zeros in the ".ams" and ".cim" output files or if inside a ".phase" section. block, ds and rmem are synonyms.
dc 'string'
Like ascii but accepts only a single string and the high bit of the last character will be set.
dc count,value
Repeat the byte value a total of count times. Similar to defs except that memory is always filled with value.
incbin file
Inserts the raw contents of the file into the assembly. Simpler for large amounts of data.
label equ 100
Define a symbol to have a fixed value. The symbol can be used before it is defined. A symbol defined with equ or as a label can be defined only once, except that a symbol defined with equ may be redefined to the same value.
label defl 200
Define a symbol to have a changeable value. The symbol cannot be used before it is defined, and it can be redefined to a different value later with another defl. aset is a synonym.
min
max
Same as defl except that the symbol is defined as the smaller or bigger of two comma-separated expressions.
*mod
Increment the internal module name string. The first time this results in "a". Then "b", "c", ... "z". Then "aa", "ab", "ac", etc. all the way up to "zzzz". The module name string is used in --mras mode where "?" in label names is replaced with the current module name.
extern lab1,lab2,...
The listed labels are defined in an external module for later linking. No effect unless zmac is producing ".rel" output. ext and extrn are synonyms.
public lab1,lab2,...
The given labels will be visible to external modules when linking. No effect unless zmac is producing ".rel" output. global and entry are synonyms.
org 9000h
Set the address to assemble to 0x9000.
phase address
Continue to produce code and data for loading at the current address but assemble instructions and define labels as if they originated at the given address. Useful when producing code that will be copied to a different location before being executed (e.g., an overlay).
dephase
End phase mode assembly.
aseg cseg dseg
Switch to the absolute, code and data segments respectively. No effect unless zmac is producing ".rel" output.
end
Ends the input. Any lines after an end are silently ignored. If an arg is given, it declares the entry address for the program. This has no effect in ".cim" output. In ".hex" output it generates an S-record directing 0 bytes of data to be loaded at the given address.
if ... [ else ... ] endif
For conditional assembly. If you do if foo and foo evaluates to zero, all the lines up until the next corresponding else or endif are completely ignored. Conversely, if foo evaluates to non-zero, any lines from a corresponding else to the endif are ignored. Ifs can be nested. cond/endc are synonyms for if/endif.
include file
Include a file. Like C's (well, cpp's) #include and follows the same include path search rules, but the filename arg lacks the angle brackets or quotes (though single or double quotes may be used). read is a synonym.
comment X
Suspend assembly until the next occurence of character X on a line. The rest of the line will be ignored. A multi-line comment.
assert expr
Stop assembly if expr is non-zero.
sett expr
Set the current T-state count to expr. tstate is a synonym.
setocf expr
Set the current opcode fetch count to expr.
8080
Make cycle counting operators return 8080 cycle counts and interpret any ambiguous assembly statements as Intel 8080 mnemonics. CP will be interpreted as "call on positive" and JP as "jump on positive".
z80
Make cycle counting operators return Z-80 cycle counts and interpret any ambiguous assembly statements as Zilog Z-80 mnemonics. CP will be interpreted as "compare accumulator" and JP as "jump unconditionally".
jperror enable
If enable is non-zero, turn on errors when JR instructions could be used instead of JP, off otherwise. Used to check existing code for situations where shorter code could be generated. Same as -J option. No effect if in 8080 mode.
jrpromote enable
If enable is non-zero, JR and DJNZ instructions will be promoted to equivalent JP and DEC B, JP NZ instructions if the relative branch offset is out of range. If enable is zero, promotion is disabled. Same as the -j option. No effect if in 8080 mode.
Most Z-80 chips support a number of undocumented instructions that were part of the original design but not made an offical part of the Zilog specification. These instructions may not be supported by all Z-80 chips, especially licensed variants, but are fairly widely available nonetheless.
sl1 r
Same as sla r but shifts a 1 into the lower bit of r rather than a 0.
in (c)
Inputs a byte from port c but does not store the value. Flags are still set as with the normal in r,(c) instruction.
out (c),0
Outputs a zero to port c.
bit/set/res n,(ix+d),r
rlc/rrc/rl/rr/sla/sl1/sra/srl (iy+d),r
Same as the corresponding operation on just (ix+d) or (iy+d) but with the result being stored both into (ix+d) and register r. Except for bit which has no effect on r. zmac supports the syntax to allow those instruction patterns to be generated.
The upper and lower bytes of the ix and iy can be used in a number of instructions much in the same way as d and e correspond to the upper and lower bytes of de. zmac names these ixh, ixl, iyh and iyl and are referred to generically as ixylh here.
inc/dec/add/adc/sub/sbc/and/xor/or/cp ixylh
Arithmetic or logical operation on ix or iy high or low byte.
ld a/b/c/d/e,ixylh
Load register with ix or iy high or low byte.
ld ixylh,a/b/c/d/e
Load ix or iy high or low byte with register.
pfix
pfiy
Output $DD and $FD prefix bytes. The Z-80 allows multiple prefix bytes for IX and IY instructions. This allows you to specify them abstractly. There is little purpose except for delaying an interrupt or confusing disassemblers.
name str
Set the name of the output model to str. For compatibility reasons str may be parenthesized (e.g., "name ('foo')"). Not all output formats support an internal name and many have severe length limits.
rsym and wsym
Read/write a symbol file. These simply load/save the currently defined symbols from/to the file specified (in a non-portable format). rsym takes place at the point it is encountered in the file (on the first pass); wsym is delayed until assembly has finished.
There are several pseudo-ops for controlling the listing. None of these ops appear in the listing themselves:
eject
Start a new listing page.
nolist
Do nothing. This can be used to have a comment in the source but not the listing, I suppose.
elist, flist, glist, mlist
These have the same effect as the similarly-named command-line options, though possibly with the sense reversed depending on the default. Use an arg >0 (or no arg) to enable, and an arg <0 to disable.
list
Sets whether to list or not. You can use this to avoid listing certain parts of the source. Takes same optional arg as 'elist', etc..
title
Set title (used in listing and symbol file).
space
Output arg blank lines in the listing, or one line if no arg is given.
Expressions feature a full set of C operators with the same precedence rules and some common assembler extensions and names. Here is the complete list of operators, highest-precedence first. Operators separated only by a space are synonyms; for example, ~ is the same as not.
! (logical), ~ not (bitwise), + (unary), - (unary), low, high, t, tilo, tihi, ocf
*, /, % mod
+, -
<< shl, >> shr
< lt, > gt, <= le, >= ge
== = eq, != <> ne
& and (bitwise)
^ xor (bitwise)
| or (bitwise)
&&
||
? : (ternary choice operator)
You can use normal parentheses or square brackets to override the precedence rules. Square brackets can be used where parentheses would conflict with Z-80 mnemonic syntax, but this is not necessary in any practical case.
The ? may need spaces around it to distinguish it from a label that has ? in it.
The unary operators not familiar to C programmers:
low expr | Returns low 8 bits of expr |
high expr | Returns high 8 bits of expr |
t expr | Current count of T-states up to memory location expr |
tilo expr | Low count of T-states used by instruction at memory location expr |
tihi expr | High count of T-states used by instruction at memory location expr |
ocf expr | Current count of opcode fetches up to memory location expr |
m macro p1, p2, ..., pn, ?s1, ?s2, ..., ?sm | |
b1 | |
b2 | |
... | |
endm |
The macro is called by writing:
m v1, v2, ..., vn
A macro call expands to the text of the macro's body, with each occurrence of a formal parameter pk replaced by the corresponding value vk, and with each local symbol ?sk replaced by a new, unique symbol invented for this call. Invented symbols begin with ?, so you should avoid using such symbols elsewhere in your program.
zmac currently does not check that you have provided the right number of parameters when calling a macro. If you provide too few, unmatched formals are replaced with the empty string. If you provide too many, the additional values begin to replace local symbols as if they were ordinary parameters. (This could be considered a feature.) After the local symbols are all replaced, additional parameters are silently ignored.
For compatibility with Macro-80, the first line of a macro definition can list other labels that will be treated locally:
local lab1,lab2,...
Each time the macro is expanded the local labels are replaced with unique names thus avoiding multiple definition problems.
For compatability with MRAS, macro arguments may be preceeded by in their definition and use.
Any ` (backquote) in a macro is ignored thus allowing a macro to construct identifiers. For example:
move macro dir | |
ld`dir`r | |
endm |
Invoking move i will construct a ldir block move instruction.
zmac is broadly compatible with many original Z-80 and 8080 assemblers because it accepts many different names for common operations and has liberal identifier and numeric formats. It also accepts most simple usage of macros.
When assembling old code keep these portability problems in mind.
Expression order of evaluation may be different. zmac uses C semantics more order of evaluation but assemblers often used simple left to right ordering. zmac will evaluate 2+2*3 as 8 where other assemblers will yield 12.
zmac has no support operating on strings in macros. Assemblers like Macro-80 could perform conditional tests on strings.
Advanced macros are unlikely to work. zmac hasn't advanced to the state where all the possible ways of substituting parameters are supported. Nor does it have simple repetition, a way to exit a macro expansion early and so on.
Consult the original assembler manual. zmac error messages won't help you figure out what an unknown assembler command is supposed to do.
Compare against original output. The very safest thing to do when porting assembly code is to compare the binary output of zmac against that produced by the original assembler. This way you can ensure everything has been interpreted correctly. Only once that has been achieved should you modify the code.
Any errors or warnings encountered during assembly are reported to standard error and in the listing file. The errors output immediately give the source file and line number containing the error. In listings the error letter and message appear just after the line containing the error.
B | Balance error |
| A string is missing an closing quote or an if is missing an endif | |
E | Expression error |
| An expression did not parse or attempts a divide or modulus by 0. | |
F | Syntax error |
| General problem with the syntax on a line. Sometimes extra explanation will be printed on standard output. | |
I | Digit error |
| A numeric constant has too many digits to be represented as a 32 bit number. | |
M | Mult. def. error |
| A symbol has been defined more than once and those values differ. | |
P | Phase error |
| On the second or subsequent assembly passes the assembly has changed significantly. Most commonly it means an if has changed conditions but can also happen when labels or equated values do not converge to a fixed value. | |
U | Undeclared error |
| An undeclared symbol was used in an expression or public statement. | |
V | Value error |
| An invalid value was given to a statement. Often this means using less than -128 or greater then 255 in a defb or less than -32768 or greater than 65535 in a defw. Or similar invalid values used Z-80/8080 opcodes requiring an 8 or 16 bit value (and other restrictions like 0 to 7 for BIT). Also if a relative jump is out of range or if a negative value is given in defs or dc. | |
O | Phase/Dephase error |
| phase was used within another phase or dephase without phase. Or if org is used within phase. | |
A | Assertion failure error |
| An assert statement evaluated to zero. | |
J | Use JR error |
| An absolute jump instruction was used where relative jump was in range of the destination address. Only generated if -j or jrpromote is in effect. | |
R | Not relocatable error |
| An expression was used that must be generated at link time but cannot be handled by the ".rel" format. For instance, an org to a symbol in the data segment when in the code segment. Or a relative jump to a different segment. The ".rel" format can evaluate expressions at link time using the high, low, not, -, +, *, / and % operators. zmac is clever enough to use high or low in place of & $ff00 and & 255. But it won't replace a shl with a multiply. | |
G | Register usage error |
| A invalid register was given to an instruction. For example, LD B,(DE) or ADD HL,IX. | |
Z | Z-80 instruction in 8080 mode error |
| An instruction was assembled that is only valid on the Z-80 but .8080 (or -8) mode is in effect. However, use use of Z-80 mnemonics that output valid 8080 instructions is always OK. | |
H | $hex constant interpreted as symbol warning |
| A symbol such as $FCB has been defined even though it could appear to be a hexadecimal constant. zmac will treat $FCB as symbol for the entire assembly which could be rather surprising if that were not the intent. | |
N | Not implemented warning |
| For statements that have been added as parse rules but have no effect. The only current example is subttl which sets the sub title of a listing in certain assemblers. |
Except for ".rel", zmac writes every known output when assembling. This is no burden on modern computers and saves having to come up with options to select a particular output format.
".rel" is a special case since that format is intended for linking and can have undefined external symbols which would be errors in the other formats which do not support them.
.ams | AMSDOS executable format for Amstrad computers. |
.bds | Experimental format with the potential for source-level debugging. |
.cas | TRS-80 high-speed (1500 baud) cassette SYSTEM file. The internal name of the file is the source file name shortened to 6 characters with suffixes removed. |
.cim | Core In-Memory image. A raw binary format with the first byte corresponding to the lowest generated code or data and proceeding contiguously until the highest address generated. Any gaps are filled with zeros. Typically used for CP/M where all executables start at address 256 or for ROM images. |
.cmd | TRS-80 DOS executable file format as used by all major DOSes on the TRS-80 (TRS-DOS, LDOS, MULTIDOS, NEWDOS, etc.) |
.hex | Intel hex record format. |
.lcas | TRS-80 low-speed (500 baud) cassette SYSTEM file. The internal name of the file is the source file name shortened to 6 characters with suffixes removed. |
.rel | Relocatable object module format as produced by MACRO-80 and other assemblers. |
0 | No errors. |
1 | One or more errors were found during assembly, or zmac exited with a fatal error. |
Updates and bugfixes over the years by John Providenza, Colin Kelley, and more recently by Russell Marks, Mark RISON, Chris Smith, Matthew Phillips and Tim Mann.
Extensive modifications for cycle counting, multiple output formats, ".rel" output, 8080 mode and older assembler compatibilty were written by George Phillips.
This document was based on Russell Marks zmac man page which had tweaks by Mark RISON and Tim Mann. George Phillips converted it to HTML and documented the new features and some older ones (e.g., phase/dephase).