Home

"Z80MU" Z80 and CP/M 2.2 Emulator User's Guide or

1. COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 T BUILTIN COMMANDS G NERAL Builtin illop fault nop i fault nop Specifies how the Emulator is to handle illegal Z80 opcodes If illop fault is entered then an illegal Z80 opcode will cause a Z80 fault meaning that the Emulator will stop executing the Z80 program and will display an error message to the effect that an illegal opcode was encountered at such and such and address If illop nop is entered then an illegal Z80 opcode will simply be ignored This is closer to true Z80 operation Execution will continue with the next 280 instruction after the illegal opcode If only illop is entered then the Emulator simply reports how it is currently handling illegal opcodes Example from an actual session Z80 A gt i Illegal opcodes will act as NOP s Z80 A gt illop fault Illegal opcodes will FAULT Z80 A gt illop nop Illegal opcodes will act as NOP s COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 T BUILTIN COMMANDS G NERAL Builtin exit e Exits the Emulator and returns to PCDOS Due to certain limitations within PCDOS you should not remove any floppy disks that are being used until you have exited the Emulator via this command unless you know that the Z80 programs which you have
2. EMULATOR BUILTIN COMMANDS The Builtin Commands are presented by functional grouping The PCDOS pass through command prefix CP M Builtins that are emulated Emulator Builtins that are similar to CP M s General Emulator commands Emulator DEBUG commands CP M Environment and file control commands RESOURCE commands m COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS PCDOS PASS THROUGH Builtin Passes command xxxxxx to PCDOS This gives you a way to use the usual PCDOS utilities from within the emulator without having them interpret ed as CP M commands Everything after the character is passed as a command to PCDOS This command requires the reloading by PCDOS of the PCDOS COMMAND COM file from disk See the section on The PCDOS Environment for more detail on this subject Since PCDOS handles the command and any command arguments that may be present the standard PCDOS PATH environment string may apply So may all other PCDOS conventions like I O redirection wildcards PCDOS device names Tes The given command is executed above the Emulator s memory This implies that there had better be enough memory available above the Emulator to run the given command You may use this facility to drop into PCDOS for a while perhaps to use
3. The specified block of memory is written from the CP M Segment to the specified file It is written as a pure memory image unless a HEX extension is supplied Specifying a filename of type HEX will cause an Intel HEX file to be written The final record of the generated HEX file is the special HEX record which specifies the starting execution address of the program This address is assumed to be nlow Example Z80 A gt read 100 820init com Low 0100H Next 0380H xxx 780 DMA PC and Stack automatically set for COM file Z80 A gt write 100 360 820init hex Writing HEX records for 0100H thru 0360H 609 bytes to file 820INIT HEX Z80 A gt read 820init hex xxx HEX file Starting Address 0100H Low 0100H Next 0360H COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 Switches input for Emula This is roughly equivalen it is built Builtin BUILTIN COMMANDS CP M ENVIRONM sub lt filename typ gt into the Z80 applica Emulator input is switched tion input Input rever detected o NOTE but via submit lt filename typ gt BDOS and I ts to the standard input n the specified fil tor commands only t to the CP M SU Emulator ENT CONTROL to th specified fil BMIT COM program except that BIOS does not get switched Only Submit
4. 0000 00 00 OLFA FEFE 0 0 0 ZF 0 HF 0 P V 0 NF 0 CF 1 HALT COMPUTERWISE CONSULTING SERVIC ES P O BOX 813 MCLEAN VA 22101 T BUILTIN COMMANDS DEBUG SUPPORT Builtin pctrace FIRST LAST n FULL BRIEF pc FIRST LAST n FULL BRIEF Displays the Z780 PC s which were saved during the last trace or pe notrace execution wound up at a particular address or where it went from there 3 a he display may proceed from the oldest PC toward the newest FI or in the reverse direction LAST n p disassembled instruction at each PC FULL Note that a FULL display assumes that instructions haven t been Since they executed All that is saved in the circular PC queue PC itself For a FULL display the current contents of whatever that address is disassembled The n argument is a numeric value as described at the beginning section The default is LAST 512 FULL Example Z80 A gt pc Z80 A gt pctrace first 20 full Z80 A gt pc last 20 brief COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 his is very useful for finding out how the Z80 RST n he display may include only the PC itself BRIEF or the complete modified is the is at of this Builtin move nlow nhigh ndest BUILTIN COMMANDS T DE
5. single char NO NUL byte Nb or B Backspace char t or T TAB char n or N LINEFEED char Nr or NR CARRIAGE RETURN char yg single apostrophe char BUILTIN COMMANDS T DEBUG SUPPORT xFF or XFF singl byte with HI lt space gt lt return gt to leav next one th addressed byt unchanged lt return gt to exit the interactive patch mode XXX A comment Example Z80 A gt patch 400 from an actual session 00 00 Enter for help with PATCH entries 0400H 00H R 0401H 00H 1 20 0402H 00H ffNO 0405H 00H Z80 A gt d 400 40f 400 40f ADDR 00 01 02 03 04 05 06 07 08 09 OA 0400 52 69 66 66 00 00 00 00 00 00 00 Z80 A gt p primary _ fcb JoanRiff z Z80 A gt d primary_fcb secondary fcb ADDR 00 01 02 03 04 05 06 07 08 09 OA 0050 0060 52 69 66 66 20 20 20 4D 00 00 80 0070 6D OB 1B BF 40 F3 00 00 00 F3 00 COMPUTERWISE CONSULTING SERVICES P OC 00 OC 4A 80 OD 00 OD 6F 01 BOX 813 00 61 00 MCLI le double quote char EX value of FF OF 01234567 00 RIE Eeti OF 01234567 OR ow Riff M m s EAN VA 22101 and move to everything following the semicolon is ignored 8 9ABCDEF BUILTIN COMMANDS Builtin xreg Sco eae T Leren n Sets 2
6. 0 2 341200 00 5 65 LIO Select te GJE 6 59 parity en None Select w th 8 C tions po USING THE RESOURCE BUILTIN COMMANDS NOTE Now let s look at the first code bytes again and see if they make any more sense 280 C gt 1 100 STARTUP L0100 11 45 02 LD DE INIT MSG L0103 CD 40 02 CALL 10240 LOI06 11 C8 02 LD DE BAUD PROMPT L20109 CD 40 02 CALL 10240 LO1OC CD 35 02 CALL 10235 LOLOF FE OD CP CR LO111 C2 16 OL JP NZ L0116 L0114 3E 36 LD Aye LO116 D6 30 SUB ZON NOTE So the routine at 0240h does something with a terminated string Need we guess Z80 C gt 1 240 L0240 OE 09 LD C TAB L0242 C3 05 00 JP L0005 INIT MSG DB SUB INIT 1 0 for Xero L0245 1A 49 4E 49 LO249 54 20 31 2E LO24D 30 20 66 6F LO251 72 20 58 65 L0255 72 OF NOTE First of all note how the above disassembly changed from instructions to data just as we told it to Note also that this routine at 0240h is simple enough to document 280 C gt 5 bdos 280 C gt 240 nPrint S terminated string at DI FI lt Z80 C gt c 240 i COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 USING THE ES OURCE BUILTIN COMMANDS Z80 C gt 240 print string 280 C gt 1 240 L0240 OE L0242 C3 L0245 1A L0249 54 LO
7. only the specif is entered then and at various other times when it the current Breakpoint Table addresses If break set is entered followed by one or more Z80 addresses then ollowing the command are added to the Table clear is entered ied addresses ar then all active breakpoint addresses occur If break clear is entered followed by one or more Z80 addresses then removed from the Breakpoint Table NOTE When a breakpoint is encountered during execution of the that breakpoint s address is automatically cleared Z80 code from the t able COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 COMPUT Example Z80 Z80 Z80 Z80 Z80 Z80 Z80 Z80 ERWISE BUILTIN COMMANDS T DEBUG SUPPORT A gt break clear A gt b 5 Breakpoint set start ts cleared tup startup 3 14f 210 221 Breakpoin ts set 5 now in table A gt b clear 221 A gt b Current 0100H 4 Breakpoints cleared 4 left Breakpoints 0103H 014FH 0210H Breakpoints currently set A gt b clear 210 startup 2 A gt b Current 0103H 2 A gt b 2 A gt b Current 0 CONSULTING S clear Breakpoints cleared 2 left Breakpoints O14FH Breakpoints currently set Breakpoints cleared Breakpoints Breakpoints current
8. BUG SUPPORT m nlow nhigh ndest oves CP M memory from one loca location within the CP M Segment ct ct The new location for the block is defined by ndest he block of memory to be moved is defined by nlow through nhigh ion within the CP M Segment to another All three arguments are numeric values as described at the start of this section ADDR 0050 0060 0070 ADDR 0050 0060 0070 COMPUT Example Tp r Le needed from an actual session A gt p primary fcb JoanRiff A gt d primary fcb secondary fcb 01 02 03 66 BF A gt move primary A gt d primary_fcb secondary fcb 01 69 69 ERWISE 02 66 66 CONSULTING S 03 66 66 04 20 40 04 20 20 05 20 F3 05 20 20 06 20 00 fcb secondary fcb secondary fcb 06 20 20 07 4D 00 07 4D 4D ERVICE 08 00 00 08 00 00 09 00 F3 09 00 00 OA 80 00 OA 80 80 OC 4A 80 OC 4A 4A OD oF 01 OD 6F 6F BOX 813 MCLI 61 61 00 00 oO al 61 61 OF 61 61 Gl Gl The move is done either left to right or right to left So no smearing is possible 01234567 89ABCDEF Joan Riff Me Ga ean ec m S S 01234567 89ABCDEF Joan Riff M Joan Riff M EAN VA 22101 T BUILTIN COMMAN
9. 20 69 20 65 20 08 00 00 00 that are terminated with This is a heavy hint that these strings are to 36 74 08 79 24 OD 20 20 E 6F 63 20 24 13 00 00 00 74 20 OD 20 00 00 00 20 77 20 20 OA 43 70 6F 00 00 00 00 00 00 1 480 2400 4 6 300 ES baud ra 1 Select Odd Ev BON SS ord leng Tor 8 ommunica rt set Let s start our control USING THE RESOURCE BUILTIN COMMANDS 0280 3D 20 31 OD OA 34 38 30 30 20 0290 32 34 30 30 20 20 3D 20 33 OD 02A0 20 3D 20 34 OD OA 20 36 30 30 02B0 OA 20 33 30 30 20 20 3D 20 36 02C0 20 20 3D 20 37 OD OA 24 OD OA 02D0 20 62 61 75 64 20 72 61 74 65 02E0 20 20 20 20 20 28 31 2D 39 29 02F0 OA 53 65 6C 65 63 74 20 70 61 0300 28 4F 64 64 2C 20 45 76 65 6E 0310 29 3A 20 4E 08 24 OD OA 53 65 0320 6F 72 64 20 6C 65 6E 67 74 68 0330 28 37 20 6F 72 20 38 29 3A 20 0340 6F 6D 6D 75 6E 69 63 61 74 69 0350 72 74 20 73 65 74 2E 24 00 00 0360 00 00 00 00 00 00 00 00 00 00 0370 00 00 00 00 00 00 00 00 00 00 NOTE Well there are some strings dollar signs be displayed by BDOS function 9 table by filling in what we know so far Z80 C gt c 100 instructions Z80 C gt 100 startup Z80 C gt c 245 b Z80 C gt 245 init msg 280 C gt 2c8 baud prompt 280 C gt 2ef parity prompt Z80 C gt 316 databits prompt Z80 C gt 33d wrapup msg COMPUTERWISE CONSULTING SERVICES P BOX 813 MCLEAN VA 22101
10. This command invokes the PCDOS for details as to what s legal Copy specified by lt from pattern gt to the file or directory command so see the PCDOS manual It also causes PCDOS to reload COMMAND COM so see ment section for further detail on that subject The PCDOS Environ This command is roughly equivalent to CP M s PIP lt outfile gt lt infile gt You have the additional power of PCDOS s directory and device name support Example Z80 Z80 Z80 Z80 Z80 Z80 Z80 however A gt copy B A gt co b asm A gt copy bin c backup A gt copy asm combined bak A gt co asm bak A gt co foo asm lptl A gt co con autoexec bat COMPUTERWISE CONSULTING SERVICES BOX 813 MCLI EAN VA 22101 T BUILTIN COMMANDS GENERAL Builtin help command command Displays a brief description of the requested Builtin Command If no command name follows the help command then a rather lengthy explanation of all commands is displayed If you press the SPACE bar this long listing will be interrupted at the next logical break The listing can be paused with S Q or CTRL NumLock You can turn printer copying on before the listing starts which is recommended with P or CTRL PrtSc Example Z80 A gt help xreg Z80 A gt list Z80 A gt Z80 A gt help Z80 A gt help b Z80 A gt help
11. the Emulator BDOS functions and this section emulated CP M then it is communicating which is maintained by t interprets ASCII codes that ar and translates them into appropriate calls to s displ mulated e sent the terminal numbers and so on to under not BIOS he this IBM ROM to are They appear on the called but to cause the minal to perform special functions like clearing the screen between high and low intensity The builtin mode They are as fol COMPUT RWISE r terminal and so on obeys VT52 control sequences same ones used by the Heath Zenith H19 and H89 machines when in ZDS llows CONSULTING S ERVICE BOX 813 trol ter switching con which are the MCLEAN VA 22101 THE CP M T ENVIRONMENT H Homes cursor C Advances cursor 1 char to right Stays on same line D Backspaces cursor one char to left Stays on same line B Moves cursor down 1 line staying in same column Screen is scrolled if necessary A Moves cursor up 1 line staying in same column No scrolling occurs I uppercase letter I HEX 049h Moves cursor up 1 line staying in same column Scrolling occurs if cursor was on top line n Causes current cursor position to be returned via emulated keyboard as ESC Y lin column This control sequence is ignored
12. lt pattern gt This invokes the PCDOS DIR command so remember about COMMAND COM see The PCDOS Environ ment section lt pattern gt is passed directly to PCDOS So see the PCDOS manual if you want to know what s legal The CP M STAT command STAT COM cannot b mulated because th first thing that Digital Research s STAT COM does is invoke a hardware specific CP M function that means nothing on the IBM PC and is there fore illegal within the Emulator But the most common function of STAT COM displaying filenames and file sizes with STAT or whatever can be done with PCDOS s DIR command So STAT and DIR have been made to do the same thing If you re used to typing STAT in CP M then you ll be able to do the same thing under the Emulator Example from an actual session Z80 A gt stat b Volume in drive B has no label Directory of B WORDSTAR lt DIR gt 11 02 85 4 19a 1 File s 89088 bytes free Z80 A gt dir b wordstar ws Volume in drive B has no label Directory of B wordstar WSMSGS OVR 27904 11 06 85 6 27p WSOVLY1 OVR 34048 11 06 85 6 30p WSU COM 15872 11 06 85 6 32p WS COM 15872 11 06 85 6 37p 4 File s 89088 bytes free Z80 A gt b Z80 B gt dir COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS EMULATED CP M BUILTIN S Volume in drive B
13. 813 MCLEAN VA 22101 INTRODUCTION The saving grace to this CP M to PCDOS conversion is that it needs to be done only once for a given file We spent quite a while transferring 10 megabytes of CP M files to the IBM PC But we need never do it again Now we just run everything on the IBM PC How Do I Run It The Emulator is just another PCDOS program There are no arguments to give it There is no syntax Just type Z80MU and bingo you re in CP M To make things easier you may want to copy Z80MU EXE to one of your PCDOS PATH directories if you have any If you don t have any PATH directories set up then just insert the floppy that holds Z80MU start the program and then remove the floppy You don t need it until you want to run the Emulator again The next section The PCDOS Environment describes the PCDOS environ ment that applies to the Emulator You may want to study it before you run the thing What Can Go Wrong The Emulator is as safe a program as ever you ll find on the IBM PC You will probably never experience any problem with it There is one important thing to watch out for however If the Emulator itself is ever aborted then you should immediately reboot your IBM PC Why Because the Emulator must trap the IBM PC s BREAK interrupt When the Emulator returns to PCDOS via the exit command it restores this i
14. BDOS handler 4 The DMA address in effect at the instant of this BDOS call 5 The BDOS function as passed in the Z80 C reg and a text description of t The CP M program it out If an argument either table is not displayed argument the way that In If SOME is speci SOME he function BDOS Trace Table is cleared by a COLD and at various other times w or ALL stead the future traces will fied then the Console Sta Direct Consol t be traced I Outpu will from m no If A e I O then Emul being performed BOOT hen it by the load of a new seems logical to clear wiy is present then the trace ator adjusts according to the and List Output This can help to keep the filling up with unimportant entries be made tus Console BDOS functions BDOS Trace Table thes BDOS console character functions will be tra LL is specified ven ced r COMPUTERWISE CONSULTING S ry RVICE BOX 813 MCLEAN VA 22101 Z80 A gt b Future BUILTIN COMMANDS DEBUG SUPPOR Example from an actual run of trace all BDOS traces will include Z80 A gt a dump dump com 0000 21 00 00 39 22 15 02 0010 1B 01 11 F3 01 CD 9C 0020 21 00 00 E5 CD A2 01 Much of DUMP COM ou 0150 00 00 00
15. CP M addresses that are referenced by the block of Z80 code that starts at nl and ends at n2 both of which are numeric values as defined at the start of this section Labels that are generated are automatically entered into the current control table Existing labels will not be altered his is a quick way to create labels It can be useful for rapid eneration of readable source code from Z80 object code You should owever define any recognizable labels before using this command You hould also make sure that you have pretty accurately defined all ontrol breaks that apply to the specified block of Z80 code There s othing worse than getting a block of data confused with instructions nd having this command generate a few hundred bogus labels by misinter preting the Z80 code 9 DaAnNnPaQH BUILTIN COMMANDS R EE SOURC E FACILITY COMMANDS So this is generally the last thing that you do before deciding that you have finished disassembling a complete Z80 program NOTE 16 bit literals will of human inspection to tell if be a Z80 address or just a binary In previous versions of the Emula bogus labels being autogen d from up to you to decide whether a par should have a label associated wi following instructions IX nn IY nn BC nn DE nn HL nn UD E K AAN G Example SP nn 280 A gt 100 program entry Z80 A gt la
16. FFOFh Output C reg to LPT1 via IBM s ROM BIOS FF12h Output C reg to COM1 via IBM s ROM BIOS FF15h Get char from COM1 to A reg via IBM s ROM BIOS FF18h Home Disk unsupported FF1Bh Select Disk unsupported FF1IEh Set Track unsupported FF21h Set Sector unsupported FF24h Set DMA address unsupported FF27h Read Sector unsupported FF2Ah Write Sector unsupported FF2Dh Set A reg to FFh if LPTl ready for output 00h if not as reported by IBM s ROM BIOS FF30h Sector Translate unsupported Similarly here is a table of the various BDOS functions in Decimal HEX and their actions under the Emulator Note that a CP M BDOS function is invoked by loading the function number into C reg doing a CALL 0005h calling conventions BDOS Function 00 00h Warm 01 01h Read 02 02h Send and See standard CP M documentation for detailed Boot Returns to accept more not alter memory in the CP M Segment char from PCDOS standard input E reg to PCDOS standard output Emulator commands to A reg Does T THE CP M ENVIRONMENT E 03 03h Read char from PCDOS AUX device into A reg 04 04h Send E reg to PCDOS AUX device 05 05h Send E reg to PCDOS PRN device 06 06h If E reg on entry FFh then return in A reg next char from PCDOS standard input or 00h if none available at this instant If E reg on entry lt gt FFh then send E reg to PCDOS standar
17. VA 22101 8 9ABCDEF 8 9ABCDEF BUILTIN COMMANDS CP M ENVIRONMENT CONTROL Builtin coldboot ldboot cold Cold Boots CP M memory by zeroing the 64K CP M Segment installing the BIOS and BDOS hooks formatting the first page of memory just as CP M would etc When you first start up the Emulator the CP M Segment has already been Cold Booted You may use this command to clean things up when you suspect that Z80 software may have corrupted the BIOS or BDOS hooks garbaged page zero or whatever If a Z80 program exits with an Emulator message to the effect that the program requests termination via Cold Boot then you should use this command to do it The Z80 program probably had a good reason for asking for a Cold Boot Example Z80 A gt coldboot CP M Segment COLDBOOTED COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS CP M ENVIRONMENT CONTROL Builtin terminal ON OFF term ON OFF Enables or disables the builtin VT52 emulated terminal If ON is specified then th mulated CP M BIOS routines that deal with the console will perform terminal emulation as described previously Such I O goes straight to the IBM PC screen via the IBM PC ROM BIOS routines and is therefore never seen by PCDOS If OFF is specified t
18. Z80MU Z80 and CP M 2 2 Emulator User s Guide or The Care and Feeding of Your Imaginary Z80 or Fakeware For The Techie Masses A Guide to the Complete Z80 Emulator COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 Textformat angepasst an OpenOffice org writer 25 11 2010 von Dr Hehl Hans Z80EMU PDF www hehlhans de euroz80 htm Describing the first of a two part series of 8080 Z80 and CP M emulators for the IBM PC This document describes Z80MU version 2 1 Z80MU dated 10 30 85 a software emulation of the Z80 and CP M 2 2 The second product if it ever gets out the door includes hardware emulation of the 8080 using the NEC V20 8088 compatible processor chip Program written by Joan Riff for Computerwise Consulting Services Joan Riff Placed in the public domain No copyright notice No legal mumbo jumbo No request for a financial contribution No warrantee Just a bunch of marvelous software magic COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 Z80MU Z80 and CP M 2 2 Emulator User s Guide INTRODUCTION what is it Z80MU is a software emulator of the ZILOG 280 processor which runs on the IBM PC It also provides an emulation of Digital Research s CP M version 2 2 operating system It includes the following facilities Complete emulation of Z80 object code including all six active bits within the Z80 Flags Register Emulati
19. are numeric values as defined at the start of this section If n2 nl 22 If nl is absent then it de disassembled as left by last list The generated disassembly is sent gt gt outfile the specified output specified no gt character presen is absent faults to t command then n2 is assumed to be he next address to be to gt outfile or appended to file If an output file is not t then the generated disassembly goes to the standard output as defined by PCDOS normally the screen NOTE Disassembly speed decreases as the size of the control table increases It may also be slowed by PCDOS being so When disassembling the Radio which required a control table of we were only getting about 2 lines of disassembled code per second lethargic with screen output Shack Model 100 s memory about 42K for instance Generated source code is suitable for input to M80 COM in Z80 mode Note however that any RST instructions use as their argument the not the RST number as is customary Also there is no END statement supplied final address being jumped to COMPUTERWISE CONSULTING SERVICE P 0 BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS RESOURCE FACILITY COMMANDS Format list prologue nl n2 gt outfile gt gt outfile l prologue nl n2 gt outfile gt gt outfile This form generates assembler source c
20. calls the CP M BIOS to read terminal an ESCAPE character will be returned a Decimal 073 HEX 49h will be returned This is The above information may be used to configure particular Z780 applica tions for use with the emulated termi tions that do I O standard CP M u Emulator s nal only appears at the CP M via tilities B termina DOS functions whic do not see this b 1 Remember that this BIOS interface Applica h includes most of the ehavior and those WORDSTAR d Base configured for informa tor using this emulated VT52 TE least some of their terminal I O via the particul tion when installing such appl Target Plannercal termin c and PMATI the CP M BIOS F sy alert that things can get very confusing when one application for example so they mus lar terminal being used Refer to the lications for use under the Please bear in mind like dl do at t be above Emula however Base II T THE CP M ENVIRONMENT does terminal I O via both the BIOS and the BDOS Just experiment until you get something useful NOTE This emulated terminal facility may be enabled and disabled via the terminal builtin command which is des cribed in the Builtin Commands section C and BREAK Handling The C Ctrl C and BREAK Ctrl Scroll Lock keys are handled in a special way on the I
21. ding the cursor position ESC 1 lowercase letter L HEX 06Ch Erases th ntire lin that the cursor is on positions the cursor to the left edge of that line ESC o lowercase letter 0 HEX O6Fh Erases from the beginning of the line to the cursor including the cursor position ESC K Erases from the cursor to the end of the line including the cursor position ESC L Inserts a blank line before the line that the cursor is on shifts following lines including the cursor line down to make room Cursor is moved to start of new blank line ESC M Deletes the line that the cursor is on scrolls follow ing lines up to fill its place Cursor moves to left edge of its line ESC N Deletes the character under the cursor shifts remaining text to left to cover it up ESC At sign character HEX 040h Enters Insert Mode Displayed characters cause others on the same line to b moved right to make room This can be pretty pokey thanks to the IBM ROM BIOS ESC O uppercase letter O HEX 04Fh Exits Insert Mode ESC p Enters Reverse Video or Highlight mode ESC q Exits Reverse Video or Highlight mode BEL decimal 7 Beeps bell BS decimal 8 Backspaces cursor one character position HT decimal 9 Tabs cursor to next mod 8 column boundary COMPUTERWISE CONSULTING SERVICES P O BOX
22. disassembler the RESOURCE facility and the rest of the advanced features tment in CP M software Most of that software consists of fairly esoteric software development tools things BM PC world Furthermore we continue to ld chip just won t die although ler boards than as a primary system yet apply our numerous IBM PC tools especially some fantastic IBM PC editors like SPF PC to our Z80 We were also keenly interested in creating source code for some object only Z80 applications with a view to converting them to 8088 assembler source code for re assembly as native II BM PC programs We scouted around and discovered several software packages which sup posedly allowed us to run CP M on the II he Heath User s Group ii just couldn t cut it HUG BM PC Needless to say they emulator 80Mate by Vertex and a few similar packages were considered We weren t impressed by the speed of emulation or by the accuracy of the user interface What s more people who were in the business of 280 development badgering us to solve this problem the right way means COMPUTERWISE CONSULTING SERVICE 0 BOX 813 MCLI the emulation or by we kept bumping into more and more and who kept whatever that EAN VA 22101 INTRODUCTION How Does It Work When it runs under PCDOS the Emulator looks like this Z80MU C main program This is w
23. list b model100 model1100 ctl l write foo ctl XYZ 100 Instructions A gt c table _start l S A gt CONTROL bios address W A gt c FFOO Table A gt c 103 clear The next section contains a sample Emulator session which generates source code from object code Refer to it for more detail about this and related Resource commands ERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS RESOURCE FACILITY COMMANDS Builtin label n label name label autogen nl n2 n label name autogen nl n2 This command controls the assignment of symbolic label names to various CP M addresses Symbolic labels may be used as numeric values in many Emulator commands They are also used by the disassembler when creating source code from 4280 object code Format label n label name n label name This format associates label name with CP M address n which is a numeric value as described at the start of this section Label names may be up to 32 characters in length They must contain only alphanumeric characters and the underscore character _ If label name is absent in this command then any existing label name associated with the specified CP M address is simply deleted Format label autogen nl n2 autogen nl n2 This format causes the Emulator to automatically generate labels of format AUTOxxxx for all unlabeled
24. lt oldname gt This command causes PCDOS to reload COMMAND COM so see The PCDOS Environment section for further detail on that subject This command invokes the PCDOS RENAME command See the PCDOS manual for details Example Z80 A gt rename dbase exe dbase xxx COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS SIMILAR TO CP M S Builtin save n lt filename typ gt sa n lt filename typ gt Saves n 256 byte pages of CP M memory starting at address 0100h to the specified file The data written to the file is a simple memory image No translation is done even if a HEX extension is given in the filename If you want to write a true Intel HEX file use the writ Builtin NOTE This is close to the CP M equivalent except that the default radix for n is HEX not decimal as with CP M Example from an actual session Z80 A gt save 3 820init2 com Writing 3 pages 768 bytes to file 820INIT2 COM Z80 A gt save 0 continue com Writing 0 pages 0 bytes to file CONTINUE COM COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 Builtin Copies the file s BUILTIN COMMANDS SIMILAR TO CP M S copy lt from pattern gt lt to path gt co lt from pattern gt lt to path gt specified by lt to path gt
25. may be whole words Only the first character is checked If no arguments appear after include then the disassembled Z80 instruction will consist only of the mnemonic field COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS RESOURCE FACILITY COMMANDS Example Z80 A gt list include addresses Z80 A gt list include Z80 A gt l prologue 100 7ff Z80 A gt list prologue 0 ffff gt modell00 rom 280 A gt list 0 ffff gt gt modell00 rom 280 A gt list NOTE The next section contains a sample Emulator session which generates source code from object code Refer to it for more detail about this and related Resource commands COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS RESOURCE FACILITY COMMANDS Builtin control list n control clear control read lt filepath gt control write lt filepath gt control n aS fk BP MOENS JE c list n c clear c read lt filepath gt c write lt filepath gt cn PB WE I SONE a This is a multi purpose command which manipulates the disassembly control table H The disassembly control table holds CP M addresses and any or all of the following which are associated with each address The data type of the Z80 object code at this address This is called a control break A s
26. not supported by the Emulator j Saves cursor position for later restore via ESC k k Returns cursor to position that was saved via ESC j Y lin column Direct cursor addressing sequence Screen lines are numbered 1 to 25 Screen columns are numbered 1 to 80 Lin and column args are obtained by adding 31 01Fh to the desired line or column number Alternative ly you may think of lines as being numbered from 0 to 24 columns from 0 to 79 and the offset to add to each being 32 020h To position to line 5 column 10 for example the following is sent ESC Y which is represented in HEX as O1Bh 059h 024h 029H and in decimal as 27 89 36 41 Note that the lin arg is obtained by 5 31 36 024h and the column arg by 10 31 41 029h Lin or column args less than 32 default to 32 i e to line or column 1 An arg value that is too large defaults to the max legal value 25 for line 80 for column COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 THE CP M ENVIRONM EI NT ESC F Erases th ntire screen and homes the cursor ESC b Erases from the start of the screen to the cursor including the cursor position ESC J Erases from the cursor to the end of the screen inclu
27. nothing there How Fast Is It there s the rub Aye instruction Because the Z80 used by the tions must be emulated in softwar is considerably less than the speed of the I for example RGE compiler tor depending on the instruction ffectiv but not SPELSTAR that we happened to have on hand that will run under the Emulator like STAT COM provided by Digital Re These cannot be run under the fully to avoid functions that look to the starts out by interrogating the physical this is unsupported under the Emulator Emulator either It tries to call CP M s CCP te sad It goes to a lot of work to calculate the CCP is relative to the BDOS address held ls that address Unfortunately there s Emulator is an imaginary one whose instruc th its addressing mode For detail on th see the descrip later in this Guide ffectiv speed of a Z80 program BM PC One 12 cycle Z80 may take from 47 to over 100 IBM PC cycles etc speed of the emulated Z80 and what it means tion of the speed and howfast Builtin Commands We have not found the speed of the emulated Z80 to be entirely accept able Z80MU is today for the IBM PC the fastest software based tru Yet we would like to have something that would run Z80 mulator available INTRODUCTION the standard CP M utilities on an IBM PC at an effect
28. of CP M Segment Appendix A Layout of Simulated CP M Segment as set by Cold Boot 0000 0003 0004 0005 005C 0080 0100 FEFD FEFE FEFF FFOO FFO3 FFO6 FFO9 FFOC FFOF FF12 FF15 FF18 FF1B FFLE FF21 FF24 FF27 FF2A FF2D FF30 FF33 FF36 FF39 FF3C FF3F FF42 FF45 FF48 FF4B FF4E FF51 FF54 FF57 FF5A FF5D FF60 FF63 FF66 DU Cy Ca Ea OG GP ENER GE EG Ca GENE Cir Ey Eg Cy Eg Cy Ca Ea EG Car Cp Cy 64 Gay Eg Gr EEG YGUUULUGUUGE H CE Sw z SEERE ao ta os OO en ao ao Ow wn o OO ao a o a o a o nv o Ow a o ao Ow N OFFO3H i fs OFEFEH VV I 1 OFF80H OFF82H OFF84H OFF8 6H OFF88H OFF8AH OFF8CH OFF8EH OFF90H OFF92H OFF94H OFF96H OFF98H OFF9AH OFF9CH OFF9EH OFFAOH OFFA2H OFFA4H OFFA6H OFFA8H OFFAAH OFFACH OFFAEH OFFBOH OFFB2H OFFB4H OFFB6H OFFB8H OFFBAH OFFBCH OFFBEH OFFCOH OFFC2H OFFC4H r r r r r r r r r to our fake BIOS IOBYTE ogin Byte drive User Number Defaul Defaul Star last OUr retu BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BDOS hook to our fake BDOS FCB DMA and Command Tail t of TPA byte of TPA r
29. run have truly closed any files that have been written to We have used the Emulator extensively and have frequently changed floppies while within the Emulator We have never experienced corrupted floppy data But then we use only safe CP M software like ASM COM M80 COM L80 COM and so on Such programs are very good about closing files when they exit This warning is included not because it has ever happened to us but because we wrote the code and we know about certain windows within which a faulting CP M program could conceivably confuse PCDOS into writing one floppy s data to another floppy destroying the second floppy s file data and perhaps even its FAT File Allocation Table Example Z80 A gt exit A gt COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 T NERAL BUILTIN COMMANDS G Builtin speed howfast Calculates th ffective speed of the imaginary Z80 that exists within the Emulator A sample Z80 program is loaded into the CP M segment It is run and its execution is timed This program takes up to half a minute to run ona simple IBM PC with an 8088 and correspondingly less time on faster machines i e a PC with a NEC V20 chip an IBM PC AT etc The effective clock speed is displayed at the end of the test The reported speed should be taken with a grain
30. the object code we should save the con Z80 C gt co trol table to disk ntrol write 820init ctl COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 USING THE RESOURCE BUILTIN COMMANDS Z80 Z80 Z80 Z80 SNo SNo NOTE Having done that we must prepare things for the actual generation of the ASM file Specifically we should exclude addresses opcodes and flags from disassembly source lines C gt list include NOTE Now we can disassemble the object code to disk as source code First we write the prologue and then the program itself C gt list prologue 100 360 gt 820init asm C gt list 100 360 gt gt 820init asm NOTE Having done that let s test things by running the ASM file through M80 COM C gt m80 820init rel 820init prn 820init asm END statement END statement No Fatal error s That s it We re done The assembler version of 820INIT COM has been written and verified For your enjoyment we have included with Z80MU the various 820INIT files that were used or created by the above session Feel free to examine all of these files especially 820INIT ASM and 820INIT PRN They give you a good idea of the quality of source code that can be recreated from a given object program COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 Appendix A Layout
31. then an error message is displayed and the Emulator just waits for you to enter commands from the keyboard If there is such a file however then the Emulator reads its commands from that file until EOF See the submit builtin command for more details about submit files This is an easy way AUTOEXEC Z80 file i cular environment t reads in the 64K Model the disassembler co to automate the n each work direc hat we want to work with within the Radio Shack Model ntrol fil Emulator At CCS we use a different tory in order to set up the parti The AUTOEXEC Z80 file for example automatically 100 image from disk read 0 modell00 mem and le control read modell00 ctl It also L 100 directory sets up the disassemb when we start up the Emul ler format that we want list include A 0 So ator while within that directory the thing comes up ready to do r COMPUTERWISE real CONSULTING S work ERVICE BOX 813 MCLI EAN VA 22101 THI I O Redirection Wit The T E PCDOS Emul ator reads PCDOS PCDOS It writes i So regular ol th The ENVIRONMENT Emulator its commands from the standard input ts output to the standard output that ld PCDOS I O redirection can be used as defined by is defined by when you start the Emulator For ex
32. 0 C gt 10f RETURN only 280 C gt 111 No look at keypress 280 C gt 114 Yes use default value 280 C gt 116 edit baud rate COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 USING THE RESOURCE BUILTIN COMMANDS Z80 C gt 1 get baud rate 12b LO106 LO109 LO10C LO1OF LO111 L0114 LO116 LO118 LO11A LO11D LO1ILF LO0122 L0125 10128 NOTE And so on and so on and so on GET BAUD RATE 11 C8 02 LD DE BAUD PROMPT Ask for baudrate value CD 40 02 CALL PRINT STRING CD 35 02 CALL GET BDOS KEYPRESS FE OD CP CR RETURN only C2 16 O1 JP NZ EDIT BAUD RATE No look at keypress 3E 36 LD A 6 Yes use default value EDIT BAUD RATE D6 30 SUB 60 FE 00 CP NUL DA 06 01 JP C GET BAUD RATE FE OA CE LF D2 06 01 JP NC GET BAUD RATE 32 58 03 LD L0358 A 11 EF 02 LD DE PARITY PROMPT CD 40 02 CALL PRINT STRING CD 35 02 CALL GET BDOS KEYPRESS We ll not present all of the output here Although the session actually lasted less than half an hour the output is huge Instead let us skip ahead to NOT the point where we ve finished defining our control table T E At this point having done all of this work to con struct documentation of
33. 00 00 00 00 0160 00 00 00 00 00 00 00 0170 00 00 00 00 00 00 00 280 A gt bt BDOS TRACE TABLE SEQ Z80PC Z80DE Z80DMA 006 016BH 0030H 0080H 007 016BH 0030H 0080H 008 016BH 0020H 0080H Many entries delet 049 016BH 0030H 0080H 050 01D6H 005CH 0080H 051 016BH 000DH 0080H 052 016BH 000AH 0080H 244 016BH 0020H 0080H 245 016BH 0030H 0080H 246 016BH 0030H 0080H 247 016BH 0020H 0080H 248 016BH 0030H 0080H 249 016BH 0030H 0080H 250 016BH 000DH 0080H 251 016BH 000AH 0080H 252 015EH 0070H 0080H 253 016BH 0030H 0080H 254 016BH 0031H 0080H 255 016BH 0037H 0080H 001 016BH 0030H 0080H T DUMP COM 3l ST OUZ CD 01 C3 51 01 El DA 51 01 tput deleted 00 00 00 00 00 00 00 00 00 00 00 00 FUNCTION 02H Console 02H Console 02H Console d for brevit 02H Console 14H Read Fil 02H Console 02H Consol 02H Consol 02H Consol e e e 02H Console 02H Console 02H Console 02H Console 02H Console 02H Console 02H Console 02H Console 02H Console 02H Console C1 01 3 47 7D E 80 FE FF C2 32 1 3 02 E6 0 F C2 for brevity 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 y Output from e Sequenti Output from Output from Output from Output from Output from Output from Output from Output from Output from Output from tatus Output from Output from Output from Output from OBH Get Console S tput from
34. 1 D1 AQaIeUE M AQ 0170 El C9 3E OD CD 65 01 3E OA CD 65 01 C9 E6 OF FE aI gt Me gt Me If 0180 OA D2 89 01 C6 30 C3 8B 01 C6 37 CD 65 01 C9 F5 R FOC F7Me Iu 0190 OF OF OF OF CD 7D 01 FI CD 7D 01 C9 OE 09 CD 05 M q M 1I M 01A0 00 C9 3A 13 02 FE 80 C2 B3 01 CD CE 01 B7 CA B3 I B 3 MN 7J3 OIBO 01 37 C9 5F 16 00 3C 32 13 02 21 80 00 19 TE BT 7I_ lt 2 L l v7 01C0 C9 AF 32 7C 00 11 5C 00 OE OF CD 05 00 C9 E5 D5 I 2 M IeU 01D0 C5 11 5C 00 OF 14 CD 05 00 C1 D1 E1 C9 46 49 4C E N M AQaIFIL 01E0 45 20 44 55 4D 50 20 56 45 52 53 49 4F 4E 20 31 E DUMP V ERSION 1 O1FO 2E 34 24 OD OA 4E 4F 20 49 4E 50 55 54 20 46 49 4 NO INPUT FI Z80 A gt d primary fcb secondary fcb 15 ADDR 00 01 02 03 04 05 06 07 08 09 OA OB OC OD OE OF 01234567 89ABCDE 0050 01 44 55 4D DUM 0060 50 20 20 20 20 43 4F 4D 00 00 80 00 80 01 00 00 P COM oa heise 0070 6D OB 1B BF 40 F3 00 00 00 F3 00 00 The 2 S 2 8 COMPUTERWISE CONSULTING SERVICES P BOX 813 MCLEAN VA 22101 T BUILTIN COMMANDS DEBUG SUPPORT Begins execution of Z780 code at address n If n is not specified then the starting address defaults to the current Z80 Program Counter PC This is the usual way to run a program that has been read from disk It is also used to continue execution when the Z80 has been stopped via a breakpoint or by the user pressing the BREAK key NOTE A Z80 command COM fi
35. 2 bytes This is more than is available on almost all real CP M systems including the Baby Blue Z80 add on board for the IBM PC from MicroLog We have also built a terminal emulator into the Emulator since many CP M applications especially those doing full screen editing assume that they are being run from an ASCII terminal All in all the compatability of the Emulator is so good that we have been able to move almost all of our CP M applications to the Emulator and to have them run perfectly although a tad slow Here is a partial list of CP M applications that we have tested with the Emulator and found to run as they do on a real CP M system ASM LOAD ED DDT DUMP PIP M80 L80 IB INTRODUCTION BASIC A A Base II QU TE 80 rev elecon C hang Labs This is more a list of the software than an exhaustive list of software What WON T Run Under the search Emulator hardware STAT STAT is WORDSTAR s SPELSTAR won t work It s really qui just where in Z80 memory directly compil A 3 02 oftware Toolworks 1 IC Ler MemoP There are some CP M programs which are hardware specific or must be run for instance layout of the diskette immediately aborted by the M L M d WORDSTAR 3 0 amp 3 3 with MAILM P S T C Lan Emula care Since in location 0005h Then it cal
36. 24D 30 LO251 T2 L0255 72 NOTE OK of PRINT STRING r Print terminated string at DI 09 05 00 INIT_MSG 49 4E 49 20 31 2E 20 66 OF 20 58 65 6F one routine down the startup code Z80 C gt 106 get baud rate Z80 C gt l startup STARTUP LO100 11 45 02 LD 10103 CD 40 02 CALL GET BAUD RATE LO106 11 C8 02 LD LO109 CD 40 02 CALL LO1OC CD 35 02 CALL LO1OF FE OD CP HOLTI C2 16 01 JP L10114 3E 36 LD 10116 D6 30 SUB COMPUTERWISE CONSULTING SERVICES P O LD JP FI lt C TAB BDOS SUB INIT 1 0 for Xero Referring back to our disassembly let s see what else we can figure out J E INIT MSG PRINT STRING DE BAUD PROMPT PRINT STRING L0235 CR NZ LO116 A 6 KON BOX 813 MCLEAN VA 22101 USING THE RESOURCE BUILTIN COMMANDS NOTE We have another routine to decipher at 0235h Z80 C gt l 235 L0235 OE 01 LD C SOH L0237 CD 05 00 CALL BDOS LO23A FE 60 CP a L023C D8 RET G L023D D6 20 SUB mak LO23F C9 RET PRINT STRING Print terminated string at DE 10240 OE 09 LD C TAB L0242 C3 05 00 JP BDOS INIT MSG DB SUB INIT 1 L0245 1A 49 4E 49 L0249 54 20 31 Z80 Z80 Z80 Z80 Z80 Z80 Z80 NOTE Notice how the disassembly continued way past the end of o
37. 80 register or flag rr If no args are present then are displayed DEBUG SUPPORT to value n If args are present then th to the numeric value n this section the current Z80 register values and flags register or flag represented by rr is set whose format is described at the beginning of NOTE The Z780 has a primary and an alternate set of registers set is indicated by appending an to the register or flag name and flags apostrophe The register or following COMPUT The alternat flag to be set in either upper or lowercase Example regs flags A F B A Ed B Ct AF BC DE HL AF BC DE HL IX IY S RE IFF1 IFF2 IMF I SF ZF HF P V SF ZF HE P V 280 A gt xreg pc 0 Z80 A gt x AF BC OAO1 OOOF 0000 0000 0000 0000 SF 0 ZF 0 L0000 DE HL IX 007F FEFC 0000 0000 from an actual session IY the rr argument must be one of the PC IFF1 IFF2 IMF E 0000 0 0 0 3 03 FF 280 A gt xreg bc ffff ERWISE CONSULTING SERVICES JP D E H D E H R NF CF NF CF Tn GR SEP 00 00 FEF HF 0 P V 0 NF 0 CF 1 LFFO3 BOX 813 MCLI EAN VA 22101 BUILTIN COMMANDS DEBUG SUPPORT Z80 A gt x Ao EF iB DE HL 0A01 FFFF O007F FEFC 0000 0000 0000 0000 SF 0 L0000 8 03 EF 280 A gt x c A 280 A gt x
38. 813 MCLEAN VA 22101 F E T THI CP M ENVIRONME LF decimal column FF decimal CR decimal line 4 ne ne rom ne O 128 80h ct I m he emulated VT52 10 12 VI NT H H H EX OAh EX OCh EX ODh Advances cur ther standard ASCII control characters through 255 BM Tech Ref Manual for details FFh terminal also translates input from returned to the characters keys arrow keys keyboard m ne he BM Additionally board Most keypresses ar The extended codes that are generated by IBM func ALT keys sequences as follows first byte is an and so on are r ESCAPE character second byte is Tech Ref Manual the NUL the keyboard scan single ASCII charac For example assume keyboard The next a keypress from the The time after that the scan code for the Pg display various graphic symbols sor to next line same Clears screen and homes cursor Returns cursor to start of current below 032 or 20h See the IBM key Z80 program as single ASCII tion te translated into 2 by HEX 11 Decimal 027 hya code as defined in the Up key xtended code CTRL is translated into a ter Decimal 000 that the user presses the PgUp key on the IBM time that the Z80 program
39. BM PC Under normal circumstances these keypresses are trapped by PCDOS and cause the executing PCDOS program in this case the Emulator to be aborted This is undesirable Additionally CP M includes an important assumption to wit C isa keypress like any other and must be passed through all the way to the Z80 program for processing Several standard CP M programs PIP COM M80 COM WORDSTAR etc use C as a command and must not be aborted when it is typed For this reason the Emulator traps C and BREAK keypresses It decides what to do with them as follows When not running a Z80 program i e when the Emulator is accepting commands the BREAK key does nothing and the C keypress does various things depending on the mood of PCDOS When executing a Z80 program pressing C causes a C character Decimal 003 to be queued as keyboard input Pressing BREAK causes the Z80 to be stopped with an appropriate message and a return to the Emulator awaiting your command NOTE If the Z80 program is in the process of reading a line of keyboard input when you press BREAK then you may have to press RETURN to terminate that read before the BREAK will be recognized When the Emulator stops aborts a Z80 program due to a BREAK key press it displays a message to that effect It suspends the 480 in perfect order maintaining all registers flags etc
40. BOX 813 MCLEAN VA 22101 THI COMPUT 21 15h 22 16h 23 17h 24 18h 25 19 26 1Ah 27 1B 28 1Ch 29 1Dh 30 11 FI 31 1Fh 32 20h 33 21h T E CP M ENVIRONMENT Write next sequential record to file whose FCB is at DE Returns status in A reg as follows 0 successful 5 diskette full 6 PCDOS returned error 2 No room in DTA for record Create and open file whose FCB is at DE Sets A reg to 00h if successful else to FFh 00h if successful else to FFh Return default drive number in A reg Set DMA to DE program See note below Write protect drive ignored Rename file s per special FCB at DE Sets A reg to Return login vector bitmap of known disks to HL Calls PCDOS to discover number of available drives Return allocation information unsupported aborts 480 Return write protect vector bitmap of R O drives to HL Sets HL to zero nobody s write protected Set file attributes ignored but returns A reg of 00h to indicate success Return physical disk information unsupported Z80 program See note below aborts If E reg on entry is FFh then current user number is returned in A reg If E reg on entry lt gt FFh then current user number is set to E reg MOD 32 This only updates the byte at CP M address 4 T R
41. DS DEBUG SUPPORT Builtin math lt expression gt ma lt expression gt Prints 16 bit evaluated result of expression which is composed of numeric values as described at the start of this section connected with or operators The evaluated result is printed in HEX and decimal as both positive and negative numbers Example from an actual session Z80 A gt math 0 7ff HEX F801H O7FFH Dec 63489 02047 FI Z80 A gt ma secondary fcb primary fcb 0010H FFFOH Dec 00016 65520 T A x Z80 A gt ma A 40 a 0062H FF9EH Dec 00098 65438 T EH x COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLI BUILTIN COMMANDS CP M ENVIRONMENT CONTROL Builtin args lt tail gt ar lt tail gt Formats default FCB s at 5Ch and 6Ch as well as default DMA at 80h per command tail exactly as if lt tail gt had followed a Z80 command COM filename This command is most useful for filling in a command tail for Z80 code that has been read into CP M memory and which will look for command line arguments For instance you may want to debug Digital Research s DDT COM program while telling DDT to load file FOO COM You would first load DDT via read 100 ddt com You would then fill in DDT s command line arguments with args foo com When ex
42. E reg tput from E reg tput from E reg E reg al FCI E reg E reg E reg H reg E reg E reg E reg E reg E reg E reg to A reg E reg E reg E reg E reg I Weil console character functions at DI M Ad OnrO LE BUILTIN COMMANDS DEBUG SUPPORT 002 016BH 0020H 0080H 02H Console Output from E reg 003 016BH 0030H 0080H 02H Console Output from E reg 0 004 016BH 0030H 0080H 02H Console Output from E reg 0 005 016BH 0020H 0080H 02H Console Output from E reg END OF BDOS TRACE TABLE COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 T BUILTIN COMMANDS DEBUG SUPPORT Builtin break break clear n n break set n n b b cle b set Manipulates the the Emulator s r TAs Mh sil Breakpoint Table command prompt Breakpoints are typically used in conjunc which contains up to 50 Z80 addresses at which execution of the Z80 is to be halted commands and various other debug commands The Breakpoint the CP M Segmen seems logical t and control returned to tion with the read and go Table is cleared when a new CP M program is loaded when t is Cold Booted o clear it If only break are displayed the addresses f If only break are removed No execution breakpoints will
43. It then accepts Emulator commands At this point you may inspect registers run another Z80 program or EI THE CP M ENVIRONMENT whatever You may also continue execution of the aborted program with the go command available with the Z80 at any This is a very powerful tool for debugging which is no true hardware Z80 systems You may in effect interrupt point actually pausing it between Z80 instructions ct ct This also maintains compatability with existing CP M programs that want to read the C character To exit PIP for example you need only press AC and then RETURN This C is passed to PIP who interprets it as a request to exit the program Note that RETURN must be pressed after the C in some cases like when entering a command line into PIP This is one area of PCDOS CP M incompatability for which Joan Riff offers her apologies A Z80 program like PIP that requests a line of input from CP M won t see the C until th ntire line is terminated with RETURN A Z80 program that asks for one character at a time however will see the C immediately NOTE When running PCDOS commands like type dir and so on the BREAK key is unavailable to you If you want to interrupt the output from such programs that are run underneath the Emulator you will have to use the C key Common PCDOS and CP M File System
44. LEAN VA 22101 BUILTIN COMMANDS Tue 11519 1985 Te 16416017 A gt exit Z80 A gt format a COMPUT ERWISE r CONSULTING S PCDOS PASS THROUGH ERVICE BOX 813 MCLI EAN VA 22101 BUILTIN COMMANDS EMULATED CP M BUILTIN S Builtin Changes the default disk drive to the drive whose letter name is represented by the d character The command prompt will change to Z80 d gt to reflect the new default Drive d s current PCDOS directory will then be the first directory searched for Z80 command COM files unless explicitly overridden by a drive prefix or pathname Data files that are created will default to that drive and its current directory Data files that are read will be searched for only in that drive and directory unless explicitly overridden by the Z80 program Example from an actual session Z80 A gt stat b Volume in drive B has no label Directory of B WORDSTAR lt DIR gt 11 02 85 4 19a 1 File s 89088 bytes free Z80 A gt dir b wordstar ws Volume in drive B has no label Directory of B wordstar WSMSGS OVR 27904 11 06 85 6 27p WSOVLY1 OVR 34048 11 06 85 6 30p WSU COM 15872 11 06 85 6 32p WS COM 15872 11 06 85 6 37p 4 File s 89088 bytes free Z80 A gt b Z80 B gt dir Volume in drive B has no label Directory of B WORDSTAR lt DIR gt 11 02 85 4 19a 1 Fil
45. OS unimplemented FFBO RET FFBA HALT BIOS unimplemented FFBB RET FFBC HALT BIOS unimplemented FFBD RET FFBE HALT BIOS unimplemented FFBF RET FFCO HALT BIOS unimplemented FFC1 RET FFC2 HALT BIOS unimplemented FFC3 RET FFC4 HALT BIOS unimplemented FFC5 RET FFC6 HALT BIOS unimplemented FFC7 RET FFC8 HALT BIOS unimplemented FFC9 RET FFCA HALT BIOS unimplemented FFCB RET FFCC HALT BIOS unimplemented FFCD RET FFCE HALT BIOS unimplemented FFCF RET FFDO HALT BIOS unimplemented FFD1 RET FFD2 HALT BIOS unimplemented FFD3 RET FFD4 rest reserved for scratch use COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 Appendix B Bugs and Future Appendix Plans B Bugs and Future Plans This section describes known bugs and otherwise strange Please help us to improve the product by sendi with as much detail as possible activity bug reports which demonstrate the bug Emulator ng us your own including programs These bugs will be fixed as time allows and user interest demands Issue The disassembly As the control table grows When disassembling poor disassembler is faced with a control table than 42K in size something bigger search most of th list command can becom the Model 100 s ROM table for quit disassembly speed decreases for instanc
46. Response Agreed We just don t have the memory left in the 64K Lattice code segment to do it right Maybe after some major rework Issue The Emulator s main program ought to be rewritten in Microsoft C version 3 0 This will speed it up consider ably and will make it a lot smaller Author s Respons Agreed The major effort is in reworking the assembler subroutines There are a lot of places where Lattice s calling convention and register usage is assumed Issue It would be nice to somehow state to the Emulator that what is in CP M memory is actually an 8080 or 8085 program This would allow the 8085 s RIM and SIM instruc tions for example to be properly disassembled instead of being misinterpreted as 480 relative jumps Author s Response Agreed The biggest obstacle to doing this is the same old bugaboo no memory left in 64K code segment Will put this off until we free up a couple of K in the code segment EAN VA 22101 COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLI Appendix B Bugs and Future Plans Issue The loading of Z80 COM files to be executed in fact any file load that is done directly or indirectly by the read command is just too slow Author s Response Agreed This should be redone to bypass Lattice C s slow I O routines This problem may go away if and when the Emulator is rewritten in Microsoft C
47. S They must be copied to standard PCDOS disk files We have used several approaches all with excellent results The first approach is to transfer the CP M files straight from the CP M disks to PCDOS disks using a utility that runs on the IBM PC and is capable of reading the foreign CP M format Such utilities include CONVERT from Selfware Inc Fairfax VA XENOCOPY from Vertex Systems Inc L A Calif This approach is nice when it works The major disadvantages are Only certain CP M formats are recognized by each of these utilities Apple and NorthStar Horizon CP M disks for INTRODUCTION example cannot be read on the IBM PC without special hardware You must have the CP M disks at hand Another approach is to transfer the CP M files to the IBM PC via a communications line This is Joan Riff s personal favorite If the CP M system is at hand then the two machines are direct connected and cranked up to 9600 baud If the CP M system is not handy then the transfer is made over the phone at whatever speeds the respective modems can handle In either case the CP M system running BYE and XMODEM is controlled by the IBM PC running Crosstalk VI version 3 5 from Micro Stuf and Joan Riff s excellent XMODEM with CRC Crosstalk RUN command When direct connected files really fly across at 9600 baud The major advantages of this approach are Wh
48. Supersoft s have proven to be inac curate Appendix B Bugs and Future Plans Issue There should be an option to allow pagination of disassembled object code Author s Response Agreed Will look into another list include option to specify pagination Issue Expressions are currently limited to and operators They should allow and also and maybe even AND OR XOR shifts etc Author s Response I disagree The amount of work involved isn t justified by the benefit Issue The Z80 IN and OUT instructions should have access to real 8088 I O ports on the IBM PC Author s Response Over my dead body COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101
49. The Emulator goes to great lengths to allow CP M programs to read and write PCDOS files Thus the PCDOS file system serves as a common environment for both PCDOS and CP M files This allows you to use your favorite IBM PC editor for example to edit source files that are then compiled within CP M using the Emulator with ASM COM M80 COM F80 COM or whatever CP M s User Number concept however is primitive compared to the directory structure available with PCDOS So although the emulated BDOS supports the setting of a user number the user number is ignored by the Emulator when it comes time to actually access files Likewise the concept of a Read Only disk drive is not necessary under the Emulator And the fatal CP M flaw that crops up when you change disks and forget to type C to Warm Boot the system has been virtually eliminated by PCDOS CP M and its CCP or lack of them COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 T THE CP M ENVIRONMENT One thing that we did in order to achieve such a large TPA size 65022 bytes and such fast emulation was remove the console command part of CP M the Console Command Processor or CCP from the CP M Segment In fact we did away with CP M entirely The CCP is the part of a normal CP M system which accepts commands from the user and processes them The Digital Research CCP that c
50. The actions of S Q P and Ctrl PrtSc may vary depending on the particular CP M application being run CP M s BDOS function number 6 Direct Console I O for example is handled by CP M without it checking for S or P The Emulator mimics this action Filenames CP M filenames may contain certain characters that PCDOS objects to In general don t use the or characters in filenames or the I O redirection characters gt and lt and so on And watch out for PCDOS device names that are perfectly innocent filenames under CP M Things like CON ASM will fool you COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 CP M ENVIRONME T NT This section describes th which your Z80 programs will run TE BIOS does When no with Emulator T terminal con using Mos displayable c screen for the user to read Other ASCII characters sequences are used not to display anything calls not apply an imaginary he Emulator trol the IB THE Emulated Terminal haracters but ay CP M t ASCII characters that are sent to th letters a Z80 program does character I O by calling BDOS functions emu BIOS calls lated ASCII terminal ENVIRONMENT nvironment set up by the Z80 program does character I O by invoking CP M then its input and output come from PCDOS
51. UR IO HENPOI PY ONE COUWOCOPACUHUUFRAO H PDP Fr Wt FI Hoong El w aoco w WoW ND o UNO NZ LO116 A 6 0 Let s dump l for what it does the thing and OB OC OD OE OF 01234567 89ABCDEF 02 CD 35 02 FE E M H M M5 06 01 FE OA D2 B gt 6V0 Z2 R CD 35 02 FE OD 2X 0 M M5 4F CA 47 O1 FE B5 gt N EJ G OJG 16 03 CD 40 02 NJG C 2 Z MQ 30 FE 07 CA 69 M5 BZ gt 8V0 7i 03 3A 58 03 FE Ji CJ 2Y X C2 83 01 3E OE By gt C7 B gt B7 01 FE 03 C2 C7 B gt C7 B Ol BE MOF C3 BT Seis GBISGET FE 06 C2 B5 OL Bt gt C7 B5 5A 03 FE 45 C2 gt C7 gt 2 X Z EB 01 3E 01 C3 D3 G gt CS OBQ gt CS CA EB 01 3E 60 gt 2Z Y Jdk gt 3E 20 32 5B 03 2 gt 2 Cu gt 2 06 3E 01 D3 06 gt 2 s gt S S gt S 44 D3 06 3E 03 S gt S Z FDS gt D3 06 3A 5B 03 S F S gt S D3 00 FB 11 3D F S gt GS X S 60 D8 D6 20 C9 M 1I M XVI 31 26 30020 66 Cave ENG GT Th Ot 30 OD OA OA OA or Xerox 820 73 3A OD OA 31 Baud R ates 1 36 30 30 20 20 9200 0 9600 20 OA 20 OD 53 20 3D 31 20 OA 65 20 20 32 3D 20 6C 20 32 30 20 31 65 20 OD OA 30 20 35 OD 31 30 63 74 20 20 3A 72 2 6C 20 38 6F 00 00 00
52. X IY T SR SP PC IFFL IFF2 IMF 0A01 OFBC 0100 FEFC 0000 0000 00 00 FEFC 013D 0 0 0 0055 0041 0000 0000 SF 0 ZF 0 HF 0 P V 0 NF 0 CF 1 LO13D 31 00 02 LD SP L0200 AF BC DE HL IX IY I R SP PC IFFL IFF2 IMF 0A01 OFBC 0100 FEFC 0000 0000 00 00 0200 0140 0 0 0 0055 0041 0000 0000 SF 0 ZF 0 HF 0 P V 0 NF 0 CF 1 LO140 C5 PUSH BC AF BC DE HL Ix FY EN Ri SP PC IFF1 IFF2 IMF 0A01 OFBC 0100 FEFC 0000 0000 00 00 O1FE 0141 0 0 0 0055 0041 0000 0000 SF 0 ZF 0 HF 0 P V NF 0 CF 1 LO141 G5 PUSH BC FI oO COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 T Builtin notrace n n n registers are not displayed af after the last instruction BUILTIN COMMANDS DEBUG SUPPORT Executes a certain number specified by the n argument of Z780 instruc tions beginning at the current Z80 Program Counter PC The 480 ter every instruction but are displayed If no argument is given then n defaults to 1 The n argument is a numeric va section lue as described at the beginning of this NOTE The PC of each executed instruction is saved in a circular buffer for later command q v Example Z80 A gt n 3 AE BE DE He Ta SEX 0A01 OFO9 0130 FEFC 0000 interpretation by the pc builtin IY T R SP PC IFF1 IFF2 IMF 0055 0041 0000 0000 SF 0 LFEFE 76
53. a PCDOS screen editor on a CP M source file and then return to the Emulator Use command to drop into DOS and exit to leave PCDOS and return to the Emulator This is also the primary way to take advantage of PCDOS s directory structure while within CP M You may issue CHDIR MKDIR and other directory related commands directly to PCDOS The effect of such commands carries over to the Emulator COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS PCDOS PASS THROUGH Example from an actual session Z80 A gt cd foo Z80 A gt cd Z80 A gt rd foo Z80 A gt chkdsk b 362496 bytes total disk space 1024 bytes in 1 directories 272384 bytes in 10 user files 89088 bytes available on disk 423936 bytes total memory 152384 bytes free Z80 A gt md foo Z80 A gt cd foo Z80 A gt stat Volume in drive A has no label Directory of A foo lt DIR gt 11 19 85 Tei 5a PE lt DIR gt 11 19 85 1 15a 2 File s 144384 bytes free 280 A gt command The IBM Personal Computer DOS Version 2 00 C Copyright IBM Corp 1981 1982 1983 Tue 11 19 1985 1 16 00 18 A gt chkdsk 362496 bytes total disk space 1024 bytes in 1 directories 217088 bytes in 17 user files 144384 bytes available on disk 423936 bytes total memory 149264 bytes free COMPUTERWISE CONSULTING SERVICES P O BOX 813 MC
54. a av av av a a J i al 1 A 1 al a 1 gt J S al a 4 1 1 1 a J R 1 1 J ES 1 a al OFFC6 OFFC8 OFFCA OFFCC OFFCE OFFDO OFFD2 BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BIOS BLOS ted ted ted ted unimplem unimplem unimplem unimplem u u u B 858 ted nted nted nimplem nimplem nimplem 0 DDDDDOD 5 COLD BOOT hook WARM BOOT hook console status console input console output list output punch output reader input home disk select disk set track set sector set DMA address read sector write sector list status unimplemented unimplemented unimplemented unimplemented Appendix A Layout of CP M Segment FFA8 HALT BIOS unimplemented FFAS RET FFAA HALT BIOS unimplemented FFAB RET FFAC HALT BIOS unimplemented FFAD RET FFAE HALT BIOS unimplemented FFAF RET FFBO HALT BIOS unimplemented FFB1 RET FFB2 HALT BIOS unimplemented FFB3 RET FFB4 HALT BIOS unimplemented FFBS RET FFB6 HALT BIOS unimplemented FFB7 RET FFB8 HALT BI
55. ample the following PCDOS command can be used to ator output to file OUTPUT DOC Emu I and capture all Z80MU gt OUTPUT DOC You may also append output to an existing file with Z80MU gt gt OUTPUT DOC And the following can be used to have the commands from the file INPUT BAT Z80MU lt INPUT BAT You may combine input and output redirection Z80MU lt INPUT This is perfect for automating Emulator s output to a file document There are a few First of all The main program acts like the CP M CCP subject to I O redirection m The actual Z80 emulator The CP M level so BIOS emulator BAT gt OUTPUT DOC the Emulator I O goes through th mula ted and then straight to the IBM PC screen does not apply there COMPUT ERWISE CONSULTING S ERVICE BOX 813 as follows run the Emulator Emulator read all of its Some of the samples displayed later in this document were captured by redirecting the things to bear in mind however which does no I O a It does I O at the IBM PC ROM PCDOS never sees what s going on terminal inside t remember that there are several parts of the which reads your commands and in general It does all I O via PCDOS b t CP M BIOS Ne Emul and then editing that file into this ator so it is BIOS te
56. an be used quite transpar ently to run CP M applications on the IBM PC It contains many advanced commands not found in CP M but there s no law that says that you have to use em all By ignoring the advanced commands you can run the emulated CP M all day long and you ll swear that you re running CP M You can also take advantage of the advanced commands and features and have a user interface more powerful than that available with CP M Advanced Z80 programmers can even ignore CP M entirely and use the Emulator as a generic Z80 development tool for developing device controllers and other non CP M based Z80 code INTRODUCTION At CCS we use the Emulator to develop things like Z80 based hard disk controller card software device switching hardware and even a few boring old standard CP M applications We have also used it to regen erate the source code for the 32K ROM laptop computer to figure out how it works m Why Did We Do It At CCS we have quite an inves that are hard to find in the II develop software for the Z80 The ol nowadays it is used more in controll processor We wanted to keep these 480 tools development process he Emulator consists of a high speed in the Radio Shack Model 100 8088 assembler subroutine which does the actual Z80 emulation and a C language main program which provides the CP M like interface to the user the
57. ated with the various CP M addresses Format control clear c clear This format of the command clears out the control table so that nothing is known about the Z80 object code No CP M addresses control breaks labels or comments are defined after this command is given Format control read lt filepath gt c read lt filepath gt This format of the command causes the Emulator to read a control table from the specified filename The file must have been created by a control write lt filepath gt command A currently defined control table is cleared before the new one is read from disk It is not possible to merge control tables using this command COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS RESOURCE FACILITY COMMANDS Format control write lt filepath gt c write lt filepath gt This command writes the current control table to the specified file for later input via the control read lt filepath gt command All known data is written CP M addresses control breaks labels and comments Format control n i Ss ice b wItl cn i b w t si c This format of the command is the real workhorse of control table maintenance It associates a Z80 data type with CP M address n which is a numeric value as defined at the start of this section The argument following CP M address n is a directive
58. bel 7ff program end 280 A gt 0 warm boot jump Z80 A gt 5C FCB1 Z80 A gt 5 BDOS Z80 A gt label autogen 100 7ff NOTE The next section contains a sample which generates source code from object code more detail about this and related Resource COMPUTERWISE CONSULTING S ERVICE 16 bit li be ignored There s no way short the 16 bit value is meant to value 1 ike a loop counter tor there were too many 16 bit literals Now it is ticular 1 6 bit I literal th it Specifically the terals are ignored BOX 813 Emulator session Refer to it for commands MCLEAN VA 22101 BUILTIN COMMANDS RESOURCE FACILITY COMMANDS Builtin comment n text on text Associates source code comment text with CP M address n which is a numeric value as defined at the start of this section text may be up to 254 characters long If text is absent then any existing comment associated with address n is simply deleted Note that text must be enclosed in double quotes It may include scape sequences as follows Single char NO NUL byte b or B Backspace char Ve Or NI Tab char n or NN Linefeed char r or NR Return char Single quote char vr Double quote char NXFF or XFF Byte with HEX value FF Thes scape codes made be used to make the comment more rea
59. cified by the HEX records In such a case the n argument may have no meaning The n argument is a numeric value of the sort described at the beginning of this section NOTE If a read of a file causes data to be read below 0100h or above FDOOh then the CP M environment will be clobbered If you re developing non CP M Z80 code then who cares If you re reading in a file that expects to call CP M however then running the thing with a clobbered CP M environment just might scramble the brains of the imaginary 280 This command is used by us at CCS to load test versions of our 480 software which we leave in HEX format when we run L80 Example Z80 A gt read 100 820init com Low 0100H Next 0380H xxx 780 DMA PC and Stack automatically set for COM file Z80 A gt write 100 360 820init hex Writing HEX records for 0100H thru 0360H 609 bytes to file 820INIT HEX Z80 A gt read 820init hex x HEX file Starting Address 0100H Low 0100H Next 0360H COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS CP M ENVIRONMENT CONTROL Builtin write nlow nhigh lt filename typ gt w nlow nhigh lt filename typ gt Write a block of CP M memory to a disk file The bounds of the block to be written are specified by nlow and nhigh which are numeric values as described at the start of this section
60. control the screen cursor by sending control characters through the BDOS For these programs you may want to have the PCDOS ANSI SYS device driver loaded via your CONFIG SYS fides How Accurate an Emulation There are two aspects to the accuracy of the Is It Emulator emulates the Z80 emulates CP M 1 How accurately it 2 How accurately it The Emulator emulates the emulation of all six fl Z80 almost perfectly bits i ag able Half carry and Add Subtract Emulator ignores the execution Register Input Output instructions the IBM PC So the actual setup auto increment of the IN s and OUT s the actual strobe of the I O data code accessing I O addresses that even for the IN s and OUT s The Z80 HALT instruction C program and as a cal When it came to emulating weren t interested in emul include builtin largest possible TPA La is used as a hook to re l to the emulated CP M CP M 2 2 n the Flags Register flag bits are emulated For faster the two unused bits in the Flags so these will not act exactly as they would on a real 480 lines mean something entirely different on data transfer has been disabled registers ting the limitations of CP M We wanted many of the benefits of PCDOS commands than were available with CP M We also demanded Transient Program Area the amount of memory even do
61. d output 07 07h Get IOBYTE to A reg 08 08h Store E reg into IOBYTE 09 09h Output string at DE to PCDOS standard output 10 0Ah Input line from PCDOS standard input to DE 11 0Bh Set A reg to FFh if char from PCDOS standard input is ready to be read or 00h if not 12 0Ch Return CP M version to HL Sets reg L to 22h for CP M version 2 2 and reg H to OOh 13 0Dh Reset disk system Sets DMA to 80h Does not change selected drive to A like CP M does as this is not necessary with PCDOS 14 0Eh Set default drive to E reg 15 0Fh Open file whose FCB is at DE Sets A reg to 00h if successful else to FFh 16 10h Close file whose FCB is at DE Sets A reg to 00h if successful else to FFh 17 11h Search for first file that matches pattern in FCB at DE Sets A reg to 00h if successful else to FFh 18 12h Search for next file that matches last pattern used Sets A reg to 00h if successful else to FFh 19 13h Delete file s represented by FCB is at DE Sets A reg to 00h if successful else to FFh 20 14h Read next sequential record from file whose FCB is at DE Sets A reg to status as follows 0 successful 1 reading unwritten data EOF FFh PCDOS returned error 2 No room in DTA for record Note that a short record is filled out by the Emulator with Z eof characters COMPUTERWISE CONSULTING SERVICES P O
62. dable When a comment is detected by the disassembler it will be printed in one of two places As a line comment after the mnemonic Such a comment replaces the flags comment field if present If text starts with other than a n escape then the comment is printed in this manner As a multi line comment on lines before the instruction If text starts with a n escape then the comment will be printed in this manner Blank comment lines starting with are automatically provided before and after the comment and characters are inserted after every n or Nr found in the text string If you want to create a nice looking multi line comment then imbed n escapes as line delimiters and t escapes to line things up on succeeding lines COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS RESOURCE FACILITY COMMANDS If your comment is intended to be a single line comment appended to the disassembled instruction s mnemonic then avoid imbedded n and Nr escapes Example Z80 A gt comment 100 nStart of main program Z80 A gt 0 Jump to BIOS Warm Start Z80 A gt 100 Z80 A gt comment ff00 nBIOS Jump Table n n t3 bytes per JMP NOTE The next section contains a sample Emulator session which generates source code from object code Refer to it for more detail about this and related R
63. e It may have ach memory refere pokey the that is to nce This yields a disassembly speed of a line or two a second Boo The control from a sequential to an indexed method Author s Respons Agr release Issue Some commands CP M addresses around the high end of the 64K CP M segment table search routines should be changed d Will rewrite these for next notably those that accept a range of get confused if they are asked to wrap Author s Respons Have applied fixes for most glaring problems Would appreciate specifics i e what commands fail and how to help track down the rest Issue Internal I O redirection effected by the Emulator not PCDOS should be available for any Emulator command not just the list command Author s Respons Agreed Will look into it COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 Appendix B Bugs and Future Plans Issue The patch command ought to allow multiple entries per line and ought to accept arguments on the patch command line without dropping into interactive patch mode Author s Response Have provided left handed solution by allowing a patch string on same line as patch command True fix with multiple byte values as independent args on command line will take a while to implement Issue The Emulator lacks a mini assembler It needs one Author s
64. e s 89088 bytes free BUILTIN COMMANDS EMULAT Z80 B gt stat a exe Volume i Directory of A Z80MU EXE 1 File s D CP M BUILTIN S n drive A has no label 94976 11 18 85 3 31p 142336 bytes free COMPUTERWISE CONSULTING SERVICES BOX 813 MCLI EAN VA 22101 Builtin del lt pattern gt era lt pattern gt delete lt pattern gt erase lt pattern gt These are identical DEL command to del See the PCDOS manual We have created sev commands All cause lete files that match for details of lt pat Example ral synonyms for the life easier for CP M folks who are used folks who are used to saying DEL or whatever Z80 A gt erase b asm Z80 A gt del Are you sure y 280 A gt delete c backup foo Z80 A gt era foo asm BUILTIN COMMANDS EMULATED CP M BUILTIN S the invocation of the PCDOS lt pattern gt tern gt same command in order to make to saying ERA and PCDOS These commands cause PCDOS to reload COMMAND COM so see The PCDOS Environment section for further detail on that subject COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS EMULATED CP M BUILTIN S Builtin dir lt pattern gt stat lt pattern gt Shows a directory of files matching
65. e screen and reading from the keyboard The Emulator is slower as a result But we gain a few conveniences as a result We achieve something closer to true CP M emulation cause PCDOS automatically handles P and S Q in a manner close to CP M s handling of them We get automatic I O redirection We get PCDOS expanding macro keys and interpreting function keys The F3 key for instance can still be used to repeat the last command entered to the Emulator The ESC key cancels the current input line And Fl recreates the last command one character at a time Other PCDOS keyboard conventions like Ctrl NumLock Ctrl PrtSc and so on are also handled by PCDOS in a way that we re all used to The addition of keyboard enhancers like CED and Sidekick can confuse things so that the function keys don t act quite right You ll just have to experiment with it If you want to copy screen output to the printer then press P or Ctrl PrtSc A second press will turn printer echo off Remember that such PCDOS redirection applies to Emulator output like dumps disassem blies etc as well as to the output of any CP M applications being run under the Emulator that use BDOS functions for output T THE PCDOS ENVIRONMENT E If text is scrolling off of the screen too fast to read not real likely with PCDOS being as slow as it is you can pause and restart it with S Q or Ctrl NumLock
66. e will gladly emulate these functions in the next releas BDOS routines call the BIOS routines This is not true in Emulator corresponding PCDOS functions BIOS routines PC ROM ERWISE The Emulator s BDOS functions in general and the Emulator s BIOS BOX 813 ERVICE CONSULTING S invoke the routines call the MCLEAN VA 22101 EMULATOR BUILTIN COMMANDS BUILTIN COMMANDS This section describes those commands that are recognized and acted upon by the Emulator itself Such commands do not involve a search of the disk for a corresponding COM file since the Emulator recognizes them as special commands which are to be handled within the Emulator itself This process is roughly equivalent to the handling of CP M s CCP commands Command Name Conflicts You may have a COM Z80 command file that has the same name as one of these Builtin Commands How do you tell the Emulator to run your COM file instead of doing its corresponding Builtin Command All that you have to do is convince the Emulator that your command is indeed a disk file This can be done by including a drive ID or pathname as part of your command Z80 A gt a dump foobar asc Z80 A gt b bin dump foobar asc Z80 A gt mystuff dump foobar asc Alternatively you may want to rename your COM file so that it no longer conflicts with an Emulator Builtin Comma
67. ecuted DDT would then see FOO COM in both the first FCB at 5Ch and as a raw command tail at 80h Example from an actual session Z80 A gt args testfile001 file0002 Z80 A gt d primary fcb secondary fcb 15 ADDR 00 01 02 03 04 05 06 07 08 09 OA OB OC OD OE OF 01234567 89ABCDEF Fl 0050 00 54 45 53 TES 0060 54 46 49 4C 45 30 30 31 00 00 00 00 00 46 49 4C TFILEOOL FIL 0070 45 30 30 30 32 20 20 20 00 00 00 00 E0002 Z80 A gt d 80 9f ADDR 00 01 02 03 04 05 06 07 08 09 OA OB OC OD OE OF 01234567 89ABCDEF 0080 15 20 54 45 53 54 46 49 4C 45 30 30 31 20 46 49 TESTFI LEOOL FI 0090 4C 45 30 30 30 32 0D 00 00 00 00 00 00 00 00 00 LE0002 E 280 A gt args foo c n b v FI AN VA 22101 Z ADDR 0050 0060 0070 Z ADDR 0080 0090 COMPUT BUILTIN COMMANDS CP M ENVIRONM ENT CON TROL 80 A gt d primary fcb secondary fcb 15 00 01 02 03 04 05 06 07 08 09 OA OB OC OD OE 00 46 4F 20 20 20 20 20 43 20 20 00 00 00 00 00 2D 4E 20 20 20 20 20 20 20 20 00 00 00 00 80 A gt d 80 9f 00 01 02 03 04 05 06 07 08 09 OA OB OC OD OE OF 20 46 4F 4F 2E 43 20 2D 4E 20 2D 42 20 2D OD 45 30 30 30 32 0D 00 00 00 00 00 00 00 00 ERWISE CONSULTING SERVICES P BOX 813 MCLI OF 01234567 4F 20 G OF 01234567 0 FOO Ac 00 E0002 EAN
68. ent disk in this case rive A for a file by the hen it loads it into the CP M Segment and runs it name of ASM COM If it finds such a file the current drive then the Emulator directories looking for a file with the right name ASM COM The directories are searched in the order that they appear in the Z80PATH s is the one loaded and run tring The first ASM COM file that is found If there is no Z80PATH string defined in the PCDOS environment then the search stops with the current disk drive s current PCDOS directory If no matching filename is found after all of this then the Emulator echos the command line asm a T THI PCDOS ENVIRONMI E indicating that it doesn t know what you mean Z80 A gt b asm dump In such a case Note that no search takes place if the command is qualified A qualified command includes a drive ID or a pathname such as aaz Z80 A gt bin asm dump aaz the Emulator tries only once to open the Z80 COM file given If such a file cannot be found then the using the exact name command fails as men The AUTO X EC Z80 File When the following command Emulator firs tioned above starts up it automatically executes the Z80 A gt SUBMIT AUTOEXEC Z80 If there is no file by the name of AUTOEXEC Z80 in the current directory when the Emulator is run
69. esource commands COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 USING THE RESOURCE BUIL USING THE TIN COMMANDS DI ESOURCE BUILTIN COMMANDS This section presents an example of re sourcing a piece of 280 object code It demonstrates t that deal wit he use of the various Emulator builtin commands h regenerating source code from object code We were recently presented with a piece of software which wouldn t you know it existed only i owner of this little ut Hyperion system cause n object form on a Xerox 820 CP M system The ility really wanted to move it to a 16 bit Hyperion has an SIO the utility sets up a 280 SIO and that s what the So he was wondering could we regenerate the source code for this little utility Z80 KkK KK Z80 Z80 NOTE The first step is to read the thing into 280 memory with the Emulator breaks and clear any previous resource control C gt read 100 820init com Low 0100H Next 0380H Z80 DMA PC and Stack automatically set for COM file C gt control clear C gt list include addresses opcodes COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 USING THE ESO URCE BUILTIN COMMANDS The next thing to do is take a quick look at t
70. eturns A reg status as follows 0 successful a reading unwritten data ne Emulator ignores this byte when accessing files E Read random record from file whose FCB is at DI 3 CP M Cannot close current extent error PCDOS returned error 2 No space in DTA for record Note that a partial record is filled out by the with Z eof characters ERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 Emulator THE In CP M the the IBM COMPUT CP M ENVIRONMENT 34 22h Write random record to file whose FCB is at DE Returns A reg status as follows 0 successful 3 CP M Cannot close current extent error PCDOS returned error 2 No space in DTA for record 5 CP M Directory Overflow error Diskette full 35 23h Compute file size for file whose FCB is at DE Result goes into random record field of FCB 36 24h Set random record field per FCB at DE 37 25h Reset drive accepted but ignored 38 26h unsupported aborts Z80 program 39 27h unsupported aborts Z80 program 40 28h Write random record with zero fill In the Emulator this is translated to a function 34 22h above NOTE If someone will kindly provide us with a coherent writeup of the disk parameter block and allocation information as returned by BDOS functions 31 1Fh and 27 1Bh above then w
71. files cannot be nested as defined by PCDOS when EOF is If a keypress is detected during submit file processing when the is running Example Z80 A gt submit script Z80 A gt sub c cpm autoexec z80 COMPUT RWISE r CONSULTING S outside of Z80 operation expecting a command is ERVICE i e Emulator is then the submit file is aborted This how you cancel a submit file just press SPACE while it sub c cpm autoexec z80 BOX 813 MCLI EAN VA 22101 Builtin list nl n2 gt outfile list prologue nl n2 list include A 0 F 1 nl n2 gt outfile include A O F BUILTIN COMMANDS RESOURCE FACILITY COMMANDS gt gt outfile gt outfile gt gt outfile gt gt outfile prologue nl n2 gt outfile gt gt outfile This is a multi purpose disassembly command things depending upon the arguments that are present Lists disassembled Z80 object code Generates an assembler prol object code second form Specifies fields to be incl form Format list nl n2 gt outfile l nl n2 gt outfile This form causes the disassembly o which does one of three first form logue for the given range of 480 uded in disassembly lines third gt gt outfile gt gt outfile f Z80 object code from CP M address nl through CP M address n2 both of which
72. has no label Directory of B WORDSTAR lt DIR gt 11 02 85 4 19a 1 File s 89088 bytes free Z80 B gt stat a exe Volume in drive A has no label Directory of A Z80MU EXE 94976 11 18 85 3 31p 1 File s 142336 bytes free COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 m 4 m ct Builtin BUILTIN COMMANDS EMULAT iD CP M type lt filename typ gt ty lt filename typ gt CTRL BREAK Example BUILTIN S his command is the equivalent of the CP M TYPE command The specified file is displayed on the standard output normally the screen he display may be paused with either the CP M convention of S Q or he PCDOS convention of CTRL NUMLOCK It may be aborted with C or This command causes PCDOS to reload COMMAND COM so see The PCDOS Environment section for further detail on that subject Z80 A gt ty b foo asm Z80 A gt type source backup foo doc Z80 A gt ty ctest err COMPUT ERWISE r CONSULTING S ERVICE BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS SIMILAR TO CP M S Builtin rename lt oldpath gt lt newpath gt ren lt oldpath gt lt newpath gt Renames the file specified by lt oldpath gt to the name given by lt newpath gt NOTE This is not the same syntax used by the CP M equivalent which is REN lt newname gt
73. hat you talk to the guy that emulates CP M Console Command Processor Z80 Emulation 8088 Assembler Code Which actually emulates the Z80 as it executes in the CP M Segment 64K CP M Segment In which the Z80 code is held as it executes The size of the Transient Program Area is 65022 bytes BDOS and BIOS hooks Which trap CP M BIOS and BDOS calls so that they can be emulated The main program accepts the user s commands and processes them When and if it comes time to run a Z80 program the Z80 code is loaded into the CP M Segment and the 8088 assembler code which actually emulates the Z80 is called to run the program there As the Z80 program executes it accesses the outside world via calls to the BDOS and BIOS hooks The code that is executed for a given BDOS or INTRODUCTION emulates the Z80 What The is allocate 64K So you had better hav Emulator runs on the II itself is about 93K in size 93K Does It Require To Run Emulator versions of the t 64K BM PC under PCDOS 2 x or above The first thing that it does when it runs to be used as CP M memory BIOS function actually resides within the 8088 assembler code that The Emulator the CP M Segment 157K available when you run the Note that the amount of memory required may vary as improved Emulator are released Some CP M applications expect to
74. he promising LD CALL DE LO245 CALL 10240 E LO2C8 10240 CALL 10235 CP JP LD SUB 07 C8 30 02 CA 32 01 4A B7 W FNM oOo amp mQQowoovwvunsnnmHo o ousAEKRKHREPIOENI OR w Fi OQ wW w Owo OoUP AP aN FO 09 CD 00 40 01 03 38 32 FE OC C2 B7 03 C2 F5 06 03 3E 58 00 54 38 74 NOTE program and get a general f Z80 C gt list LO100 11 45 02 L0103 CD 40 02 LO0106 11 C8 02 10109 CD 40 02 LO10C CD 35 02 LO1OF FE OD LO111 C2 16 01 LO114 3E 36 LO116 D6 30 NOTE This isn t real look for obvious ASCII strings 280 C gt d 100 37f ADDR 00 01 02 03 04 05 06 0100 11 45 02 CD 40 02 11 0110 OD C2 16 O1 3E 36 D6 0120 06 01 32 58 03 11 EF 0130 C2 35 01 3E 4E FE 45 0140 4E CA 47 01 C3 25 01 0150 CD 35 02 FE OD C2 5A 0160 01 FE 08 CA 69 01 C3 01 70 00 C2 79 01 35 OF C3 0180 C3 B7 01 FE 02 C2 8D 0190 97 01 3E OA C3 B7 01 O1A0 01 FE 05 C2 AB 01 3E 01BO0 3E 05 C3 B7 01 3E 02 OLEDE CH O01 368 03 03003 01 01D0 01 3E 00 32 5A 03 3A O1EO 32 5B 03 3E CO 32 5C O1FO 3E 40 32 5C 03 F3 3E 0200 AF D3 06 3E 04 D3 06 0210 D3 06 3A 5C 03 C6 01 0220 C6 8A D3 06 3E 47 D3 0230 03 CD 40 02 C9 OE O1 0240 OE 09 C3 05 00 1A 49 0250 6F 72 20 58 65 72 6F 0260 OD OA 42 61 75 64 20 0270 39 32 30 30 20 3D 20 oO J OA
75. hen th mulated CP M BIOS routines that deal with the console will not emulate anything They will simply act as if the equivalent CP M BDOS function had been called This means that CP M BIOS terminal I O will go to PCDOS for handling This makes it available for PCDOS I O redirection It also allows a PCDOS emulator like ANSI SYS to become the CP M terminal emulator If no argument is specified then the current state of emulation is simply reported Example Z80 A gt term Terminal Emulation is OFF CP M BIOS console goes to PCDOS Z80 A gt terminal on Terminal Emulation is ON via CP M BIOS Z80 A gt terminal off Terminal Emulation is OFF CP M BIOS console goes to PCDOS COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS CP M ENVIRONMENT CONTROL Builtin read n lt filename typ gt r n lt filename typ gt Reads data from specified file into the CP M Segment at address n If n is absent then it defaults to 0100 This is the primary method used to load Z80 software for debugging It is normally used to read Z80 command COM files into memory but this command will also read raw data files with no problem If lt filename typ gt has a filetype of HEX then the file is assumed to be in standard Intel HEX format and is loaded into memory at addresses spe
76. hould make sure that PCDOS s COMMAND COM file is in a RAMdisk or on a hard disk You can tell PCDOS where to find COMMAND COM by using the SET COMSPEC command in your AUTOEXEC BAT file Certain versions of PCDOS 2 0 and 2 1 and maybe others have trouble obeying the COMSPEC command They try to reload COMMAND COM from the boot disk regardless of the current COMSPEC parameter If you use one of these versions of PCDOS then you may avoid problems by keeping COMMAND COM always available on the boot drive Alternatively you may apply one of the public domain COMZAP patches to fix your copy of PCDOS The Z80PATH Environment String The Emulator has a facility which is equivalent to the PCDOS PATH command It allows you to tell the Emulator where to look for Z80 command COM files This facility is implemented by a new PCDOS environment string called Z80PATH This string is a list of fully qualified names of directories which are to be searched when the Emulator is looking for a COM file to load and run The various directory names must be separated with semicolon characters as follows COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 THI Fl E PCDOS ENVIRONMENT SET Z80PATH c cpm c z80 mystuff c This example tells the Emulator to search for Z80
77. ive cpu speed of at least 1 MegaHertz and still have all of the subtleties like flag updating performed with 100 accuracy One solution is to run the Emulator on an IBM PC AT with a hard disk This is perhaps the best solution but doesn t help those who don t have access to an AT An alternative solution is to use the NEC V20 processor chip in the IBM PC and get rid of the Intel 8088 The NEC V20 is a tad faster than the 8088 More importantly it performs full speed hardware emulation of the Intel 8080 chip Many CP M utilities do not use th xtended instruc tions offered by the 280 and will run just fine on an 8080 chip Such a hardware based emulator would offer superior speed It would however be limited to 8080 operation We are developing such an emulator There is no firm release date In the meantime you should equip your IBM PC with a NEC V20 chip to speed things up We paid 16 apiece for ours and there is no more cost effective hardware upgrade for the IBM PC See the ads in back of BYTE magazine for sources and prices How Do I Get My CP M Programs Into The IBM PC Assuming that you want to emulate some CP M applications on the IBM PC the first realization is that these CP M files don t already reside on the PC What s more they currently exist by definition on disks formatted for CP M not for the IBM PC So they can t be read by a vanilla IBM PC using PCDO
78. le that is invoked by typing its name is automatically run It does not require this command in order to be executed Example Z80 A gt go Z80 A gt g 100 Z80 A gt g 768 Z80 A gt go fixit5 3 COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 T BUILTIN COMMANDS DEBUG SUPPORT Builtin find n text fon text Searches the CP M Segment for the binary pattern represented by string text The search begins at Z80 address n which is a numeric value as described at the start of this section The text string may and usually does include imbedded escap sequences as follows single char NO NUL byte Nb or B Backspace char VE Or NT TAB char n or NN LINEFEED char Nr or NR CARRIAGE RETURN char single apostrophe char DUN single double quote char xFF or XFF byte with HEX value of FF EH x The CP M Segment address of each match is displayed as a four digit HI value The search ends with CP M Segment address OFFFFh Example from an actual session Z80 A gt patch 8000 Joan Riff Z80 A gt find 100 Joan 8000H Z80 A gt f 256 xcd x05 x00 O15EH 016BH O19EH O1CAH 01D6H COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLI FI AN VA 22101 T BUILTIN COMMANDS DEBUG SUPPORT Builtin
79. ly set ERVICES P O BOX 813 MCLEAN VA 22101 Builtin Dumps 280 dump d nl BUILTIN COMMANDS n CP M If nl is given present If n2 is given If n2 is not given then the first address dumped is nl T DE 1 n2 n2 memory BUG SUPPORT in HEX and ASCII then the dump continues through 280 starting address If no arguments are then the first address is the one following the last one done by a previous dump command CP M address n2 then n2 is assumed to be 255 bytes beyond the A lengthy dump may be interrupted by pressing the SPACE bar Example from an actual session Z80 A gt dump 100 ADDR 00 01 02 03 04 05 06 07 08 09 OA OB OC OD OE OF 01234567 89ABCDEF 0100 21 00 00 39 22 15 02 31 57 02 CD Cl OL FE FF C2 9 1 W MA B 0110 1B 01 11 F3 01 CD 9C 01 C3 51 01 3E 80 32 13 02 s M CQ gt 2 0120 21 00 00 E5 CD A2 01 El DA 51 01 47 7D E6 OF C2 eM a ZQ G f B 0130 44 01 CD 72 01 CD 59 01 OF DA 51 01 7C CD 8F 01 D Mr MY ZQ M 0140 7D CD 8F 01 23 3E 20 CD 65 01 78 CD 8F 01 C3 23 M gt XM C 0150 01 CD 72 01 2A 15 02 F9 C9 E5 D5 C5 OE OB CD 05 Mr y IeUE M 0160 00 Cl D1 El C9 E5 D5 C5 OE 02 5F CD 05 00 C
80. n from BDOS COLD BOOT vector WARM BOOT vector console status console input console output list output punch output reader input home disk select disk set track set sector set DMA address read sector write sector list status unimplem unimplem unimplem nimplem nimplem nimplem nimplem nimplem nimplem nimplem nimplem nimplem nimplem nimplem nimplem nimplem nimplem unimplem unimplem ted ted ted ted ted ted ted ted ted ted ee ee 0 B 88888888 n ted ted ted ted ted ted ted ted ted on GG GG BB 898888 je MDE RD MEDEE EE Appendix A Layout of CP M Segment FF69 FF6C FFOF FF72 FF75 FF78 FF7B FF80 FF81 FF82 FF83 FF84 FF85 FF86 FF87 FF88 FF89 FF8A FF8B FF8C FF8D FF8E FF8F FF90 FFOL FF92 FF93 FF94 FF95 FF96 FF97 FF98 FF99 FF9A FF9B FF9C FF9D FF9E FFOF FFAO FFAL FFA2 FFA3 FFA4 FFAS FFA6 FFA7 C 4 a E 5 1 E 5 ah C 4 J 1 C 5 1 C 1 3 J E 3 C 5 J E a La 4 J G 5 J E 5 J E 4 J C 5 J E 5 1 C 4 J C J E 3 al Hr Hr Hr HD Ar Hr Er Hr Hr Hr Hr EA Hr Hr Hr AH Hr Hr EP EGP Cy Cy Sy Gy GE EG lt W v
81. nd name Numeric Arguments Some Builtin Commands accept numeric arguments These may represent addresses to be dumped the number of pages to save or whatever A numeric argument may be entered in any of several ways As a HEX number No prefix is required in this case as this is the default numeric radix EMULATOR BUILTIN COMMANDS Examples ffff 0 TF 5 3FF As a decimal number prefixed by a period Examples 10 0 el 256 65022 As a binary number prefixed with the percent sign 3 Examples 0 1010101011110000 1 As an ASCII character prefixed by the apostrophe Examples A 10 Z As an ASCII escape sequence prefixed by an apostrophe and back slash Examples ENA single char NO NUL byte Nb or B Backspace char FN OG ANT TAB char rym or N LINEFEED char r or NR CARRIAGE RETURN char DEG single apostrophe char TM single double quote char xFF or XFF byte with HEX value of FF As a label which has been defined with the label builtin command Examples fcbl program start BDOS reserved As two or more of the abov ntries connected with or operators Examples fobl 5 program end table length A 40 a table 5toffset COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101
82. nterrupt the way it was before If the Emulator never gets a chance to exit gracefully then it never gets a chance to restore this interrupt The thing is left pointing to now dead code somewhere in the IBM PC s memory This is bad news for you and good news for that big red switch on the side of your PC I COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 INTRODUCTION Why might the Emulator abort Well there is always the possibility of an Emulator bug that we haven t found But the most likely reason is a disk error that results in the familiar message Abort Retry Ignore If you select Abort then you ve just aborted the Emulator and left the BREAK interrupt in limbo So reboot to be safe COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 T THE PCDOS ENVIRONMENT E THE PCDOS ENVIRONMENT The Z80 Emulator runs as a normal application program under PCDOS version 2 0 and above There are a few things that you should keep in mind in order to get the most out of the Emulator PCDOS s use of COMMAND COM Certain Emulator commands dir xxxxxx etc are handled by calling PCDOS to perform the associated operation The first thing that PCDOS does when called in this way is reload its COMMAND COM file from disk To speed things up you s
83. o cares what the CP M disk format is If the CP M system can read its own files then we can get them This works very well when transferring Apple and NorthStar Horizon CP M files Public Domain CP M software can be gathered just by dialing into a CP M Bulletin Board or RCPM system You need never know what hardware system is on the other end CP M and PCDOS files are similar enough that we have never had to alter a file that was transferred using either of the above two approaches We just download the files to the IBM PC and run em under the Emulator The biggest problem is remembering which files are PCDOS files and which are CP M files If you transfer a CP M file called DUMP COM for example from a CP M system to the IBM PC s disk you really do want to r I emember that it is a CP M file to be run with the Emulator and not an BM PC COM file If you accidentally invoke DUMP COM from PCDOS you will be unpleasantly surprised The CP M DUMP COM file contains 280 opcodes which will be executed by the IBM PC as 8088 opcodes Time to reach for the Big Red Switch You must run such CP M command COM files under the Emulator At CCS we keep things straight by storing CP M files under separat PCDOS directories The Z80PATH environment string explained else where makes this particularly convenient COMPUTERWISE CONSULTING SERVICES P O BOX
84. ode suitable for inclusion at the front of a 280 source file The generated source code is the prologue for a given block of Z80 object code defined by CP M addresses nl and n2 Both nl and n2 are numeric values as defined at the start of this section The generated prologue contains equates for the various ASCII control characters Additionally it contains equated labels for any CP M addresses that are referenced by the specified block of 480 code from nl to n2 but not contained within it Such a prologue is generally needed at the front of any sizeable 480 disassembly The generated prologue is sent to gt outfile or appended to gt gt out file the specified output file If an output file is not specified no gt character present then the generated prologue goes to the standard output as defined by PCDOS normally the screen Format list include A 0 F 1 include A 0 F Specifies the fields to be included in disassembled 4280 instructions If the A arg is present then CP M addresses will be included at the left of disassembled instructions If the O argument is present then raw opcodes will be included after the address if present but before the Z80 mnemonic If the F argument is present then the disassembled Z780 instruction will include a comment explaining the instruction s possible effect s on the 280 flags Arguments after include
85. of salt What it means is that if you had a real Z80 running the exact instruction mix found in the test program then that real Z80 would have to run at the reported clock speed in order to perform as fast or slow as the Emulator s imaginary Z80 For example assume that the reported effective clock is 250 000 Hz This means that the imaginary Z80 in the Emulator is running the test program at one fourth the speed of a 1 MegaHertz Z80 as found on a Microsoft SoftCard in an Apple for example on ighth the speed of a 2 MegaHertz Z80 etc Does this mean that your CP M programs run under the Emulator will run at one fourth the speed of an Apple with a SoftCard Not necessarily The reported speed is for CPU bound no I O operation of the exact mix of instructions found in the test program Real CP M programs tend to have a mix of CPU and I O operations I O operations to disk are handled as fast as the IBM PC can do them They aren t emulated they are don And CP M programs whose CPU bound operations involve a lot of register to register operations will be emulated faster than those requiring a lot of memory accesses It s a complicated relationship Our experience has been that an assembly using ASM COM runs about 1 5th the speed under the Emulator on a stock floppy based IBM PC than it does on an Apple with a SoftCard and 1 MegaHertz Z80 The addition of a NEC V20 processor to the IBM PC imp
86. omes with CP M 2 2 is fairly limited in its power In the Emulator it is the main Z80MU C language program which contains all of the functions of CP M s CCP and does a whole lot more In fact it is this program which emulates all of CP M with a lot of help from PCDOS For this reason there are certain CP M enhancements like ZCPR which will have a whole lot of trouble working under the Emulator The good news is that they are largely irrelevant under the Emulator as the Emulator itself provides a powerful increase in console power even without ZCPR So if you have dreams of running ZCPR or any CP M enhancement which counts on patching CP M you ought to forget about it When using the Emulator there s no CP M for such programs to patch It s all fakeware invisible to Z80 programs Stick with CP M programs which interact with the outside world via the standard unmodified BIOS and BDOS interfaces CP M 2 2 BIOS and BDOS Emulation The Emulator tries very hard to look to Z80 programs like CP M version 2 2 at least in terms of its BIOS calls and BDOS support functions Most Z780 programs that are run under the Emulator will have no idea that they aren t being run on a Z80 machine running Digital Research s CP M There are some hardware specific aspects of CP M however that make no sense on a PCDOS system Many CP M BIOS calls fo
87. on of CP M 2 2 with the exception of hardware specific functions Advanced commands for debugging 280 software eliminating the need for DDT COM including Illegal Opcode control treat em as FAULTS or NOPs BDOS function trace Instruction TRACE and NOTRACE with Z80 PC traceback Breakpoints Dump CP M memory in HEX and ASCII Patch CP M memory in HEX decimal binary ASCII characters or ASCII strings Symbolic labels may be defined and used instead of CP M addresses Z80 register and flag display and alter including alternate regs flags and IFF1 IFF2 IMF I R regs CP M memory move and find Intel HEX files can be properly read into CP M memory as well as created from CP M memory An emulated terminal for full screen CP M applications T A full disassembler much like Ward Christensen s RESOURCE built right in with Symbolic addresses Control breakpoints for Instructions Bytes DB Words DW Table of Words DW and Storage DS Automatic label generation Comments associated with Z80 addresses Online help summaries SUBMIT file support built right in no need for SUBMIT COM Access to all PCDOS programs and commands CP M software reads and writes PCDOS files and can be organized with PCDOS directory structure instead of using CP M s user number idea Z80MU from now on called the Emulator c
88. patch n patch n xxxx p n p n xxxx Either enters an interactive patch dialog which allows you to change CP M memory a byte at a time or else applies string patch xxxx to the CP M Segment and does not enter interactive patch mode If n which is a numeric value as defined at the start of this section is specified then patching starts at address n If n is not specified then patching begins with next patch location the one above the last location patched Note that in the patch n xxxx format numeric value n is required m The interactive patch dialog consists of 1 a prompt which shows the next address to be patched and its current contents 2 user responses User responses to the interactive patch prompt are as follows lt return gt A question mark followed by RETURN to request a short help message showing available responses n lt return gt A standard numeric argument as described at the start of this section This is the byte value to be patched into the specified CP M address NOTE This may also be a 16 bit value If the high order byte of the resultant n is non zero then this is taken to be a 16 bit value and fills 2 bytes xxx A string of ASCII text delimited by double quote characters The bytes of the string are patched into successive CP M memory locations The string may include ASCII escape se quences as follows
89. programs first in the directory CPM on drive C d t and then if not found there in the irectory Z80 MYSTUFF on drive C and finally if still not found in he root directory of drive C A Z80PATH string should be defined in your AUTOEXEC BAT file so that it is always present when you run the Emulator The trailing character of each directory name is optional If it is absent a character is automatically applied to the directory name before the name is used in t fa 1 has no drive ID on t he search The Z80PATH search order is used whenever an unqualified program name is used as a command to the legal filename up to 8 characters which Emulator An unqualified program name is a he front of it no character and 2 has no directory names imbedded in it no characters and 3 is not the name of a n Emulator Builtin Command For example let s say that you give the following command to the Emulator Z80 A gt asm dump aaz ttaches a COM extension tTOaroenR 4 If the file is not found on searches the various Z80PATH he Emulator first checks to see if the command ASM is one that it ecognizes a so called Builtin Command see the Builtin Commands ection If it is not then the Emulator acts just like CP M and to the command yielding ASM COM It then ooks in the current PCDOS directory on the curr
90. r back to PCDOS by entering the following PCDOS command Z80MU lt AUTONAM Le Please remember that all Emulator input and or all Emulator output is redirected at once If you redirect the output only meaning to enter commands from the keyboard don t be real surprised if you can t see any of the Emulator s prompts They are being written to the redirected output file and not to the screen NOTE When you redirect output to a disk file your input keypresses are supposed to be sent to the output file not to the screen Some versions of PCDOS however contain a bug T THE PCDOS ENVIRONMENT E that causes your keypresses to appear on the screen instead We have seen public domain patches to fix this bug floating around the Bulletin Boards but can t vouch for any of them ALSO Input that comes from Input I O Redirection is not echoed so you won t see it anywhere Input from submit files however IS echoed Using The Keyboard As mentioned previously the Emulator reads its input from the standard input as defined by PCDOS So if you don t redirect the input to the Emulator then input comes from the keyboard The Emulator could have done its own direct keyboard and screen I O This would speed things up considerably PCDOS is notoriously slow when it comes to writing to the screen We decided however not to circumvent PCDOS when writing to th
91. r example deal with the physical layout and operation of the floppy disk Some of these are ignored Others cause a fault of the Z80 program with the display of a message to the effect that the program invoked an unsupported BIOS call There are a few BDOS functions which likewise are irrelevant and which cause the Z80 program to be aborted COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 THE Ti CP M m The following ENVIRONMI isa CP M 2 2 and unsupported The addresses list of the various their effects under the Emulator cause the Z80 program to be aborted BIOS calls that are supported by Calls that are marked listed are absolute addresses within the CP M Segment Note that when the CP M segment is Cold Booted CP M s location zero is set to JMP BIOS 3 FFO3h the Warm Boot vector The only safe way for a Z80 program to locate this BIOS jump table in any CP M system not just the Emulator is to look at address 0001 within CP M s memory BIOS Address FFOOh Cold Start CP M segment FFO3h Warm Start CP M segment FFO6h Set A reg to FFh if Emulated VT52 Terminal has keypress to be read 00h if not FFO9h Get keypress from Emulated VT52 Terminal to A reg via IBM s ROM BIOS FFOCh Output C reg to Emulated VT52 Terminal via IBM s ROM BIOS
92. reg de 256 Z80 A gt xreg AF 55 Z80 A gt xreg AA BE DE HL OAOL FFFF 0100 FEFC 0055 0041 0000 0000 SF 0 L0000 COMPUTERWISE C3 03 FF CONSULTING S IX IY I R SP PC IFFL IFF2 IMF 0000 0000 00 00 FEFE 0000 0 0 0 ZF 0 HF 0 P V 0 NF 0 CF 1 JP LFFO3 IX IY I R SP PC IFFL IFF2 IMF 0000 0000 00 00 FEFE 0000 0 0 0 ZF 0 HF 0 P V 0 NF 0 CF 1 JP LFFO3 ERVICES P O BOX 813 MCLEAN VA 22101 T BUILTIN COMMANDS DEBUG SUPPORT Builtin trace n t n Traces a certain number specified by the n argument of 480 instruction executions displaying 280 regs and flags after each instruction s execution Execution begins at the current Z80 Program Counter PC If no argument is given then n defaults to l The n argument is a numeric value as described at the beginning of this section NOTE The PC of each executed instruction is saved ina circular buffer for later interpretation by the pc builtin command q v Example from an actual trace of DDT COM s opening lines Z80 A gt read ddt com Low 0100H Next 1400H xxx 780 DMA PC and Stack automatically set for COM file Z80 A gt t 4 AF 2Be DE Hel IX IY i HRS SP PC IFF1 IFF2 IMF 0A01 OFBC 0100 FEFC 0000 0000 00 00 FEFC 0103 0 0 0 0055 0041 0000 0000 SF 0 ZF 0 HF 0 P V 0 NF 0 CF 1 L0103 C3 3D OL JP LO13D ASF BC DE HIL T
93. rminal Emulator So I O redirection MCLI EAN VA 22101 T THE PCDOS ENVIRONMENT The CP M BDOS emulator The BDOS emulator does its I O via PCDOS so I O redirection does apply to it and to any Z80 programs that use BDOS functions for I O Now the question arises Will my CP M application obey any I O redirec tion that I specify when I run the Emulator The answer of course depends on your application Most standard CP M applications do their I O via BDOS functions So these will obey your I O redirection Full screen editors in general use the BIOS instead of the BDOS for a lot of very good reasons So these will automatically be exempt from your I O redirection When constructing a file to be read via input redirection remember to include all characters that are to be read either by the Emulator itself or by the CP M application This usually means that your input file will be a jumbled mix of Emulator and application input Let s say for example that you have a CP M application named TEST COM that asks for your name prints some silly message based upon your name and then exits back to CP M A complete input file to execute that program would look like this test Joan Riff exit If this text is saved on a file called AUTONAME we can run the Emula tor tell it to run TEST COM answer TEST s question and then exit the Emulato
94. roves performance So does using a hard disk instead of floppies And moving the Emulator to an IBM PC AT brings emulated performance close to that of a 1 MegaHertz Z80 COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS G T NERAL NOTE This command causes a Cold Boot of the CP M segment This destroys any CP M program that you may have had in memory Example from an actual session 280 A gt speed CP M Segment COLDBOOTED Beginning 480 timing test Please wait Effective Z80 clock speed is 248101 Hz CP M Segment COLDBOOTED COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS DI T SOMI SOME ALL btrace bt Builtin EI DOS tion Displays the current B controls the BDOS func As a CP M program is run BUG SUPPORT ALL Trace Table s that will the various if no arguments are present be traced or BDOS calls that it makes are traced This command displays the trace table as it has been left by the last CP M program run Items reported include 1 The trace table sequence number 2 The Program Counter of the CALL to the BDOS 3 The contents of the Z80 DE register at the entry to the
95. to the disassembler the list command and may be any one of the following note that only the first character is required Instructions switch to Z80 mnemonics when you get to this address Bytes switch to DB pseudo ops when you get to this address Words switch to DW pseudo ops multiple per line when you get to this address Table of words switch to DW pseudo ops one per line when you get to this address This is useful for jump tables etc where you want the source code to be neatly ar ranged Storage do a single DS define storage pseudo op when you get to this address and make the size field big enough to take you up to the next control break address or the end of the disassembly whichever is lower You may also specify a special argument which is handled immediately and never gets to the disassembler Clear Clear this address s control break data type This does not remove an associated label or comment It just undoes any control break of one of the above types associated with this CP M address COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 COMPUT Example Z80 Z80 Z80 Z80 Z80 Z80 Z80 Z80 Z80 Z80 Z80 NOTE BUILTIN COMMANDS A gt control A gt c clear A gt c read A gt control A gt c read A gt control A gt c 103 b RESOURCE FACILITY COMMANDS
96. ur routine That s because we didn t give an ending address At any rate the routine at 0235h appears to call BDOS to get a keypress then force it to uppercase It contains a slight bug but our job right now is to re source itj not fix At C gt 235 get bdos keypress CSG 239 4 C gt 235 nReturn next keypress as Uppercase char in A reg C gt 237 Use BDOS to get next keypress C gt 23a Is it lowercase char C gt 23c No return it as is C gt 23d Yes convert to uppercase COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 USING THE RESOURCE BUILTIN COMMANDS Z80 C gt 1 235 GET BDOS KEYPRESS Return next keypress as Uppercase char in A reg L0235 OE 01 LD C SOH 102373 CD 05 00 CALL BDOS Use BDOS to get next keypress LO23A FE 60 CP Lot Is it lowercase char L023C D8 RET C No return it as is 1023D D6 20 SUB ur Yes convert to uppercase LO23F c9 RET PRINT STRING Print terminated string at DE LO240 OE 09 LD C TAB L0242 C3 05 00 JP BDOS INIT MSG DB SUB INIT 1 L0245 1A 49 4E 49 L0249 54 20 31 NOTE OK our little routines are understood and documented Back to the main code and add comments that clarify things 280 C gt 100 Give intro screen Z80 C gt 106 Ask for baudrate value 106 Ask for baudrate value 28
97. version 3 0 Issue The disassembler can get confused when a multi byte opcode crosses a control break In general it reverts to DB pseudo ops up to the control break when this happens Also it s not too smart when disassembling code with addresses up around the 64K segment boundary Author s Response I have tried to locate and eliminate peephole problems The nature of the problem however goes to the very core of the disassembler as designed This is not quickly or cheaply fixable Issue There are too many CP M applications which abort because they use BDOS functions 27 1Bh and 31 1Fh These BDOS functions should be supported even if they mean little on a PCDOS system Author s Response Agreed The only reason that they haven t been emulated is that I have yet to find a sensible writeup of just exactly what the various data formats are DRI s writeup stinks If someone can provide a clear explanation of just what they truly mean then I ll emulate them Issue There are more than 600 distinct instructions in the Z80 Have they all been validated as to the accuracy of the emulation Author s Response So far all we ve done is run Z80 stuff and try to guess that it has run fine All opcodes have been desk checked Not all opcodes have been tested Most in fact have not even been executed Would somebody please create a definitive test program The diagnostics that we ve tried like
98. wn to an exac Even the untest ct ct perform everything except You can t very well have Z80 But any and flag effects have been emulated turn control to the main BIOS and BDOS we took a less precise approach We to And we wanted to add many more the INTRODUCTION available to be used by a Z80 program Yet we wanted to keep the interface very close to CP M s So we decided to support standard CP M applications ones that stood a good chance of executing on a wide variety of CP M systems and thus were hardware independent This we have succeeded in doing The user interface is just like CP M s so that someone used to CP M will feel right at home The program interface via the BIOS and BDOS is exactly the same as CP M s There are some BIOS and BDOS functions that are hardware specific These are in general not supported The differences ar explained in a later section The handling of commands and command arguments the command tail appears to the Z80 application exactly as it would on a real CP M system The default FCB at 5Ch is formatted with the filename implied by the first command line argument and the FCB at 6Ch with the second argument The byte at 80h is set to the number of characters in the command tail and is followed by an uppercase version of the command tail as typed by the user We have achieved a TPA size of 6502
99. ymbolic label to be associated with the address A comment to be associated with the address This control table is used by the disassembler the list command and list tells it how to format the source code while disassembling The various data type control breaks that may be associated with a CP M address are as follows Instructions executable Z80 code disassembled as mnemonics Bytes disassembled as DB pseudo ops Words disassembled as DW pseudo ops multiple entries per line Table of Words disassembled as DW pseudo ops one per line Storage disassembled as DS with argument large enough to bring it up to next control entry This is how the disassembler knows which parts of your 480 object code are instructions which are data and which are irrelevant buffers etc COMPUTERWISE CONSULTING SERVICES P O BOX 813 MCLEAN VA 22101 BUILTIN COMMANDS RESOURCE FACILITY COMMANDS The specific formats are described below Format control list n c list n This format of the command causes the Emulator to display all control table information that is currently known to it If numeric value n see definition of legal numeric values at start of this section is present t t hen only control information associated with CP M addresses greater han or equal to n are listed The list includes any control breaks labels and comments associ

"Z80MU" Z80 and CP/M 2.2 Emulator User's Guide or

Contents

Download Pdf Manuals

Related Search

Related Contents

&quot;Z80MU&quot; Z80 and CP/M 2.2 Emulator User's Guide or

Contents

Download Pdf Manuals

Related Search

Related Contents

"Z80MU" Z80 and CP/M 2.2 Emulator User's Guide or