home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / ENTERPRS / CPM / UTILS / F / MYZ80111.ZIP / MYZ80.DOC < prev    next >
Text File  |  1993-04-27  |  16KB  |  339 lines
  1.  
  2.  
  3.  
  4.                MicroFast Z80 Emulation Engine code,
  5.                             MYZ80 API,
  6.       and The MYZ80 Emulator Package Versions 1.xx are each:
  7.               Copyright 1991,1992,1993 Simeon Cran.
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                             M Y Z 8 0
  14.                             =========
  15.  
  16.                          by Simeon Cran.
  17.  
  18. Welcome to MYZ80!
  19. ~~~~~~~~~~~~~~~~~
  20. MYZ80 is a Z80/64180 emulator package. It was written to allow you 
  21. to finally get rid of those old Z80 computers which  have done  so 
  22. many fine years of service.  The new 80486, 80386 & 80286 machines 
  23. with the fast hard drives and  the snazzy  OS/2 operating  systems 
  24. are such a delight... but for many, the Z80 machines still have to 
  25. be fired up from to time in order to develop code for CP/M and the 
  26. Z80 chip. Well, not any more, thanks to MYZ80.
  27.  
  28. Other  emulators  on  the  market  are   less  than   satisfactory 
  29. solutions.  Of  the small  number which  can actually  run without 
  30. causing system errors under the later versions of  DOS, apparently 
  31. none is capable of running real CP/M. Instead they use an emulated 
  32. version of CP/M which is only as accurate  as the  developers have 
  33. bothered to make it.
  34.  
  35. None can run CP/M  3.0, and  none can  run ZCPR  (which is  such a 
  36. useful Z80 developer's environment).  Add to that their  less than 
  37. perfect  Z80  emulation and  slow overall  performance, and  until 
  38. MYZ80, the  'real' Z80  machines were  destined to  remain in  the 
  39. office.
  40.  
  41. MYZ80 provides the solution being conceived, born and  nurtured to 
  42. the point where it  is now  the most  useful Z80  emulator package 
  43. ever!
  44.  
  45.  
  46. MYZ80 features.
  47. ~~~~~~~~~~~~~~~
  48. MYZ80 emulates the instruction set of the 8080, Z80 and Z180/64180 
  49. CPU chips. It does this with the "MicroFast Z80 Emulation  Engine" 
  50. which is a very highly tuned piece of code designed to be  as fast 
  51. and as accurate as technically possible on 80286, 80386 and  80486 
  52. CPUs.
  53.  
  54. MYZ80 provides an interface (the MYZ80 API) to  the host  computer 
  55. which allows real Z80 BDOSes to run in the MYZ80 environment. This 
  56. interface provides disk and character I/O as well as two  banks of 
  57. 64k RAM (with common  area) and  a large  RAM disk.   These unique 
  58. features allow MYZ80 to run 'real'  CP/M 2.2,  CP/M 3.0,  Z-System 
  59. and ZPM3.
  60.  
  61. MYZ80  is  designed  for  the  latest  host computer  multitasking 
  62. operating systems and makes Z80 programs  'host friendly'.   MYZ80 
  63. will  share  time  very  fairly  with  the  host.   Even  multiple 
  64. instances of MYZ80 are supported.
  65.  
  66. MYZ80  can  take  advantage  of the  latest computer  hardware for 
  67. increased performance. The Microfast Z80 Emulation Engine operates 
  68. in either 16 (80286) or 32 (80386/80486/P5) bit mode depending  on 
  69. the capabilities of the host computer.
  70.  
  71. MYZ80 runs beautifully on IBM AT compatible (or  better) computers 
  72. under  DOS  3.3  compatible  (or later)  operating systems.   This 
  73. includes running under OS/2 2.x, Desqview, and Windows 3.x.
  74.  
  75.  
  76. Installing MYZ80.
  77. ~~~~~~~~~~~~~~~~~
  78. To install MYZ80 onto your computer, all you need do is place  all 
  79. the MYZ80 files in the one subdirectory on your hard  disk (it  is 
  80. recommended that you make  a subdirectory  especially for  MYZ80). 
  81. You can also run  MYZ80 from  a floppy  disk if  required, however 
  82. this severely limits the amount of space available for CP/M  files 
  83. (and reduces the performance of the program).
  84.  
  85.  
  86. Starting MYZ80.
  87. ~~~~~~~~~~~~~~~
  88. MYZ80 is started from the DOS  command line  by simply  typing the 
  89. name of its executable (CPM). When you first start MYZ80  you will 
  90. be shown some text which explains the basic concepts of  the MYZ80 
  91. environment. Try it now and read the text. The experience you gain 
  92. will help you understand the more advanced topics below.
  93.  
  94.  
  95. Leaving MYZ80.
  96. ~~~~~~~~~~~~~~
  97. There are two ways to exit  from the  MYZ80 environment.   You may 
  98. select the 'Abort and exit' choice from the pause box menu, or you 
  99. may run the MYZ80 utility QUIT.COM. The latter method also  allows 
  100. you to specify an error level with which to return to DOS (for use 
  101. in batch files).
  102.  
  103.  
  104. Further information.
  105. ~~~~~~~~~~~~~~~~~~~~
  106. Some explanations of the terms used above and  further information 
  107. will be displayed to you when you start MYZ80 for the first  time. 
  108. Advanced users will find  important information  in the  "Advanced 
  109. Topics" section which follows.  Legal information  is provided  in 
  110. the file READ.1ST which was supplied with this  package.  All  the 
  111. MYZ80 utilities have online  help. Other  support files  for MYZ80 
  112. should be provided in the future  and will  probably be  available 
  113. from the place where you found this package.
  114.  
  115.  
  116.  
  117. Advanced Topics.
  118. ~~~~~~~~~~~~~~~~
  119. The following information presumes  that you  have already  gained 
  120. some experience with the MYZ80 package.  It is  meant to  help you 
  121. use some of the many more  advanced facilities  that MYZ80  has to 
  122. offer.
  123.  
  124. MYZ80 API.
  125. The  API  is  what  enables  Z80  programs  running  on  MYZ80  to 
  126. communicate  with  facilities  on  the host  computer.  The  MYZ80 
  127. utilities are the prime users of the API however you  may use  the 
  128. API functions in programs that you write. The  file "MYZ80API.TXT" 
  129. is provided with the package (in user area 1 on  the A:  disk) and 
  130. contains  all  the  necessary  specifications  you   should  need.  
  131. Further information is provided in that document.
  132.  
  133. KEYBOARD REDEFINITION.
  134. MYZ80 includes  one the  most comprehensive  keyboard redefinition 
  135. systems you're likely to find. Almost  every key  on the  keyboard 
  136. can be redefined to output strings of up to 127 characters to your 
  137. Z80 programs.  In addition, the definitions  for the  keyboard may 
  138. be saved in a file and reloaded at a later time. To set or  change 
  139. the definition of a key, hold down the CONTROL Key  and the  SHIFT 
  140. Key and press the BREAK Key. This will bring up a menu.  Note that 
  141. keys can be defined on two "levels".  The "transient" level is the 
  142. one you will normally use. The "default" level  exists to  provide 
  143. the keys with definitions when the "transient" level is completely 
  144. cleared out. When a key is pressed, MYZ80 first checks  to see  if 
  145. it has a "transient" level definition, and if it does,  it outputs 
  146. that. If it doesn't, it checks to see if there it has  a "default" 
  147. level definition, and if it does,  it outputs  that. If  neither a 
  148. "transient"  level  nor  a  "default" level  definition is  found, 
  149. nothing is output (the  key is  ignored). The  KEY.COM utility  is 
  150. used to save and load definitions from files.  Run KEY.COM  to see 
  151. instructions on how to use it.
  152.  
  153. DISK FILES IN DIFFERENT DIRECTORIES.
  154. As you may have  already discovered,  by default  MYZ80 uses  disk 
  155. files called A.DSK, B.DSK and C.DSK which are located in  the same 
  156. directory as the CPM.EXE file. However it is  possible to  specify 
  157. different names for these  disk files,  and even  to specify  disk 
  158. files  in  different directories  or on  different disks  by using 
  159. "aliases" for the disk files .  This is all done using the DOS SET 
  160. command. Before starting MYZ80, use the SET command  to specify  a 
  161. new name for any of the disk files in the following way:
  162. SET A.DSK=D:\TESTING\DISKFILE.TST
  163. The above command would mean that  MYZ80 would  use a  file called 
  164. DISKFILE.TST which  resided in  the \TESTING  directory of  the D: 
  165. disk. Note that if the file didn't exist it would  be created  (if 
  166. possible). The same system can be  used for  B.DSK and  C.DSK. The 
  167. disk file definitions will remain until you reboot DOS.  To  clear 
  168. the definition use the command:
  169. SET A.DSK=
  170.  
  171. DIFFERENT BOOT FILES.
  172. By default,  MYZ80 uses  the Boot  File called  BOOT.CPM which  is 
  173. located in the same directory as the CPM.EXE file. You may specify 
  174. a different boot file  so that  MYZ80 starts  up with  a different 
  175. CP/M system.  To do this use the keyword "MYZ80BOOT" with the  DOS 
  176. SET command in the following way:
  177. SET MYZ80BOOT=C:\TEST\OTHER.STM
  178. The above command would  cause MYZ80  to boot  from the  Boot File 
  179. C:\TEST\OTHER.STM. Note that you can also specify a boot file name 
  180. from within  the  MYZ80  environment   using  the   MYZ80  utility 
  181. COLDBOOT.COM.
  182.  
  183. TERMINAL EMULATIONS.
  184. CP/M programs of any complexity have  always required  customising 
  185. to suit different terminals.  MYZ80 provides a terminal  emulation 
  186. which  is  closely  based  on  the  most  common  of the  powerful 
  187. terminals used for CP/M: the ADM3A/Televideo 912/Morrow MT70/ANSI.  
  188. If you have software which can not be customised appropriately for 
  189. this terminal you may be able to use one of the alternative MYZ80 
  190. terminal emulations.  TERM.TXT (in  user area  1 on  the A:  disk) 
  191. describes these alternative terminals.   Normally MYZ80  starts up 
  192. running the standard MYZ80 terminal, however  you may  change this 
  193. by using the DOS  SET command  with the  keyword "MYZ80TERM".  For 
  194. example:
  195. SET MYZ80TERM=VT52
  196. will set the default terminal to the VT52 emulation. You can still 
  197. change  this  during the  session with  the TERMINAL.COM  utility, 
  198. however  on  cold  boot  the  default   terminal  (from   the  DOS 
  199. environment) is always returned and reset.
  200.  
  201. COLOURS
  202. CP/M is a monochrome  system. There  is no  allowance for  colour. 
  203. However  many  of the  larger CP/M  programs do  allow control  of 
  204. terminal  "attributes".   These attributes  make the  text on  the 
  205. screen bright or dim or reversed or underlined.  MYZ80 understands 
  206. these attributes but takes the concept  one step  further to  give 
  207. you  CP/M  computing  in  glorious  colour.   Each  attribute  and 
  208. attribute  combination  can  be  assigned  a   colour  using   the 
  209. COLOUR.COM utility.  COLOUR.COM is  easy to  use, self-explanatory 
  210. and allows you to save and load colour preferences from  files. To 
  211. complement this system, when first started up, MYZ80 will look for 
  212. the file MYZ80.CLR in the same DOS directory as the  CPM.EXE file.  
  213. This file should be one produced by COLOUR.COM and it will provide 
  214. the start-up colours for the MYZ80 environment.
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222. GLOSSARY  -  Some terms explained.
  223. ~~~~~~~~
  224.  
  225. CP/M
  226. The operating system used by most  8080 and  Z80 based  computers.  
  227. CP/M provides a fixed set of rules and services that  programs can 
  228. take advantage of.  CP/M is to 8 bit computers what  DOS is  to 16 
  229. bit computers. Two versions of CP/M became very  popular: 2.2  and 
  230. 3.0.  After market (improved but compatible) versions of  CP/M are 
  231. also available (e.g. ZPM3).
  232.  
  233. CPU
  234. Central Processing  Unit. In  a CP/M  computer the  CPU is  a Z80, 
  235. 8080, 8085, 64180, Z180 or Z280 integrated circuit. The CPU is the 
  236. central brain of the computer. MYZ80 emulates the Z80 CPU as  well 
  237. as the instruction set of the 64180 and Z180 CPU.
  238.  
  239. DISK FILE
  240. CP/M stores data on disks.  In  order to  satisfy CP/M's  need for 
  241. particular  disk  formats,  MYZ80  emulates  the  real  CP/M  disk 
  242. structure and stores the resultant data on your DOS disk. The data 
  243. for each emulated CP/M disk is held in  a DISK  FILE. Usually  the 
  244. disk files  are  called A.DSK,  B.DSK and  C.DSK, however  you may 
  245. change the default names of the disk files with a  setting in  the 
  246. DOS enironment block.
  247.  
  248. EMULATION
  249. MYZ80 emulates a real CP/M computer. This means that it  acts like 
  250. it in a way which is hardly distinguishable  from the  real thing. 
  251. In order to emulate a CP/M computer, MYZ80 also emulates  a number 
  252. of sub-systems that are typically found  in a  CP/M computer,  for 
  253. example the CPU, the terminal and the disk system.  This emulation 
  254. of sub-systems is one of  the things  that sets  MYZ80 apart  from 
  255. other CP/M emulators and makes MYZ80 the most compatible emulation 
  256. of a CP/M computer.
  257.  
  258. SHRINKING
  259. Because the MYZ80 virtual disks are able to hold over  8 megabytes 
  260. of data, and because CP/M expects to be able to access all of that 
  261. data at any time, disk files would normally have to be at  least 8 
  262. megabytes in size all the time.  This would take up a lot  of your 
  263. hard disk space and  would be  extremely wasteful  when your  disk 
  264. files don't hold much useful data.  MYZ80 solves  this problem  by 
  265. only storing useful data and returning dummy blank sectors to CP/M 
  266. in return for any requests for data from unused parts of the disk. 
  267. As you add more data to your MYZ80 disk files  you will  find that 
  268. they grow, however when you delete files from the MYZ80 disk files 
  269. they will not shrink automatically. This is a feature, not  a bug! 
  270. You can shrink disk files that have had data removed from them  so 
  271. that MYZ80 will return the dummy blank sectors for the  previously 
  272. used sectors  using the  SHRINK.COM utility.   Note well  however, 
  273. that disk files can only be shrunk down  to the  highest block  of 
  274. data in use on the disk.  SHRINK.COM will tell you which file owns 
  275. the highest block of data so that you can delete that file or move 
  276. it  in  order  to  allow  further  shrinking  of  the  disk  file.  
  277. SHRINKING does  not "pack"  your disk  files, it  simply frees  up 
  278. previously  allocated  blocks  that  are  no  longer  being  used.  
  279. SHRINKING is  not necessary,  except to  save space  on your  hard 
  280. disk.
  281.  
  282. TERMINAL
  283. Most CP/M computers consist of at least two  boxes: the  computer, 
  284. and the  terminal.  The  computer does  the work  required by  the 
  285. program,  and  the  terminal  displays  the  result. The  terminal 
  286. typically contains a small computer of its own in order to display 
  287. the results in a pleasing way.  Many different  types of  terminal 
  288. have been produced, and each different design requires a different 
  289. type of communication with CP/M programs.  CP/M programs  which do 
  290. anything clever with the screen must  therefore be  "installed" to 
  291. suit the terminal in use.  MYZ80  has built-in  emulation of  most 
  292. common  terminals.   You  therefore  have  the  choice  to  either 
  293. "install" your  programs, or  to tell  MYZ80 to  emulate terminals 
  294. which are already suitable for each program.  TERMINAL.COM  is the 
  295. utility which makes this possible.
  296.  
  297. ZCPR
  298. An advanced software system for CP/M computers. MYZ80  is able  to 
  299. run ZCPR in its many forms. ZCPR gives UNIX-like features  to CP/M 
  300. and is a favourite with most serious CP/M hobbyists.
  301.  
  302. ZPM3
  303. An after market replacement for CP/M version 3.0. ZPM3 is  written 
  304. to take advantage of  the Z80  CPU and  offers compatibility  with 
  305. CP/M 3.0, but with extra features and improved  performance. MYZ80 
  306. is able to run ZPM3.
  307.  
  308.  
  309.  
  310.  
  311.  
  312. Package Footnote.
  313. ~~~~~~~~~~~~~~~~~
  314. The version of MYZ80 that you have now may not be perfect,  but it 
  315. is pretty close! It has been released so  that as  many people  as 
  316. possible can  join the  MYZ80 revolution,  and keep  CP/M and  Z80 
  317. alive for years to come. Please enjoy it.
  318.  
  319.  
  320.                            Simeon Cran.
  321.             (Author and designer of the MYZ80 package)
  322.  
  323.  
  324.  
  325.          
  326.        
  327.   *************************************************************
  328.   Acknowledgments:
  329.   Due to all the great help,  I feel  compelled to  acknowledge 
  330.   the support given by a number of people in the "Z" community. 
  331.   Especially Bruce Dudley (Sysop of Z-Node 62 in Perth, Western 
  332.   Australia), and the handful of crash testers in Australia and 
  333.   around  the  world.   And  to  all  those  people  who  truly 
  334.   appreciate  the  elegance  of   the  art   of  machine   code 
  335.   optimization, please enjoy "MYZ80 by Simeon Cran."
  336.   *************************************************************
  337.  
  338.         MYZ80 - Virtual Z80 Reality for today's computers.
  339.