463 lines
14 KiB
Plaintext
463 lines
14 KiB
Plaintext
|
|
|
|
|
|
zmac(1) Development Tools zmac(1)
|
|
|
|
|
|
NAME
|
|
zmac - Z80 macro cross-assembler
|
|
|
|
SYNOPSIS
|
|
zmac [--help] [--version] [-AbcdefghilLmnOpsStTz] [-o out-
|
|
file] [-x listfile] [filename]
|
|
|
|
DESCRIPTION
|
|
zmac is a Z80 macro cross-assembler. It has all the fea-
|
|
tures you'd expect. It assembles the specified input file
|
|
(with a `.z' extension if there is no pre-existing exten-
|
|
sion 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 along-
|
|
side the source, in a `.lst' file.
|
|
|
|
As well as normal Z80 programs, zmac lets you write 8080
|
|
programs in Z80 assembly. (See the `-z' option below.)
|
|
|
|
OPTIONS
|
|
Most of the options control aspects of the listing.
|
|
|
|
--help Display a list of options and a terse description
|
|
of what the options do.
|
|
|
|
--version
|
|
Print version number.
|
|
|
|
-A Add an AMSDOS header to the generated binary file
|
|
(this option automatically disables generation of
|
|
hex output).
|
|
|
|
-b Don't generate the m/c 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 list-
|
|
ing online rather than printing it. This is the
|
|
default.
|
|
|
|
-d Make the listing discontinuous.
|
|
|
|
-e Omit the `error report' section in the listing.
|
|
|
|
-f List instructions not assembled due to `if' expres-
|
|
sions being false. (Normally these are not shown in
|
|
the listing.)
|
|
|
|
-g List only the first line of equivalent hex for a
|
|
source line.
|
|
|
|
-h Output CP/M-ish Intel hex format (using extension
|
|
`.hex') rather than the default of a simple binary
|
|
|
|
|
|
|
|
Version 1.3 2000-07-02 1
|
|
|
|
|
|
|
|
|
|
|
|
zmac(1) Development Tools zmac(1)
|
|
|
|
|
|
file (extension `.bin').
|
|
|
|
-i Don't list files included with `include'.
|
|
|
|
-l Don't generate a listing at all.
|
|
|
|
-L Generate listing no matter what. Overrides any con-
|
|
flicting options.
|
|
|
|
-m List macro expansions.
|
|
|
|
-n Omit line numbers from listing.
|
|
|
|
-o Output assembled code to outfile.
|
|
|
|
-O Suggest possible optimisations. (These are shown as
|
|
warnings.)
|
|
|
|
-p Use a few linefeeds for page break in listing
|
|
rather than ^L.
|
|
|
|
-s Omit the symbol table from the listing.
|
|
|
|
-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 BUGS section).
|
|
|
|
-t Give terse (single-letter) error codes in listing
|
|
(with a key at the end). (Normally the full error
|
|
message is given.)
|
|
|
|
-T Enable DDE throwback for reporting warnings and
|
|
errors. This option only exists for RISC OS
|
|
builds.
|
|
|
|
-x Output listing to listfile. (It outputs to stdout
|
|
if you specify the file as `-'.) This has no
|
|
effect if used with -l.
|
|
|
|
-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.
|
|
:-)
|
|
|
|
INPUT FORMAT
|
|
zmac uses the standard Zilog mnemonics, and the pseudo-ops
|
|
are also largely as you'd expect.
|
|
|
|
Input can be upper or lowercase.
|
|
|
|
Comments start with `;' and carry on to the end of the
|
|
line.
|
|
|
|
|
|
|
|
Version 1.3 2000-07-02 2
|
|
|
|
|
|
|
|
|
|
|
|
zmac(1) Development Tools zmac(1)
|
|
|
|
|
|
Labels are declared with `label:', `.label', `:label' or
|
|
just `label' - indentation is unimportant. (Labels can be
|
|
up to 40 chars long.)
|
|
|
|
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.
|
|
|
|
Here is how other things work:
|
|
|
|
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 MS-DOG when you have *CP/M*?', 13, 10, '$'
|
|
Strings, bytes, and comp.os.msdos.programmer troll.
|
|
:-)
|
|
|
|
defw 2112
|
|
A word (16 bits). `word' and `dw' are synonyms.
|
|
|
|
defs 500
|
|
Insert 500 zero bytes. `block', `ds' and `rmem'
|
|
are synonyms.
|
|
|
|
org Set the address to assemble to.
|
|
|
|
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.
|
|
|
|
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'.
|
|
|
|
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.
|
|
|
|
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,
|
|
|
|
|
|
|
|
Version 1.3 2000-07-02 3
|
|
|
|
|
|
|
|
|
|
|
|
zmac(1) Development Tools zmac(1)
|
|
|
|
|
|
any lines from a corresponding `else' to the
|
|
`endif' are ignored. Ifs can be nested.
|
|
`cond'/`endc' are synonyms for `if'/`endif'.
|
|
|
|
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 assem-
|
|
bly has finished.
|
|
|
|
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.
|
|
|
|
ODDITIES
|
|
There are the following oddities:
|
|
|
|
cmp Same as `cp'.
|
|
|
|
jmp Same as `jp'.
|
|
|
|
jp hl Same as `jp (hl)'. Ditto for ix and iy.
|
|
|
|
ld hl, 'LH'
|
|
Oh, yes! Ditto for bc, de, sp, ix and iy.
|
|
|
|
min and max
|
|
Same as `defl' except that the symbol is defined as
|
|
the smaller or bigger of two comma-separated
|
|
expressions.
|
|
|
|
v and nv
|
|
These are alternatives to `pe' and `po' respec-
|
|
tively 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.
|
|
|
|
LISTING PSEUDO-OPS
|
|
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
|
|
|
|
|
|
|
|
Version 1.3 2000-07-02 4
|
|
|
|
|
|
|
|
|
|
|
|
zmac(1) Development Tools zmac(1)
|
|
|
|
|
|
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
|
|
Expressions are reasonably full-featured; here is the com-
|
|
plete list of operators, highest-precedence first. Opera-
|
|
tors separated only by a space are synonyms; for example,
|
|
`~' is the same as `not'.
|
|
|
|
! (logical), ~ not (bitwise), + (unary), - (unary)
|
|
|
|
*, /, % mod
|
|
|
|
+, -
|
|
|
|
<< shl, >> shr
|
|
|
|
< lt, > gt, <= le, >= ge
|
|
|
|
== = eq, != <> ne
|
|
|
|
& and (bitwise)
|
|
|
|
^ xor (bitwise)
|
|
|
|
| or (bitwise)
|
|
|
|
You can use normal parentheses or square brackets to over-
|
|
ride the precedence rules; use square brackets where
|
|
parentheses would conflict with Z80 mnemonic syntax.
|
|
|
|
MACROS
|
|
The following defines a macro named m with zero or more
|
|
formal parameters p1, p2, ..., pn, zero or more local sym-
|
|
bols ?s1, ?s2, ..., ?sm, and body b1, b2, ...:
|
|
|
|
m macro p1, p2, ..., pn, ?s1, ?s2, ..., ?sm
|
|
|
|
b1
|
|
|
|
b2
|
|
|
|
...
|
|
|
|
endm
|
|
|
|
|
|
|
|
Version 1.3 2000-07-02 5
|
|
|
|
|
|
|
|
|
|
|
|
zmac(1) Development Tools zmac(1)
|
|
|
|
|
|
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 fea-
|
|
ture.) After the local symbols are all replaced, addi-
|
|
tional parameters are silently ignored.
|
|
|
|
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 separa-
|
|
tor, `.' 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).
|
|
|
|
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 `.'.
|
|
|
|
Filenames passed as command-line arguments (i.e. for the
|
|
source specification, or for the -o or -x options), how-
|
|
ever, are assumed to be in the local (non-canonical) for-
|
|
mat; this includes the extension separator (whether sup-
|
|
plied or added) and any drive specifiers.
|
|
|
|
The OSes which are currently supported are Un*x, BeOS, DOS
|
|
and RISC OS.
|
|
|
|
MISCELLANEOUS
|
|
In the symbol table listing, the `=' prefix is given for
|
|
those symbols defined by `equ' or `defl', and the `+' suf-
|
|
fix is given for those which were not used.
|
|
|
|
EXIT STATUS
|
|
0 No errors.
|
|
|
|
1 One or more errors were found during assembly, or
|
|
zmac exited with a fatal error.
|
|
|
|
|
|
|
|
Version 1.3 2000-07-02 6
|
|
|
|
|
|
|
|
|
|
|
|
zmac(1) Development Tools zmac(1)
|
|
|
|
|
|
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 ref-
|
|
erence to an undefined symbol causes both an undeclared
|
|
error and a value error).
|
|
|
|
The man page isn't what you'd call extensive. This
|
|
shouldn't be too surprising as I had to RTFS to WTFM. :-)
|
|
|
|
What do phase/dephase do (they seem to be some way of tem-
|
|
porarily moving the program location -- for overlays?)?
|
|
|
|
SEE ALSO
|
|
as(1)
|
|
|
|
AUTHOR
|
|
Bruce Norskog (in 1978!).
|
|
|
|
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.
|
|
|
|
Russell Marks wrote most of the man page, with tweaks by
|
|
Mark RISON and Tim Mann.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Version 1.3 2000-07-02 7
|
|
|
|
|