MZT

My Z80 Tools

MZT or My Z80 Tools is a complete set of cross-assembly tools targeted at the Z80 cpu in a Linux enviroment. It includes a macro assembler (mzmac), a linker/librarian (mld80) and a disassembler (mdz80).
The components of MZT are designed to provide a set of well-integrated tools capable to operate in the most recent versions of 64-bit Linux.

All the software si derived by a fork of existing projects. See in the sections relative to each tool for original authors credits.

MZT needs cmake to compile. Cmake is available on all major Linux distributions and you can always visit project site www.cmake.org for additional informations.

Why MZT?
I could answer with a simple "why not?", but the point is that the tools available do not usually make a unique environment, or do not have all the features that I want, or simply they do not fit my tastes and way of working, and since i still spent much time on Z80 projects this is more then enough for me to write a new one.

If you are of those in a hurry, you can jump directly to the downloads, or you can read more in each tool's section: mzmac, mld80, mdz80.

Installation

Install cmake, if you do not already have it on your system.

Extract MZT tar file in a working subdirectory and then do:

$ make; make install

                                                

By default MZT will be installed in /usr/local, if this is not what you want, in MZT top directory you can edit the Makefile and change the value of the variable INSTALL_PREFIX to your desired installation path.

Depending on where you decide to install MZT executables, you may need root permissions to do "make install".

Mzmac is a macro cross-assembler for the Z80 and is based onthe well-known zmac of which it inherits all the features. In particular mzmac is based onthe highly advanced version of zmac developed by George Phillips that includes, among other features, cycle counting and various output formats including the most important ".rel".

Mzmac differs from its predecessor in management of output formats, the format of listing and in management of options from command line.

It also has a better support for 64-bit environments, reformatted source code and some minor improvements/bug fixing.
At present mzmac is able to successfully compile almost every kind of source including CP/M 3.
An integral partof mzmac is its support for macro directives in style of m80, rmac or SLR.
In the current version however, are not yet supported the following directives: IRP, IRPC, REPT and EXITM.
The implementation of these directives has the highest priority among the objectives of the next release.

Mzmac exactly as zmac has a long list of credits: Bruce Norskog wrote the original version in 1978 and then it was updated by John Providenza, Colin Kelley, Russell Marks, Mark Rison, Chris Smith, Matthew Phillips and Tim Mann.

Finally George Phillips has written the versions on which mzmac is based.

Usage:

 It has the following options:

        --version show version number
        -8      use 8080 interpretation of mnemonics
        -b      no binary (.hex,.cmd,.cas, etc.) output
        -c      add cycle counts in listing
        -d      make the listing discontinuous.
        -e      error list only
        -f      print if skipped lines
        -g      do not list extra code
        -h      show this information about options and quit
        -i      do not list include files
        -I dir  add 'dir' to include file search path
        -j      promote relative jumps to absolute as needed
        -J      warn when a jump could be relative
        -l      no list
        -L      force listing of everything
        -m      print macro expansions
        -n      put line numbers off
        -p      put out four \n's for eject
        -s      don't produce a symbol list
        -t      output error count instead of list of errors
        -x      generate listing to `listfile' (`-' for stdout)
        -z      use Z-80 interpretation of mnemonics

        --bin   output .bin file (default)
        --ams   output .ams file
        --bds   output .bds file
        --cas   output .cas file
        --cmd   output .cmd file
        --hex   output .hex file
        --lcas  output .lcas file
        --rel   output .rel file

        --dep   list files included
        --mras  limited MRAS/EDAS compatibility
        --help  show detailed help
        --html  output detailed help in HTML format
                                                

Using --help or --html, produce a much more informative help page, respectively in (coloured) text or in HTML format that you can also read here.

Apart its ability to produce .rel format output, mzmac can perform accurate timing evaluation (cycle counting) on assembled code. George Phillips has written an interesting tutorial on this at his site.

Known bugs:

Equates of this kind:

TRUE        EQU    0FFFFH
FALSE       EQU    0
                                                
                                                

are not always evaluated correctly.

Replace with this to be sure:

TRUE        EQU    -1
FALSE       EQU    0
                                                
                                                

Mld80 is the linker/librarian tool of MZT toolset.

While it is a replacement for the Micrososft L80 linker for CP/M and incorporates almost all of its capabilities, mld80 has also extra features.

Mld80 accepts object (.rel) files produced by mzmac or by original m80, rmac or compatible assemblers as well as library (.rel) files made by LIB80.

In this initial release it does not support any of expected librarian function (create or add/change/remove members). It is also not capable to produces .SPR, .PRL or .OVL files.

All this features will be in the next release.

Mld80 is a derivative of ld80 by Gábor Kiss.

Usage:

mld80 -o outfile [options] objectfile ...

Addresses must be in the range 0-FFFF and expressed in hexadecimal notation. Addresses prefixed by a percent (%), as %NNNN, are not absolute and instructs mld80 to place following segments on a NNNN-boundary.

E.g. -D%10 causes the following data segments to be located on a 16 byte boundary.

-Paddress

specify the address where code segment of the following object files will be placed. If an object file specification is not preceded by -P option, code segment will be appended to the previous one. If no -P option specified before the first object file, its code segment will be placed to 0000.

-Daddress

specify where data segment of the following object files will be placed. If an object file specification is not preceded by -D option, data segment will be appended to the previous one. If no -D option specified before the first object file, its data segment will be appended after the last code segment.

-Cname,address

address is the address where common block name will be placed. If block name name is empty string or it begins with space it will be treated as blank common block. However no extra whitespace character around of comma (,) are allowed. Name is not case sensitive. Common blocks of unspecified location will be appended to the last data segment.

-Uname

Common block named name will be "uncommon". Normally common blocks of the same name are located on the same address. However blocks marked as uncommon will be concatenated like code or data segments. In this way you can spread your code/data over several region of physical memory. Name is case insensitive.

-llibrary

The following object file is a library. Mld80 will scan the library loading only modules that satisfies unresolved external references. If a new reference is encoutered to an already extracted module than the newer module will not loaded again. It is possible to specify the same library more than once in order to resolve backward references.

-c

Suppress data segments. The output file will contain just code and absolute segments only.

-Ooformat

Output format specification. Possible values of oformat are:

• • ihex: Intel hex. This is the default format.
  • bin: Raw binary, gaps filled with X'00'.
  • binff: Raw binary, gaps filled with X'ff'.

-Wwarns   

Request for warning messages. Possible value of warns is (only):

extchain: Warn if ambigous external reference found.

-ssymfile

Name of symbol file. `-' stands for the standard output.

-m

Generate map. A list of segment mapping will be placed into symbol file if it has been specified. Otherwise the segment list will printed on standard output.

-Ssymsize

Symbol table size. Use this option if the linker have to process more than 1024 symbols.

-V

Print version number and exit.

Mdz80 is a "smart" disassembler for the Z80 cpu. It has the abilty to trace input code to "guess" what kind of binary data it is, and so, to have a disassembly that correctly produce different output for data or code.

Disassembly is also controlled by a "control" file (autogenerated the first time) that lets you assign a "type" to variuous regions of code to produce highly readable code even from the first attempts of disassembly job.

Of the MZT toolset mdz80 is the most mature and heavily rewritten respect to original code.

Mdz80 is a fork of the D52 microcontroller disassembler from Jeffery L. Post.

The mdz80 disassembler allows the user to specify memory areas as code, binary data (8 or 16 bit), ascii text, address tables, or data that should be ignored (not disassembled). You may specify such areas in an ascii text file with the same name as the file to be disassembled, but with an extension of ctl (for example: program.ctl controls the disassembly of program.hex or program.bin).

With the use of a control file, you can, by an iterative process, get a progressively more meaningful disassembly by modifying the control file based on examination of the output of previous runs of the disassembler. You can also specify names for labels and symbols in the control file, resulting in a much more readable source file.

Labels and symbols may have as many characters as will fit in one line of the control file, but some cross assemblers (and especially cross linkers) will truncate any more than some fixed number of characters. Consult your cross development tool documentation. Labels and symbols are not case sensitive.

The control file may exist in either the current directory or the directory of the file to be disassembled. If it is in both directories, the control file in the current directory will take precedence. The output file will always be placed in the current directory.

The getting started section of this document gives some minimal information for users who are eager to try out the disassembler. For best use of the disassembler, however, you should read the sections on command line options and control file directives before proceeding.

Usage:

Usage: mdz80 [options]  [-o ] [-c ] [-e ]

File control options:
        -o use 'ofile' as output.
        -c use 'cfile' as control.
        -C disassemble CP/M .com file (implies -x100).
        -b force .bin format/extension on input file.
        -h force .hex format/extension on input file.
           If neither 'b', 'c', nor 'h' is specified, mdz80 will first search
           for a .hex file, then a .bin file and then the filename alone.
        -t trace and analyze code before disassembly.
        -e use asm source 'efile' to add/evaluate symbols
           (Altoghether with -t option will create/modify control file).

Disassembling options:
        -a use ascii macro instead of db/defb for text.
        -d include address and data in comment field.
        -n use C style for hexadecimal operands
        -f format hex values as '$xx' instead of xxH.
        -p put dot '.' at beginning of pseudo ops
        -s change 'defb' and 'defw' to 'db' and 'dw'.
        -l output labels, symbols, and mnemonics in lower case.
        -x [nnnn] add hexadecimal offset to program addresses.
        -8 generate 8080 mnemonics.
        -T during trace (-t) presume unidentified binary is code

General options:
        -v be verbose.
        -V print version and exit.

Options are case sensitive and may be entered in a freeform
fashion as long as a dash (-) preceeds any option (group).
Examples:
        mdz80 -bd filename
        mdz80 -d filename -b -o out_file

Getting Started

mdz80 is a command line disassembler. To disassemble a file called 'program.bin' or 'program.hex', type in (at the command line prompt):

A control file with the same name as the file to be disassembled, but with an extension of '.ctl' can be created in which you can specify areas of memory to be ascii text, 8-bit binary data, 16-bit binary data, etc. A control file is not necessary for disassembly, but as will be seen, it will provide for a much more complete disassembly. The -t option will cause mdz80 to trace and analyze the code before disassembly, and will create a preliminary control file.

If a file extension is not provided and neither the -b option nor the -h option is specified on the command line, the disassembler will first search for a hex file and, if it is not found, will then search for a bin file. The disassembler can be forced to look for only one or the other by specifying either the binary or the hex option on the command line:

If a file extension of '.hex' or '.bin' is provided in the filename (ie: mdz80 test.hex), that is equivalent to using the -h option or -b option.

mdz80 will produce a file named 'program.z80' containing the disassembly of the original hex or binary file. It is very useful on the first few disassemblies to use the -d option , which adds a comment field to every line. The comment field contains the hexadecimal address of each instruction, the hex data for each byte in the instruction, and the ascii code for each byte of the instruction.
Example:

This makes it easy to spot areas of ascii text or other nonexecutable code, and you can then modify the control file to tell the disassembler that these areas should be treated as some other kind of data on subsequent disassemblies.

By examining the output file and then modifying the control file based on the information obtained, you can get a progressively better disassembly of your program. Generally, about half a dozen iterations of the disassembly are enough to produce a very readable source file that can then be modified and reassembled.

Command Line Options

Options are case sensitive and may be entered in a freeform fashion as long as a dash (-) preceeds any option or group of options:

or

Command line options are: 

-a (ascii macro)

The A option tells the disassembler to change the db/defb pseudo op to the ascii macro (pseudo op 'ascii' instead of 'db' or 'defb') for areas defined as ascii text. This will cause the disassembler to include a macro definition in the disassembly output file that should expand to 'db' for the cross assembler. To use this option, your cross assembler must be able to handle macros, and in particular, mzmac's macro format. If used in conjunction with the -s option , the -s option must come first on the command line.

There are some caveats regarding the ascii macro. The intent of this macro is to make ascii text easier to find in the output file. Once you're satisfied with the readability of the output file, you may want to run the disassembler once more without the -a option to produce a file compatible with your cross assembler.

-8 (disassemble 8080 code)

Disassembles code using 8080 opcodes instead of Z80 opcodes (that is the default).

-b (read binary file)

The -b option forces the disassembler to read a binary file (extention '.bin') instead of an Intel hex file (extention .hex). If neither the -b option nor the -h option are specified, the disassembler will first search for a file with an extention of .hex, and if not found, will then search for a binary file with an extention of .bin. 

-c (control filename)

This option lets you specify a filename for the .ctl file to be used, instead of the default that is input filename postfixed with ".ctl".

-C (disassemble CP/M .com file)

Disassembles a CP/M .com executable file beginning at address 100H. Use of this option will cause mdz80 to look for a file with a .com extension, as opposed to a .bin or .hex extension. This option also sets the offset to 100H without the need to do so with the -x option.

-d (put data in comment field)

The -d option tells the disassembler to include a comment field in each disassembled line. The comment field will contain the hexadecimal address of each instruction, the hex data for each byte in the instruction, and the ascii code for each byte of the instruction.
Example:

This makes it easy to spot areas of ascii text or other nonexecutable code, and then modify the control file to tell the disassembler that these areas should be treated as some other kind of data on subsequent disassemblies. 

-e (evaluate symbols from asm source)

Use this option to feed mdz80 with an assembler source file the contains valid labels, equates and entry points in the context of what you are disassembling. In this way mdz80 will extract a list of symbols to be used in the current disassembly substituting symbols in list with the autogenerated ones.
Normally this is to be used in the very first runs of mdz80 in conjunction with -t option to trace code and generate an initial .ctl file that already contains valid labels. 

-f (use '$' prefixed operands)

Use this option to have the disassembler output hexadecimal operands using '$' prefix notation, ie: $cd instead of the default 0cdh.

-h (read hexadecimal file)

The -h option forces the disassembler to read an Intel hex file (extention '.hex') instead of a binary file (extention '.bin'). If neither the -b option nor the -h option are specified, the disassembler will first search for a file with an extention of '.hex', and if not found, will then search for a binary file with an extention of '.bin'. 

-l (lowercase case output)

Causes labels, symbols, mnemonics, etc to be output in lower case, for cross assemblers that may require lower case code. Comments, literal data values, strings, and other output are not affected by this option.

-n (use C type operands)

Use this option to have the disassembler output hexadecimal operands using C notation, ie: 0xcd instead of the default 0cdh. 

-o (output filename)

This option lets you specify the output filename, instead of the default that is input filename postfixed with ".z80".

-p (add dot in front of pseudo ops)

Some assemblers require pseudo operations to begin with a dot. Use this option to have the disassembler output ".equ" instead of "equ" and similar for org and other pseudo operations. 

-s (set string pseudo op)

This option tells the disassembler to generate the pseudo ops 'db' and 'dw' instead of 'defb' and 'defw' for those cross assemblers that may require this.Use this option for cross assemblers that do not recognize 'defb' and 'defw'. If used in conjunction with the -a option , the -s option must preceed the -a option on the command line.

-t (trace and analyze code)

This option tells mdz80 to trace and analyze the Z80 code before disassembling it. mdz80 will attempt to determine which parts of the code are actually code, and which parts are ascii text, binary data, pointers, etc. While it does a reasonably good job of analyzing the code on most files, no program can do as good a job as a human programmer. A control file with the same name as the hex or bin file, but with an extension of '.ctl', will be created before the actual disassembly is performed. You can then edit the control file to correct any erroneous directives, or to add new directives.

Warning: Using this option will overwrite any control file that may already exist for the code file being disassembled. It is intended to be used on the first disassembly only or until you combine disassembly options in the right way to have a good starting point.

-T (presume code during trace)

This option is meaningful only in conjunction with -t option during initial traces of the code. If you are disassembling very fragmented code or code that cannot clearly traced from the beginning (i.e. a library) this can easily confuse mdz80 produncing wrong output. -T option will instruct mdz80 to presume the all binary input that can't be exactly identified as code or data must be considered as code and in this way disassembled.

-v (be verbose)

Will inform you of the phases of disassembling.

-V (print version)

Will print mdz80 version and then exit.

-x (add hexadecimal offset to addresses)

This option causes the disassembler to add a hexadecimal offset to the address of every location in the code file. This may be useful for disassembling code that was read from the second (or subsequent) rom of a set of roms. For example, suppose that binary data was obtained from a set of 4K byte eproms (call them rom1 and rom2). Then the first file should be disassembled with the command line:

and the second should be disassembled with the -x option:

The two files then can be combined into one and all references within the disassembled code will be to the correct addresses.

If given on the command line, the -x option overrides any -o directive in the control file.

The control file

The control file gives you the way to assign the proper type to regions of code in disassembly that are not (eventually) correctly identified by mdz80 during trace.

See here how to use the control file.

•  Implements missing macro directives in mzmac (IRP, IRPC, REPT, EXITM)
• Add librarian functions to mld80
• Add the ability to link .PRL, .SPR files to mld80
• Add an option to mdz80 to recognize embedded print routines and disassemble embedded ascii text in the right way.

Suggestions or, even better, code enhancements are more then welcome...

Latest version (source format):

mzt-1.0.0.tar.bz2

Older versions:

- none -