home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / emulate / simcpm.lha / simcpm.doc < prev    next >
Text File  |  1989-04-25  |  11KB  |  233 lines
  1.                SimCPM - a CP/M simulator for the Amiga
  2.  
  3.                    by Jim Cathey and Charlie Gibbs
  4.              incorporating modifications by Willi Kusche
  5.  
  6.                     Version 2.3 - January 9, 1989
  7.  
  8.  
  9.      This is a FREELY-DISTRIBUTABLE program.  Spread it around all
  10. you like, just don't sell it, and please keep the entire package
  11. (including this file) intact.  If you find any bugs or make any
  12. changes, please let me know - I'd like to keep my copy up to date.
  13.  
  14.      This program is based on an article by Jim Cathey which ran in
  15. Dr. Dobb's Journal from January to March 1986.  The original program
  16. emulated an 8080, including CP/M BIOS and BDOS calls, on a CP/M-68K
  17. system.  I have modified the operating system interface to run under
  18. AmigaDOS (from the CLI only, which shouldn't bother most CP/M-ers :-).
  19.  
  20.      Willi Kusche maintains that the proper term is "emulator", rather
  21. than "simulator."  Although I agree, the original article called it a
  22. simulator, and the name seems to have stuck.
  23.  
  24.      *** NEW FOR VERSION 2.0 ***  Due to popular demand, I have added
  25. support for the entire Z-80 instruction set (including undocumented
  26. opcodes).
  27.  
  28.      WARNING!  This program uses the MOVE from SR instruction to set up
  29. the simulated Z-80 flags.  Therefore, it will not run on the 68010 or
  30. higher processors.  I didn't want to use the Exec's GetCC() call because
  31. it would be too slow.  As a work-around I have set up a EQUate in
  32. options.i which you can change to indicate that you are running on a
  33. 68010, 68020, etc.  Re-assembling with x680x0 equated to 1 will cause
  34. all MOVE from SR instructions to be replaced by the corresponding MOVE
  35. from CCR instructions (actually faked with a DC.W in case your assembler
  36. doesn't support 68010 opcodes).  I have assembled a version with this
  37. flag set, and included it in the package; it is named SimCPM010.
  38. It should be possible to check whether x680x0 is equated to 2 and
  39. generate code optimized for a 68020 (as if it wouldn't be fast enough
  40. as is :-).
  41.  
  42.      SimCPM only looks at the first 12 bytes of the FCB (drive code,
  43. file name, and file type) when opening a file.  The remainder of the
  44. FCB is neither altered nor checked, except for BDOS calls 17 (search
  45. for first file) and 18 (search for next file), which insert extent size
  46. and count information only.
  47.  
  48.      If a reference is made to any drive other than A:, SimCPM will
  49. insert the string CPMx: ahead of any file name it uses.  For instance,
  50. if a program tries to open MYFILE.DAT on drive B:, SimCPM will try to
  51. open CPMB:MYFILE.DAT.  You can ASSIGN these simulated drives anywhere
  52. you want.  Drive A: will always go to the current directory, unless the
  53. user number is not zero.  If you specify any user number other than
  54. zero, it will be included, e.g. if the above example were opened under
  55. user 1, SimCPM will look for CPMB01:MYFILE.DAT.  If the file were on
  56. drive A under user 1, SimCPM will look for CPMA01:MYFILE.DAT.
  57.  
  58.      The only built-in commands supported are USER and SAVE.  All
  59. others, such as DIR or TYPE, can easily be done using AmigaDOS
  60. equivalents.  You might want to RUN SimCPM so that the original
  61. CLI window will be available for this.
  62.  
  63.      The EI and DI instructions are currently ignored.
  64.  
  65.      The IN and OUT instructions are ignored except for ports 14 and
  66. 15.  Access to the Amiga's serial port is provided through a simulated
  67. Intel 8251 USART, which is currently set up to run at 1200 bps.  Data
  68. is read from or written to port 14, and status input is simulated on
  69. port 15.  All output to port 15 (command) is ignored.  Note that CPU
  70. overhead may not permit an effective throughput of 1200 bps.  (Yup,
  71. you guessed it, it emulates the modem port on my old IMSAI.)
  72.  
  73.      The following BDOS calls are not supported:
  74.  
  75.           3 - reader input
  76.           4 - punch output
  77.          30 - set file attributes
  78.          all above 36
  79.  
  80.      The only BIOS calls supported are those for program termination
  81. and console and list I/O.  (Low-level disk access could get scary.)
  82. If a program attempts to use an unsupported BIOS or BDOS call, an
  83. appropriate error message will be displayed, along with a register dump,
  84. and the program will be terminated.
  85.  
  86.      Basic H19 terminal emulation (similar to a VT52) has been
  87. provided.  Escape sequences for cursor positioning, cursor to home,
  88. screen clearing, and insert and delete modes are translated to the
  89. corresponding Amiga sequences.  The program MANDOG.COM, which I
  90. wrote for my original CP/M (H19) system and copied here unchanged,
  91. demonstrates the cursor addressing capabilities of SimCPM.  Any escape
  92. sequences that SimCPM can't recognize are passed through unchanged.
  93. You can disable all escape sequence translation by changing the equated
  94. value "h19" (in options.i) to from 1 to 0 and re-assembling.
  95.  
  96.      To speed up console output for programs which write one character
  97. at a time, I have included a buffered output option.  If you include
  98. the -b switch on the command-line parameter, all console output will be
  99. held until one of the following events occurs:
  100.  
  101.           - a carriage return, line feed, or bell character is written
  102.           - the buffer (currently 2K) becomes full
  103.           - a BIOS or BDOS call other than console output is made.
  104.  
  105. It should be possible to use buffered output in just about any program.
  106. Note that if a program uses the "console output string" function (BDOS
  107. call 9), the entire string is written in a single operation even when
  108. buffering is not requested.
  109.  
  110.      If you include the -t switch on the command line, instruction
  111. and/or BIOS/BDOS tracing is available.  Simulations run somewhat slower
  112. with this flag set, even if tracing is not currently active.  Tracing
  113. is done using 8080 mnemonics by default.  If you want Z-80 mnemonics,
  114. use -z instead of -t.  If both -z and -t are specified, -t will be
  115. ignored.
  116.  
  117.      If the trace switch has been specified, SimCPM will prompt you
  118. for starting and ending addresses for tracing, and whether you want
  119. BIOS/BDOS calls traced.  Simulation starts with tracing disabled.  When
  120. SimCPM executes an instruction at the starting address, tracing is
  121. turned on.  All Z-80 registers and the top four stack entries, as well
  122. as the current instruction, are displayed for each instruction until
  123. the ending address is reached.  Tracing is then disabled until the
  124. start address is again encountered.  After displaying 8 instructions,
  125. execution is suspended; enter S to stop tracing and continue executing,
  126. Q to quit the program, C to change the starting and ending addresses
  127. for tracing, or any other key to trace the next 8 instructions.
  128.  
  129.      If you have requested BIOS/BDOS call tracing, the message
  130.  
  131.           BIOS CALL nn (hex) AT aaaa
  132. or
  133.           BDOS CALL nn (hex) AT aaaa
  134.  
  135. will be displayed each time a BIOS or BDOS call is made.  The BDOS
  136. call number (contents of register C in hex) will replace "nn" for BDOS
  137. calls, while BIOS calls will set "nn" to a sequential number starting
  138. at 01 for program termination, 02 for console status, etc.  The address
  139. where the call is made will be taken from the top of the stack and
  140. displayed in place of "aaaa".
  141.  
  142.      List output is sent to PRT:RAW.  This ensures that no newline
  143. translation will take place.  The printer is not opened until the first
  144. attempt is made to access it.  If the printer cannot be opened for any
  145. reason, the program will be terminated.  At program termination the
  146. printer will be closed if it was used.
  147.  
  148.      If SimCPM is brought up with no command-line parameters, it will
  149. present the standard CP/M A> prompt.  At this point you can run CP/M
  150. .COM files just like on a normal CP/M system.  The command line will
  151. be scanned for up to two FCBs and the tail will be passed to the
  152. program.  When the program terminates, the A> prompt will be
  153. re-displayed.  To return to AmigaDOS, enter a control-C (CP/M warm
  154. boot) at the A> prompt.
  155.  
  156.      If command-line parameters are given, they will be passed to
  157. SimCPM as if they had been entered at the A> prompt.  When the program
  158. terminates, SimCPM will automatically return to AmigaDOS.  This allows
  159. you to run CP/M programs from an EXECUTE file.
  160.  
  161.      Here are some sample invocations of SimCPM:
  162.  
  163.           simcpm
  164.                Loads the simulator, which presents the A> prompt and
  165.                waits for CP/M commands.  Type control-C at the prompt
  166.                to exit.
  167.  
  168.           simcpm -b
  169.                Same as above, except console output buffering is used.
  170.  
  171.           simcpm myprog
  172.                Loads the simulator, which loads and runs the CP/M
  173.                program MYPROG.COM.  When MYPROG terminates, SimCPM
  174.                returns to AmigaDOS.
  175.  
  176.           simcpm -t myprog
  177.                Same as above, except that before MYPROG.COM is run,
  178.                you will be prompted for trace parameters.
  179.  
  180.           simcpm -z myprog
  181.                Same as above, except that Z-80 mnemonics will be used
  182.                for tracing, rather than 8080 mnemonics.
  183.  
  184.           simcpm mbasic basprog
  185.                Loads the simulator, which loads Microsoft BASIC-80 (if
  186.                you have it), which in turn loads and runs BASPROG.BAS.
  187.                When BASPROG issues a SYSTEM command, SimCPM returns
  188.                to AmigaDOS.
  189.  
  190.           simcpm -b mbasic basprog
  191.                Same as above, but with console output buffering.  Since
  192.                MBASIC does all console I/O one character at a time, the
  193.                buffered option can speed it up considerably.
  194.  
  195.      I have included two CP/M programs for demonstration purposes.
  196. TESTPROG.COM is a simple "hello, world" program (try it using the
  197. trace option), while MANDOG.COM demonstrates cursor addressing for
  198. an emulated H19 terminal.
  199.  
  200.      SimCPM consists of two source modules, SIMCPM1.ASM and
  201. SIMCPM2.ASM.  No include files are needed, although amiga.lib is
  202. required for linking.  The makefile is set up to use my own assembler,
  203. A68k, and BLink - it should be relatively easy to adapt it to whatever
  204. assembler and linker you are using.
  205.  
  206.  
  207.      Special thanks to:
  208.  
  209.        Jim Cathey for his article in Dr. Dobb's Journal -
  210.         it provided the starting point for this program.
  211.  
  212.        Willi Kusche (for new ideas and corrections of my Z-80 code)
  213.        SYSOP
  214.        KMMM Pascal BBS
  215.        (609) 232-0773
  216.        24 hours a day
  217.        7 days a week
  218.        300/1200/2400/9600 bps
  219.        9600 is USRobotics HST protocol
  220.        Passing a simple IQ test required for full access
  221.  
  222.  
  223.      Please address any kudos, flames, etc. to
  224.  
  225.           Charlie Gibbs
  226.           2121 Rindall Avenue
  227.           Port Coquitlam, B.C.
  228.           Canada
  229.           V3C 1T9
  230.  
  231. or to Larry Phillips or Jeff Lydiatt on CompuServe or Usenet.
  232. (I don't have the time or money to live there myself.)
  233.