CPM+ADD4.DOC DOCUMENTATION for CPM+ADD4 Address Program ------------------------------------------ Jerry Levy 28-Feb-87 FILES IN CPM+ADD4.LBR CPM+ADD4.DOC This File CPM+ADD4.ASM and .COM The address program CPM+ADD4.UPD How to convert CPM+ADD3.ASM to CPM+ADD4.ASM CPM+ADD2.FIX Bug Fix for ver. 2 CPM3SCB.LBR Read CPM3SCB.DOC if you want to learn more CPM3SCB.DOC about the SCB. Thanks to Jim Lopushinsky. BIOSFIX.MAC BIOSFIX.COM VERSION 3 vs. VERSION 4 The only change is to print the extended disk parameter header instead of the shorter, regular header. All patch points, etc. (see Wild-Card Dumps, below) remain unchanged. The LIMITATIONS comments in this file have been expanded. PROGRAM FUNCTION CPM+ADD4.COM prints out useful addresses, contents of selected memory locations, dumps of important areas of memory including the SCB and Zero Page. It also provides a summary of memory architecture, including some detail about .RSX's that may be active at time of program loading and execution. Three optional dumps may be selected either by editing the .ASM file or by patching the .COM file with SID.COM. This allows for simple addition of new dumps. LIMITATIONS Use of this program is limited to CP/M Plus (CP/M 3.x) installations. Program will abort if run on a non-CP/M system or on a CP/M operating system running a version earlier than 3.0. It should run under any CP/M Plus Operating System. Other limitations (applies to all versions of CPM+ADD) ------------------------------------------------------ 1. Since CPM+ADD loads and runs from the TPA bank (Bank1), some possibility exists that the program will output code in Bank1 in a few situations where the true bank of the address is Bank0 (example: when the Disk Parameter Block or Disk Parameter Header may be DSEG'ed in the bios). This won't always be a problem, even when code of interest is DSEG'ed, but be forewarned about what to track down if output doesn't make sense. 2. Another problem occasionally encountered is that the location of the common memory boundary which this program gets from the CP/M Plus System Control Block isn't always to be believed. I suspect that when it is not correct it is because hardware or firmware in a particular system sets the common memory independently. Seems to be the case with the ALS CP/M Card (for Apple ][ and //e). BACKGROUND This all began when I needed four operating system addresses and the contents of one more to install BYE5. Because I was working with three different bios's on my Apple ][ (ALS CP/M Card bios's 3.01b2, 3.01c2, and the Public Domain CP-PLUG bios 3.02b), I decided to write a short program. The ALS EQUate: ALS, for the ALS CP/M Card on Apple ][, added two special bios functions in v. 3.01b1, a third in 3.01b2, and a fourth in 3.01c2. CP-PLUG, also for the ALS CP/M Card, employed the first three of those. As these new bios functions (#'s 33-36) are non-standard, I've used an ALSCARD equate to control whether ALS's names for them are printed out as part of the bios jump table. The equate changes nothing else. It is purely of editorial content. Where I could in the output produced, I tried to spell things as they are spelled in DRI's "CP/M Plus System Guide" and other DRI reference documents. BUG IN VERSION 2 Version 2 (CPM+ADD2) contained a rather sleepy bug in the dump routine, one which didn't bite if you made no changes to the program. It which could screw up some dumps if you had made changes. In v.3 I corrected this error. The bug, incidentally, was what (erroneously) led me to perceive a need to do one of my dumps from a buffer. The bug and its fix are described in CPM+ADD2.FIX. In v.3, I did not buffer dumps, but as an option controlled by the new equate, BFDMP, dump buffering can be selected. Don't, unless dumps go wild. MODIFICATIONS Feel free to modify and add special stuff for other implementations, but please note that you've done it in the .ASM file version log. Isolate hardware-specific stuff by using equates as I've done for the ALS CPM Card, indicate your name and date. Most recent change last. If you can, leave a copy on George Peace's Fog #10 RCP/M (717-657-8699) and also leave me a note there. That will allow me to keep track of and then to distribute changes to all. EDITING THE .ASM FILE BFDMP EQU NO ;Leave NO unless dumps go wild on you. YES means ; memory that is dumped is transferred to buffer and ; dumped from there rather than from the original ; location. If you select this YES, AND you also ; have dumps longer than 256 bytes, increase BFSZ, ; below. BFSZ EQU 256 ;Only if BFDMP is selected YES. Sets buffer size. ; 256 is OK for BFDMP EQU YES and present dumps ALSCARD EQU NO ;Leave NO, unless you have Apple ][ with ALS CP/M Card. ; This only attaches ALS's labels to four special ; bios functions added by ALS. There are no other ; alterations introduced by how you set this equate. The next 4 are defaults for chars used in the RSX name when RSX prefix info is presented. Change if your console/printer cannot handle them. They are used in place of unprintable chars in printing out the rsx name field. Ctrl chars can send your printer or console off to the country and we therefore replace unprintables by a suitable combination of printables. An example of how such names can arise in the RSX name field is the case when the operating system or Loader processes multiple commands that are entered at the command line prompt, each separated by an exclamation point. An RSX is created with the name field uninitialized. The name field thus contains whatever adventitious characters were in memory where the name field happens to have been placed. These 4 characters can be patched with SID.COM. The patch locations are: 0103h (carat) 0104h (sedilla) 0105h (quote) 0106h (rubout) The rubout char is ascii 07fh and because some O.S.'s replace it with a backspace, the uploaded version uses 7dh as the "rubout" char. If your system will accept 7fh as a printable, 7fh is more appropriate and will not be confused with the 7dh or fdh characterS themselves. rubout equ 7dh ;'}', in place of 7fh. If 7fh prints, use 7fh The other 3 are prefix chars used as follows: ;(No prefix signifies an ordinary, printable character) carat equ 5eh ;^ prefix a control char with hi bit not set sedilla equ 7eh ;~ prefix a non-control char with hi bit set quote equ 22h ;" prefix a control char with hi bit set WILD-CARD DUMPS You can now easily specify your own additional dumps. Either edit the .ASM file to do that or use SID.COM to patch the .COM file. No Wild-Card dumps are specified in the uploaded file. SID-patchable Wild-Card Dump parameters -- what they are and their locations are as follows: 1. The enabler byte set to 0feh = we don't do this dump but may do next 00h = we don't do any more wild-card dumps 0ffh (or anything besides 00h and 0feh) = we do the dump 2. # of byes to be dumped 3. Starting address of location to be dumped 4. Format or index value, so first byte in dump is formatted to appear as this "address". Usually this will be the same as the starting address. If you are dumping something which you want to directly indicate an offset from the starting address (study the second SCB dump when CPM+ADD4.COM is run), set this to 0000. ...or, as you wish, set to anything useful to help you understand the data you dump. Patching Locations ----------------------------------------------- # of Bytes Dump Addr Dump Index Enabler ---------- ---------- ---------- byte lsb msb lsb msb lsb msb ------- ---- ---- ---- ---- ---- ---- First Dump 0120h 0121h 0122h 0123h 0124h 0125h 0126h Next, 0127h 0128h 0129h 012Ah 012Bh 012Ch 012Dh <- address etc. above + 7 A typical patching session to set two of the Wild-Card Dumps is duplicated at the end of the .DOC File. SYSTEM CONTROL BLOCK DUMPS There is only one SCB but the program produces two SCB dumps. Why? DRI documentation refers to an SCB 100 (64h) bytes long located just ahead of the first page of the BIOS. Jim Lopushinsky, in CPM3SCB.DOC (within CPM3SCB.LBR) documents a longer SCB, 152 (98h) bytes long, starting earlier than DRI's SCB_BASE but ending, as DRI's SCB does, at the FF byte on the page preceding the start of the BIOS. DRI, in different documentations, use both address offsets relative to SCB_BASE and offset by the lsb of absolute address (an offset, also, relative to start of the page) to specify location of a particular SCB element. DRI requires an offset relative to SCB_BASE in the SCB Parameter Block when BDOS function 49 (Get/Set SCB) is called. Lopushinsky uses offsets relative to start of the page. Consequently, the first SCB dump is the whole SCB as described in the Lopushinsky .DOC file, with absolute addresses as indices of the dump. The second SCB dump is the DRI-documented portion of the SCB with dump indices referenced to SCB_BASE. The latter dump allows one to more easily pick out SCB locations corresponding to, for example, those in Appendix A in the DRI "CP/M Plus Operating System Programmer's Guide". TESTING THE PROGRAM 1. A>cpm+add4 2. A>cpm+add4!cpm+add4 3. Make up a .SUB file containing the following ;TEST.SUB cpm+add4 cpm+add4 and do A>submit test What you'll find: 1) If no RSX's are present -- if they are, reboot and start over -- you will get only addresses and some dumps. 2) When the first one runs, you will see RSX's indicated, the first (lowest) with a name that, if present at all, is probably gibberish. The LOADER .RSX will also be present. It is always resident when other RSX's are there, and is always the RSX highest in memory. The second cpm+add4 will show no RSX's -- all cleared out. 3) Like 2), except you will see the RSX SUBMIT.COM uses (GET, on my system, though from reading DRI's literature I expected it to be called something else); also you'll see the LOADER RSX. The second cpm+add4 run by the SUBMIT file will show no RSX's. PATCHING SESSION -- We set two Wild-Card Dumps The two dumps we set are the pair of SCB dumps described above. This should explain through doing what the function is of the format or index word we set. It also provides something that should check versus the SCB dumps CPM+ADD4.COM produces. My system has SCB_BASE (SCB_BASE+0h) = F29ch, and the origin of the full SCB per Lopushinsky's guidance is F268h. These numbers came from running CPM+ADD4. Yours may and probably will differ. Only the page (F2) will differ. You should therefore use the addresses you find, not mine in trying to repeat the stuff below. B>SID b:cpm+add4.com CP/M 3 SID - Version 3.0 NEXT MSZE PC END 2200 2200 0100 C9FF [First. verify our patch area, should start at 0120h] #d100,d145 0100: C3 FA 01 5E 7E 22 7D 00 00 00 00 00 00 00 00 00 ...^~"}......... 0110: 00 00 00 00 00 00 00 00 20 30 31 32 30 48 2D 3E ........ 0120H-> 0120: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 0130: 00 00 00 00 00 00 3C 2D 45 4E 44 20 50 41 54 43 ......<-END PATC 0140: 48 20 41 52 45 41 H AREA #s120 [set the first "enable bit" at 120h to ffh] 0120 00 ff 0121 00 . #sw121 0121 0000 0098 [dump the whole 152 (98h) byte SCB...] 0123 0000 f268 [...from f268h] 0125 0000 f268 [dump will show f268h as first byte] 0127 0000 . #s127 0127 00 ff [Now at 120h+7h, set enable byte for second w-c dump] 0128 00 . #sw128 0128 0000 0064 [dump the part of the SCB that DRI document, 100 (64h)bytes] 012A 0000 f29c [starting here] 012C 0000 0000 [dump indexed to zero so all entries are relative to start] 012E 0000 . #wb:cpm+add4.com [write file back to disk] 0042h record(s) written. #g0 [exit SID] Run CPM+ADD4. You should have two new dumps providing the same information as in the two SCB dumps. Jerry Levy 1129 Dundee Drive Dresher, PA 19025 (215) 657-0898 (voice - evenings)