413 lines
12 KiB
Groff
413 lines
12 KiB
Groff
.\" -*- nroff -*-
|
|
.\"
|
|
.\" zmac - Z80 macro cross-assembler
|
|
.\" Public domain by Bruce Norskog and others.
|
|
.\"
|
|
.\" zmac.1 - man page
|
|
.\"
|
|
.\" (version number below is purely for the sake of argument;
|
|
.\" it's probably about the millionth version IRL :-))
|
|
.\"
|
|
.TH zmac 1 "2000-07-02" "Version 1.3" "Development Tools"
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH NAME
|
|
zmac \- Z80 macro cross-assembler
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH SYNOPSIS
|
|
.PD 0
|
|
.B zmac
|
|
.RB [ --help ]
|
|
.RB [ --version ]
|
|
.RB [ -AbcdefghilLmnOpsStTz ]
|
|
.RB [ -o
|
|
.IR outfile ]
|
|
.RB [ -x
|
|
.IR listfile ]
|
|
.RI [ filename ]
|
|
.PD 1
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH DESCRIPTION
|
|
zmac is a Z80 macro cross-assembler. It has all the features you'd
|
|
expect. It assembles the specified input file (with a `.z' extension
|
|
if there is no pre-existing extension and the file as given doesn't
|
|
exist) and produces raw binary output
|
|
in a `.bin' file. (It can optionally produce CP/M-style Intel hex
|
|
format - see below.) By default it also produces a nicely-formatted
|
|
listing of the m/c alongside the source, in a `.lst' file.
|
|
.PP
|
|
As well as normal Z80 programs, zmac lets you write 8080 programs in
|
|
Z80 assembly. (See the `-z' option below.)
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH OPTIONS
|
|
Most of the options control aspects of the listing.
|
|
.TP
|
|
.I --help
|
|
Display a list of options and a terse description of what the options
|
|
do.
|
|
.TP
|
|
.I --version
|
|
Print version number.
|
|
.TP
|
|
.I -A
|
|
Add an AMSDOS header to the generated binary file (this option
|
|
automatically disables generation of hex output).
|
|
.TP
|
|
.I -b
|
|
Don't generate the m/c output at all.
|
|
.TP
|
|
.I -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.
|
|
.TP
|
|
.I -d
|
|
Make the listing discontinuous.
|
|
.TP
|
|
.I -e
|
|
Omit the `error report' section in the listing.
|
|
.TP
|
|
.I -f
|
|
List instructions not assembled due to `if' expressions being
|
|
false. (Normally these are not shown in the listing.)
|
|
.TP
|
|
.I -g
|
|
List only the first line of equivalent hex for a source line.
|
|
.TP
|
|
.I -h
|
|
Output CP/M-ish Intel hex format (using extension `.hex') rather than
|
|
the default of a simple binary file (extension `.bin').
|
|
.TP
|
|
.I -i
|
|
Don't list files included with `include'.
|
|
.TP
|
|
.I -l
|
|
Don't generate a listing at all.
|
|
.TP
|
|
.I -L
|
|
Generate listing no matter what. Overrides any conflicting options.
|
|
.TP
|
|
.I -m
|
|
List macro expansions.
|
|
.TP
|
|
.I -n
|
|
Omit line numbers from listing.
|
|
.TP
|
|
.I -o
|
|
Output assembled code to
|
|
.IR outfile .
|
|
.TP
|
|
.I -O
|
|
Suggest possible optimisations. (These are shown as warnings.)
|
|
.TP
|
|
.I -p
|
|
Use a few linefeeds for page break in listing rather than ^L.
|
|
.TP
|
|
.I -s
|
|
Omit the symbol table from the listing.
|
|
.TP
|
|
.I -S
|
|
When reporting an error, show the line which caused it. Without this
|
|
option zmac reports errors in the canonical format, one-per-line (but
|
|
see the first item in the
|
|
.B BUGS
|
|
section).
|
|
.TP
|
|
.I -t
|
|
Give terse (single-letter) error codes in listing (with a key at the
|
|
end). (Normally the full error message is given.)
|
|
.TP
|
|
.I -T
|
|
Enable DDE throwback for reporting warnings and errors. This option
|
|
only exists for RISC OS builds.
|
|
.TP
|
|
.I -x
|
|
Output listing to
|
|
.IR listfile .
|
|
(It outputs to stdout if you specify the file as `-'.)
|
|
This has no effect if used with
|
|
.IR -l .
|
|
.TP
|
|
.I -z
|
|
Accept 8080-compatible instructions only; flag any Z80-specific ones
|
|
as errors. This lets you write 8080 programs in Z80 assembly, without
|
|
having to worry about the deeply nasty 8080 assembly syntax. :-)
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH "INPUT FORMAT"
|
|
zmac uses the standard Zilog mnemonics, and the pseudo-ops are also
|
|
largely as you'd expect.
|
|
.PP
|
|
Input can be upper or lowercase.
|
|
.PP
|
|
Comments start with `;' and carry on
|
|
to the end of the line.
|
|
.PP
|
|
Labels are declared with
|
|
`label:', `.label', `:label' or just `label' -
|
|
indentation is unimportant. (Labels can be up to 40 chars long.)
|
|
.PP
|
|
Number constants can take a trailing h or a leading &, $ or # for hex,
|
|
a trailing b for binary, a trailing o or q for octal, or a trailing
|
|
d for decimal.
|
|
.PP
|
|
Here is how other things work:
|
|
.TP
|
|
.B defb 42
|
|
A byte. `ascii', `byte', `db', `defm' and `text' are synonyms.
|
|
.TP
|
|
.B defb 'foobar'
|
|
An ASCII character string (not NUL-terminated).
|
|
Double quotes can also be used.
|
|
.TP
|
|
\fBdefb 'Who needs MS-DOG when you have *CP/M*?', 13, 10, '$'\fP
|
|
Strings, bytes, and comp.os.msdos.programmer troll. :-)
|
|
.TP
|
|
.B defw 2112
|
|
A word (16 bits). `word' and `dw' are synonyms.
|
|
.TP
|
|
.B defs 500
|
|
Insert 500 zero bytes. `block', `ds' and `rmem' are synonyms.
|
|
.TP
|
|
.B org
|
|
Set the address to assemble to.
|
|
.TP
|
|
.B equ
|
|
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.
|
|
.TP
|
|
.B defl
|
|
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'.
|
|
.TP
|
|
.B 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 if zmac is writing a raw binary file. In an Intel
|
|
hex file, it generates an S-record directing 0 bytes of data to be loaded
|
|
at the given address.
|
|
.TP
|
|
\fBif\fP ... [ \fBelse\fP ... ] \fBendif\fP
|
|
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'.
|
|
.TP
|
|
\fBrsym\fP and \fBwsym\fP
|
|
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.
|
|
.TP
|
|
.B include
|
|
Include a file. Like C's (well, cpp's) #include, but the filename arg
|
|
lacks the angle brackets or quotes (though quotes may be used).
|
|
`read' is a synonym.
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH "ODDITIES"
|
|
There are the following oddities:
|
|
.TP
|
|
.B cmp
|
|
Same as `cp'.
|
|
.TP
|
|
.B jmp
|
|
Same as `jp'.
|
|
.TP
|
|
.B jp hl
|
|
Same as `jp (hl)'. Ditto for ix and iy.
|
|
.TP
|
|
.B ld hl, 'LH'
|
|
Oh, yes! Ditto for bc, de, sp, ix and iy.
|
|
.TP
|
|
\fBmin\fP and \fBmax\fP
|
|
Same as `defl' except that the symbol is defined as the
|
|
smaller or bigger of two comma-separated expressions.
|
|
.TP
|
|
\fBv\fP and \fBnv\fP
|
|
These are alternatives to `pe' and `po' respectively in `jp'
|
|
and `call' instructions, meaning that tests on the Z80's
|
|
(parity/)overflow flag can be written in the same
|
|
format (`x'/`nx') as for those on the zero or carry flags.
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH "LISTING PSEUDO-OPS"
|
|
There are several pseudo-ops for controlling the listing. None of
|
|
these ops appear in the listing themselves:
|
|
.TP
|
|
.B eject
|
|
Start a new listing page.
|
|
.TP
|
|
.B nolist
|
|
Do nothing. This can be used to have a comment in the source but not
|
|
the listing, I suppose.
|
|
.TP
|
|
.B "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.
|
|
.TP
|
|
.B 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..
|
|
.TP
|
|
.B title
|
|
Set title (used in listing and symbol file).
|
|
.TP
|
|
.B space
|
|
Output arg blank lines in the listing, or one line if no arg is given.
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH "EXPRESSIONS"
|
|
Expressions are reasonably full-featured; 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'.
|
|
.IP
|
|
! (logical), ~ not (bitwise), + (unary), - (unary)
|
|
.IP
|
|
*, /, % mod
|
|
.IP
|
|
+, -
|
|
.IP
|
|
<< shl, >> shr
|
|
.IP
|
|
< lt, > gt, <= le, >= ge
|
|
.IP
|
|
== = eq, != <> ne
|
|
.IP
|
|
& and (bitwise)
|
|
.IP
|
|
^ xor (bitwise)
|
|
.IP
|
|
| or (bitwise)
|
|
.PP
|
|
You can use normal parentheses or square brackets to override
|
|
the precedence rules; use square brackets where parentheses would
|
|
conflict with Z80 mnemonic syntax.
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH "MACROS"
|
|
The following defines a macro named m with zero or more formal parameters
|
|
p1, p2, ..., pn, zero or more local symbols ?s1, ?s2, ..., ?sm, and
|
|
body b1, b2, ...:
|
|
.IP
|
|
m macro p1, p2, ..., pn, ?s1, ?s2, ..., ?sm
|
|
.IP
|
|
b1
|
|
.IP
|
|
b2
|
|
.IP
|
|
...
|
|
.IP
|
|
endm
|
|
.PP
|
|
The macro is called by writing:
|
|
.IP
|
|
m v1, v2, ..., vn
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH "FILENAMES"
|
|
To allow source files to be portable, a canonical format should be
|
|
used for filenames in source files (i.e. in include, rsym or wsym
|
|
statements). This canonical format is basically the Un*x
|
|
format: `/' as the directory separator, `.' as the extension separator,
|
|
".." as the parent directory, "." as the current directory,
|
|
and a leading `/' as the root directory
|
|
(this should be avoided as it makes moving the source non-trivial).
|
|
.PP
|
|
For maximum portability, no element of such a filename should have
|
|
more than 10 characters, contain characters other than 0-9, a-z,
|
|
underscore and `.', or contain more than one `.'.
|
|
.PP
|
|
Filenames passed as command-line arguments (i.e. for the source
|
|
specification, or for the
|
|
.IR -o
|
|
or
|
|
.IR -x
|
|
options), however, are assumed to
|
|
be in the local (non-canonical) format; this includes the
|
|
extension separator (whether supplied or added) and any drive specifiers.
|
|
.PP
|
|
The OSes which are currently supported are Un*x, BeOS, DOS and RISC OS.
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH "MISCELLANEOUS"
|
|
In the symbol table listing, the `=' prefix is given for those symbols
|
|
defined by `equ' or `defl', and the `+' suffix is given for those
|
|
which were not used.
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH "EXIT STATUS"
|
|
.TP
|
|
.B 0
|
|
No errors.
|
|
.TP
|
|
.B 1
|
|
One or more errors were found during assembly, or zmac exited with a
|
|
fatal error.
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH BUGS
|
|
zmac reports each error in a line separately. This is probably a good
|
|
thing, but tends to effectively result in the same overall problem
|
|
being reported twice (e.g. a reference to an undefined symbol causes
|
|
both an undeclared error and a value error).
|
|
.PP
|
|
The man page isn't what you'd call extensive. This shouldn't be too
|
|
surprising as I had to RTFS to WTFM. :-)
|
|
.PP
|
|
What do phase/dephase do (they seem to be some way of temporarily
|
|
moving the program location -- for overlays?)?
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH "SEE ALSO"
|
|
.IR as "(1)"
|
|
.\"
|
|
.\"------------------------------------------------------------------
|
|
.\"
|
|
.SH AUTHOR
|
|
Bruce Norskog (in 1978!).
|
|
.PP
|
|
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.
|
|
.PP
|
|
Russell Marks wrote most of the man page, with tweaks by Mark RISON
|
|
and Tim Mann.
|