MyZ80 by Simeon Cran

               MicroFast Z80 Emulation Engine code,
                            MYZ80 API,
      and The MYZ80 Emulator Package Versions 1.xx are each:
                Copyright 1991 - 1998 Simeon Cran.





                            M Y Z 8 0
                            =========

                         by Simeon Cran.

Welcome to MYZ80!
~~~~~~~~~~~~~~~~~
MYZ80 is a Z80/64180 emulator package. It was written to allow you 
to finally get rid of those old Z80 computers which  have done  so 
many fine years of service.  The new Pentium, 80486, 80386 & 80286 
machines with the fast hard drives and the  snazzy OS/2  operating 
systems are such a delight... but for many, the Z80 machines still 
have to be fired up from to time in order to develop code for CP/M 
and the Z80 chip. Well, not any more, thanks to MYZ80.

Other  emulators  on  the  market  are   less  than   satisfactory 
solutions.  Of  the small  number which  can actually  run without 
causing system errors under the later versions of  DOS, apparently 
none is capable of running real CP/M. Instead they use an emulated 
version of CP/M which is only as accurate  as the  developers have 
bothered to make it.

None can run CP/M  3.0, and  none can  run ZCPR  (which is  such a 
useful Z80 developer's environment).  Add to that their  less than 
perfect  Z80  emulation and  slow overall  performance, and  until 
MYZ80, the  'real' Z80  machines were  destined to  remain in  the 
office.

MYZ80 provides the solution, being conceived, born and nurtured to 
the point where it  is now  the most  useful Z80  emulator package 
ever!


MYZ80 features.
~~~~~~~~~~~~~~~
MYZ80 emulates the instruction set of the 8080, Z80 and Z180/64180 
CPU chips. It does this with the "MicroFast Z80 Emulation  Engine" 
which is a very highly tuned piece of code designed to be  as fast 
and as accurate as technically possible on 80286, 80386, 80486 and
Pentium CPUs.

MYZ80 provides an interface (the MYZ80 API) to  the host  computer 
which allows real Z80 BDOSes to run in the MYZ80 environment. This 
interface provides disk and character I/O as well as two  banks of 
64k RAM (with common  area) and  a large  RAM disk.   These unique 
features allow MYZ80 to run 'real'  CP/M 2.2,  CP/M 3.0,  Z-System 
and ZPM3.

MYZ80  is  designed  for  the  latest  host computer  multitasking 
operating systems and makes Z80 programs  'host friendly'.   MYZ80 
will  share  time  very  fairly  with  the  host.   Even  multiple 
instances of MYZ80 are supported.

MYZ80  can  take  advantage  of the  latest computer  hardware for 
increased performance. The Microfast Z80 Emulation Engine operates 
in either 16 (80286) or 32 (80386/80486/P5) bit mode depending  on 
the capabilities of the host computer.

MYZ80 runs beautifully on IBM AT compatible (or  better) computers 
under  DOS  3.3  compatible  (or later)  operating systems.   This 
includes running under OS/2 2.x, Desqview, and Windows 3.x.


Installing MYZ80.
~~~~~~~~~~~~~~~~~
To install MYZ80 onto your computer, all you need do is place  all 
the MYZ80 files in the one subdirectory on your hard  disk (it  is 
recommended that you make  a subdirectory  especially for  MYZ80). 
You can also run  MYZ80 from  a floppy  disk if  required, however 
this severely limits the amount of space available for CP/M  files 
(and reduces the performance of the program).


Starting MYZ80.
~~~~~~~~~~~~~~~
MYZ80 is started from the DOS  command line  by simply  typing the 
name of its executable  (MYZ80). When  you first  start MYZ80  you 
will be shown some text which explains the  basic concepts  of the 
MYZ80 environment. Try it now and  read the  text. The  experience 
you gain will help you understand the more advanced topics below.


Leaving MYZ80.
~~~~~~~~~~~~~~
There are two ways to exit  from the  MYZ80 environment.   You may 
select the 'Abort and exit' choice from the pause box menu, or you 
may run the MYZ80 utility EXIT.COM. The latter method also  allows 
you to specify an error level with which to return to DOS (for use 
in batch files).


Further information.
~~~~~~~~~~~~~~~~~~~~
Some explanations of the terms used above and  further information 
will be displayed to you when you start MYZ80 for the first  time. 
Advanced users will find  important information  in the  "Advanced 
Topics" section which follows.  Legal information  is provided  in 
the file READ.1ST which was supplied with this  package.  All  the 
MYZ80 utilities have online  help. Other  support files  for MYZ80 
should be provided in the future  and will  probably be  available 
from the place where you found this package.


==================================================================


Advanced Topics.
~~~~~~~~~~~~~~~~
The following information presumes  that you  have already  gained 
some experience with the MYZ80 package.  It is  meant to  help you 
use some of the many more  advanced facilities  that MYZ80  has to 
offer.

MYZ80 API.
The  API  is  what  enables  Z80  programs  running  on  MYZ80  to 
communicate  with  facilities  on  the host  computer.  The  MYZ80 
utilities and the CP/M BIOS are the prime users of the API however
you may use the API functions in programs that you write. The file
"MYZ80API.TXT" is provided with the package (in user area 1 on the
A:  disk)  and  contains  all  the  necessary  specifications  you
should  need. Further information is provided in that document.

KEYBOARD REDEFINITION.
MYZ80 includes  one the  most comprehensive  keyboard redefinition 
systems you're likely to find. Almost  every key  on the  keyboard 
can be redefined to output strings of up to 127 characters to your 
Z80 programs.  In addition, the definitions  for the  keyboard may 
be saved in a file and reloaded at a later time. To set or  change 
the definition of a key, hold down the CONTROL Key  and the  SHIFT 
Key and press the BREAK Key. This will bring up a menu.  Note that 
keys can be defined on two "levels".  The "transient" level is the 
one you will normally use. The "default" level  exists to  provide 
the keys with definitions when the "transient" level is completely 
cleared out. When a key is pressed, MYZ80 first checks  to see  if 
it has a "transient" level definition, and if it does,  it outputs 
that. If it doesn't, it checks to see if there it has  a "default" 
level definition, and if it does,  it outputs  that. If  neither a 
"transient"  level  nor  a  "default" level  definition is  found, 
nothing is output (the  key is  ignored). The  KEY.COM utility  is 
used to save and load definitions from files.  Run KEY.COM  to see 
instructions on how to use it. When MyZ80 is started, if it  finds 
the file MYZ80.KEY in  the same  directory as  MYZ80.EXE, it  will 
load it and use the definitions in it.

DISK FILES IN DIFFERENT DIRECTORIES.
As you may have  already discovered,  by default  MYZ80 uses  disk 
files called A.DSK, B.DSK and C.DSK which are located in  the same 
directory as the MYZ80.EXE file. However it is possible to specify 
different names for these  disk files,  and even  to specify  disk 
files  in  different directories  or on  different disks  by using 
"aliases" for the disk files .  This is all done using the DOS SET 
command. Before starting MYZ80, use the SET command  to specify  a 
new name for any of the disk files in the following way:
SET A.DSK=D:\TESTING\DISKFILE.TST
The above command would mean that  MYZ80 would  use a  file called 
DISKFILE.TST which  resided in  the \TESTING  directory of  the D: 
disk. Note that if the file didn't exist it would  be created  (if 
possible). The same system can be  used for  B.DSK and  C.DSK. The 
disk file definitions will remain until you reboot DOS.  To  clear 
the definition use the command:
SET A.DSK=
Once MyZ80 is running, you can change the disk files it uses  with 
the CHGDSK.COM utility.

DIFFERENT BOOT FILES.
By default, MYZ80  uses the  Boot File  called MYZ80.SYS  which is 
located  in  the same  directory as  the MYZ80.EXE  file. You  may 
specify  a  different boot  file so  that MYZ80  starts up  with a 
different CP/M  system.  To  do this  use the  keyword "MYZ80BOOT" 
with the DOS SET command in the following way:
SET MYZ80BOOT=C:\TEST\OTHER.STM
The above command would  cause MYZ80  to boot  from the  Boot File 
C:\TEST\OTHER.STM. Note that you can also specify a boot file name 
once MyZ80 is running by using the MYZ80 utility COLDBOOT.COM.

TERMINAL EMULATIONS.
CP/M programs of any complexity have  always required  customising 
to suit different terminals.  MYZ80 provides a terminal  emulation 
which  is  closely  based  on  the  most  common  of the  powerful 
terminals used for CP/M: the ADM3A/Televideo 912/Morrow MT70/ANSI.  
If you have software which can not be customised appropriately for 
this terminal you may be able to use one of the alternative MYZ80 
terminal emulations.  TERM.TXT (in  user area  1 on  the A:  disk) 
describes these alternative terminals.   Normally MYZ80  starts up 
running the standard MYZ80 terminal, however  you may  change this 
by using the DOS  SET command  with the  keyword "MYZ80TERM".  For 
example:
SET MYZ80TERM=VT52
will set the default terminal to the VT52 emulation. You can still 
change  this  during the  session with  the TERMINAL.COM  utility, 
however  on  cold  boot  the  default   terminal  (from   the  DOS 
environment) is always returned and reset.

COLOURS
CP/M is a monochrome  system: there  is no  allowance for  colour. 
However  many  of the  larger CP/M  programs do  allow control  of 
terminal  "attributes".   These attributes  make the  text on  the 
screen bright or dim or reversed or underlined.  MYZ80 understands 
these attributes but takes the concept  one step  further to  give 
you  CP/M  computing  in  glorious  colour.   Each  attribute  and 
attribute  combination  can  be  assigned  a   colour  using   the 
COLOUR.COM utility.  COLOUR.COM is  easy to  use, self-explanatory 
and allows you to save and load colour preferences from  files. To 
complement this system, when first started up, MYZ80 will look for 
the file  MYZ80.CLR in  the same  DOS directory  as the  MYZ80.EXE 
file.  This file should be one produced by COLOUR.COM and  it will 
provide the start-up colours for the MYZ80 environment.







GLOSSARY  -  Some terms explained.
~~~~~~~~

CP/M
The operating system used by most  8080 and  Z80 based  computers.  
CP/M provides a fixed set of rules and services that  programs can 
take advantage of.  CP/M is to 8 bit computers what  DOS is  to 16 
and 32 bit  computers. Two versions  of CP/M became very  popular:
2.2  and 3.0.  After market (improved but compatible)  versions of
CP/M are also available (e.g. ZPM3).

CPU
Central Processing  Unit. In  a CP/M  computer the  CPU is  a Z80, 
8080, 8085, 64180, Z180 or Z280 integrated circuit. The CPU is the 
central brain of the computer. MYZ80 emulates the Z80 CPU as  well 
as the instruction set of the 64180 and Z180 CPU.

DISK FILE
CP/M stores data on disks.  In  order to  satisfy CP/M's  need for 
particular  disk  formats,  MYZ80  emulates  the  real  CP/M  disk 
structure and stores the resultant data on your DOS disk. The data 
for each emulated CP/M disk is held in  a DISK  FILE. Usually  the 
disk files  are  called A.DSK,  B.DSK and  C.DSK, however  you may 
change the default names of the disk files with a  setting in  the 
DOS environment block or by using the MyZ80 CHGDSK.COM utility.

EMULATION
MYZ80 emulates a real CP/M computer. This means that it  acts like 
it in a way which is hardly distinguishable  from the  real thing. 
In order to emulate a CP/M computer, MYZ80 also emulates  a number 
of sub-systems that are typically found  in a  CP/M computer,  for 
example the CPU, the terminal and the disk system.  This emulation 
of sub-systems is one of  the things  that sets  MYZ80 apart  from 
other CP/M emulators and makes MYZ80 the most compatible emulation 
of a CP/M computer.

SHRINKING
Because the MYZ80 virtual disks are able to hold over  8 megabytes 
of data, and because CP/M expects to be able to access all of that 
data at any time, disk files would normally have to be at  least 8 
megabytes in size all the time.  This would take up a lot  of your 
hard disk space and  would be  extremely wasteful  when your  disk 
files don't hold much useful data.  MYZ80 solves  this problem  by 
only storing useful data and returning dummy blank sectors to CP/M 
in return for any requests for data from unused parts of the disk. 
As you add more data to your MYZ80 disk files  you will  find that 
they grow, however when you delete files from the MYZ80 disk files 
they will not shrink automatically. This is a feature, not  a bug! 
You can shrink disk files that have had data removed from them  so 
that MYZ80 will return the dummy blank sectors for the  previously 
used sectors  using the  SHRINK.COM utility.   Note well  however, 
that disk files can only be shrunk down  to the  highest block  of 
data in use on the disk.  SHRINK.COM will tell you which file owns 
the highest block of data so that you can delete that file or move 
it  in  order  to  allow  further  shrinking  of  the  disk  file.  
SHRINKING does  not "pack"  your disk  files, it  simply frees  up 
previously  allocated  blocks  that  are  no  longer  being  used.  
SHRINKING is  not necessary,  except to  save space  on your  hard 
disk.  It is purposely not done automatically.  This allows erased
CP/M files  to be recovered and  operating systems other than CP/M
to have unfettered access to every sector.

TERMINAL
Most CP/M computers consist of at least two  boxes: the  computer, 
and the  terminal.  The  computer does  the work  required by  the 
program,  and  the  terminal  displays  the  result. The  terminal 
typically contains a small computer of its own in order to display 
the results in a pleasing way.  Many different  types of  terminal 
have been produced, and each different design requires a different 
type of communication with CP/M programs.  CP/M programs  which do 
anything clever with the screen must  therefore be  "installed" to 
suit the terminal in use.  MYZ80  has built-in  emulation of  most 
common  terminals.   You  therefore  have  the  choice  to  either 
"install" your  programs, or  to tell  MYZ80 to  emulate terminals 
which are already suitable for each program.  TERMINAL.COM  is the 
utility which makes this possible.

ZCPR
An advanced software system for CP/M computers. MYZ80  is able  to 
run ZCPR in its many forms. ZCPR gives UNIX-like features  to CP/M 
and is a favourite with most serious CP/M hobbyists.

ZPM3
An after market replacement for CP/M version 3.0. ZPM3 is  written 
to take advantage of  the Z80  CPU and  offers compatibility  with 
CP/M 3.0, but with extra features and improved  performance. MYZ80 
is able to run ZPM3.





Package Footnote.
~~~~~~~~~~~~~~~~~
The version of MYZ80 that you have now may not be perfect,  but it 
is pretty close! It has been released so  that as  many people  as 
possible can  join the  MYZ80 revolution,  and keep  CP/M and  Z80 
alive for years to come. Please enjoy it.


                           Simeon Cran.
            (Author and designer of the MYZ80 package)



         
       
  *************************************************************
  Acknowledgments:
  Due to all the great help, I feel compelled to acknowledge the 
  support given  by a  number of  people in  the "Z"  community. 
  Especially Bruce Dudley, Howard Goldstein, and the handful  of 
  crash testers in Australia and around the world.   And to  all 
  those people who truly appreciate the elegance of  the art  of 
  machine  code  optimization,  please  enjoy  "MYZ80  by Simeon 
  Cran."
  *************************************************************

        MYZ80 - Virtual Z80 Reality for today's computers.