home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / cpm3 / cpmpadd4.lbr / CPM+ADD4.DZC / CPM+ADD4.DOC
Text File  |  1987-08-12  |  13KB  |  334 lines
  1. CPM+ADD4.DOC
  2.  
  3.         DOCUMENTATION for CPM+ADD4 Address Program
  4.         ------------------------------------------
  5.             Jerry Levy    28-Feb-87
  6.  
  7.  
  8.  
  9. FILES IN CPM+ADD4.LBR
  10.  
  11.     CPM+ADD4.DOC        This File
  12.  
  13.     CPM+ADD4.ASM and .COM    The address program
  14.  
  15.     CPM+ADD4.UPD        How to convert CPM+ADD3.ASM to CPM+ADD4.ASM
  16.  
  17.     CPM+ADD2.FIX        Bug Fix for ver. 2
  18.  
  19.     CPM3SCB.LBR        Read CPM3SCB.DOC if you want to learn more 
  20.       CPM3SCB.DOC        about the SCB.  Thanks to Jim Lopushinsky.
  21.       BIOSFIX.MAC
  22.       BIOSFIX.COM
  23.  
  24.  
  25. VERSION 3 vs. VERSION 4
  26.     The only change is to print the extended disk parameter header
  27.     instead of the shorter, regular header.  All patch points, etc.
  28.     (see Wild-Card Dumps, below) remain unchanged.  The LIMITATIONS
  29.     comments in this file have been expanded.
  30.  
  31. PROGRAM FUNCTION
  32.     CPM+ADD4.COM prints out useful addresses, contents of selected
  33.     memory locations, dumps of important areas of memory including
  34.     the SCB and Zero Page.  It also provides a summary of memory
  35.     architecture, including some detail about .RSX's that may be active
  36.     at time of program loading and execution.
  37.  
  38.     Three optional dumps may be selected either by editing the .ASM
  39.     file or by patching the .COM file with SID.COM.  This allows
  40.     for simple addition of new dumps.
  41.  
  42. LIMITATIONS
  43.     Use of this program is limited to CP/M Plus (CP/M 3.x)
  44.     installations.  Program will abort if run on a non-CP/M system
  45.     or on a CP/M operating system running a version earlier than 3.0. 
  46.     It should run under any CP/M Plus Operating System.
  47.  
  48.     Other limitations (applies to all versions of CPM+ADD)
  49.     ------------------------------------------------------
  50.         1. Since CPM+ADD loads and runs from the TPA bank (Bank1),
  51.            some possibility exists that the program will output code
  52.            in Bank1 in a few situations where the true bank of the
  53.            address is Bank0 (example: when the Disk Parameter Block
  54.            or Disk Parameter Header may be DSEG'ed in the bios).  This
  55.            won't always be a problem, even when code of interest is
  56.            DSEG'ed, but be forewarned about what to track down if
  57.            output doesn't make sense.
  58.  
  59.         2. Another problem occasionally encountered is that the
  60.            location of the common memory boundary which this program
  61.            gets from the CP/M Plus System Control Block isn't always
  62.            to be believed.  I suspect that when it is not correct it
  63.            is because hardware or firmware in a particular system sets
  64.            the common memory independently.  Seems to be the case with
  65.            the ALS CP/M Card (for Apple ][ and //e). 
  66.  
  67.  
  68. BACKGROUND
  69.     This all began when I needed four operating system addresses
  70.     and the contents of one more to install BYE5.  Because I was
  71.     working with three different bios's on my Apple ][ (ALS CP/M Card
  72.     bios's 3.01b2, 3.01c2, and the Public Domain CP-PLUG bios 3.02b),
  73.     I decided to write a short program.
  74.  
  75.          The ALS EQUate: ALS, for the ALS CP/M Card on Apple ][, added
  76.     two special bios functions in v. 3.01b1, a third in 3.01b2, and a
  77.     fourth in 3.01c2.  CP-PLUG, also for the ALS CP/M Card, employed
  78.     the first three of those.  As these new bios functions (#'s 33-36)
  79.     are non-standard, I've used an ALSCARD equate to control whether
  80.     ALS's names for them are printed out as part of the bios jump table.
  81.  
  82.     The equate changes nothing else.  It is purely of editorial content.
  83.  
  84.     Where I could in the output produced, I tried to spell things as
  85.     they are spelled in DRI's "CP/M Plus System Guide" and other DRI
  86.     reference documents.
  87.  
  88. BUG IN VERSION 2
  89.     Version 2 (CPM+ADD2) contained a rather sleepy bug in the dump
  90.     routine, one which didn't bite if you made no changes to the 
  91.     program.  It which could screw up some dumps if you had made changes.
  92.     In v.3 I corrected this error.  The bug, incidentally, was
  93.     what (erroneously) led me to perceive a need to do one of my dumps
  94.     from a buffer.  The bug and its fix are described in CPM+ADD2.FIX.
  95.  
  96.     In v.3, I did not buffer dumps, but as an option controlled by
  97.     the new equate, BFDMP, dump buffering can be selected.  Don't, unless
  98.     dumps go wild.
  99.  
  100. MODIFICATIONS
  101.     Feel free to modify and add special stuff for other implementations,
  102.     but please note that you've done it in the .ASM file version log.
  103.     Isolate hardware-specific stuff by using equates as I've done for
  104.     the ALS CPM Card, indicate your name and date.  Most recent change
  105.     last.  If you can, leave a copy on George Peace's Fog #10 RCP/M
  106.     (717-657-8699) and also leave me a note there.  That will allow me
  107.     to keep track of and then to distribute changes to all.
  108.  
  109.  
  110. EDITING THE .ASM FILE
  111.  
  112.   BFDMP    EQU    NO    ;Leave NO unless dumps go wild on you.  YES means
  113.             ;  memory that is dumped is transferred to buffer and
  114.             ;  dumped from there rather than from the original
  115.             ;  location.  If you select this YES, AND you also 
  116.             ;  have dumps longer than 256 bytes, increase BFSZ,
  117.             ;  below.
  118.  
  119.   BFSZ    EQU    256    ;Only if BFDMP is selected YES. Sets buffer size.
  120.             ;  256 is OK for BFDMP EQU YES and present dumps
  121.  
  122.   ALSCARD EQU    NO    ;Leave NO, unless you have Apple ][ with ALS CP/M Card.
  123.             ;  This only attaches ALS's labels to four special
  124.             ;  bios functions added by ALS.  There are no other
  125.             ;  alterations introduced by how you set this equate.
  126.  
  127.  
  128.  
  129. The next 4 are defaults for chars used in the RSX name when RSX prefix info 
  130. is presented.  Change if your console/printer cannot handle them.  They are
  131. used in place of unprintable chars in printing out the rsx name field. Ctrl
  132. chars can send your printer or console off to the country and we therefore  
  133. replace unprintables by a suitable combination of printables.
  134.  
  135. An example of how such names can arise in the RSX name field is the case
  136. when the operating system or Loader processes multiple commands that are 
  137. entered at the command line prompt, each separated by an exclamation point.
  138. An RSX is created with the name field uninitialized.  The name field thus
  139. contains whatever adventitious characters were in memory where the name
  140. field happens to have been placed.
  141.  
  142. These 4 characters can be patched with SID.COM.
  143.     The patch locations are:
  144.             0103h (carat)
  145.             0104h (sedilla)
  146.             0105h (quote)
  147.             0106h (rubout)
  148.  
  149. The rubout char is ascii 07fh and because some O.S.'s replace it with a
  150. backspace, the uploaded version uses 7dh  as the "rubout" char.  If your
  151. system will accept 7fh as a printable, 7fh is more appropriate and will
  152. not be confused with the 7dh or fdh characterS themselves.
  153.  
  154. rubout    equ    7dh    ;'}', in place of 7fh.  If 7fh prints, use 7fh
  155.  
  156.  
  157. The other 3 are prefix chars used as follows:
  158.  
  159.             ;(No prefix signifies an ordinary, printable character)
  160. carat    equ    5eh    ;^  prefix        a control char with hi bit not set 
  161. sedilla    equ    7eh    ;~  prefix        a non-control char with hi bit set
  162. quote    equ    22h    ;"  prefix        a control char with hi bit set
  163.  
  164.  
  165. WILD-CARD DUMPS
  166.     You can now easily specify your own additional dumps.  Either edit
  167.     the .ASM file to do that or use SID.COM to patch the .COM file.  No
  168.     Wild-Card dumps are specified in the uploaded file.
  169.  
  170.     SID-patchable Wild-Card Dump parameters -- what they are and their
  171.     locations are as follows:
  172.  
  173.     1. The enabler byte set to
  174.         0feh = we don't do this dump but may do next
  175.         00h  = we don't do any more wild-card dumps
  176.         0ffh (or anything besides 00h and 0feh) = we do the dump
  177.  
  178.     2. # of byes to be dumped 
  179.  
  180.     3. Starting address of location to be dumped
  181.  
  182.     4. Format or index value, so first byte in dump is formatted to
  183.        appear as this "address".  Usually this will be the same as the
  184.        starting address.  If you are dumping something which you want to
  185.        directly indicate an offset from the starting address (study the
  186.        second SCB dump when CPM+ADD4.COM is run), set this to 0000.
  187.        ...or, as you wish, set to anything useful to help you understand
  188.        the data you dump.
  189.  
  190.  
  191.                 Patching Locations
  192.          -----------------------------------------------
  193.                # of Bytes    Dump Addr     Dump Index 
  194.          Enabler  ----------    ----------    ----------
  195.           byte      lsb   msb    lsb   msb     lsb   msb    
  196.              -------  ----  ----    ----  ----    ----  ----
  197.    First Dump      0120h   0121h 0122h   0123h 0124h   0125h 0126h
  198.    Next,      0127h   0128h 0129h   012Ah 012Bh   012Ch 012Dh <- address
  199.     etc.                                above + 7
  200.  
  201.     A typical patching session to set two of the Wild-Card Dumps is
  202.     duplicated at the end of the .DOC File.
  203.  
  204.  
  205.  
  206. SYSTEM CONTROL BLOCK DUMPS
  207.     There is only one SCB but the program produces two SCB dumps.  Why?
  208.  
  209.     DRI documentation refers to an SCB 100 (64h) bytes long located
  210.     just ahead of the first page of the BIOS.  Jim Lopushinsky, in
  211.     CPM3SCB.DOC (within CPM3SCB.LBR) documents a longer SCB, 152 (98h)
  212.     bytes long, starting earlier than DRI's SCB_BASE but ending, as
  213.     DRI's SCB does, at the FF byte on the page preceding the start of the
  214.     BIOS.
  215.  
  216.     DRI, in different documentations, use both address offsets relative
  217.     to SCB_BASE and offset by the lsb of absolute address (an offset, also,
  218.     relative to start of the page) to specify location of a particular
  219.     SCB element.  DRI requires an offset relative to SCB_BASE in the
  220.     SCB Parameter Block when BDOS function 49 (Get/Set SCB) is called.
  221.  
  222.     Lopushinsky uses offsets relative to start of the page.
  223.  
  224.     Consequently, the first SCB dump is the whole SCB as described in the
  225.     Lopushinsky .DOC file, with absolute addresses as indices of the dump.
  226.     The second SCB dump is the DRI-documented portion of the SCB with dump
  227.     indices referenced to SCB_BASE.  The latter dump allows one to more
  228.     easily pick out SCB locations corresponding to, for example, those in
  229.     Appendix A in the DRI "CP/M Plus Operating System Programmer's
  230.     Guide".
  231.  
  232.  
  233. TESTING THE PROGRAM
  234.  
  235.     1. A>cpm+add4
  236.  
  237.     2. A>cpm+add4!cpm+add4
  238.  
  239.     3. Make up a .SUB file containing the following
  240.  
  241.         ;TEST.SUB
  242.         cpm+add4
  243.         cpm+add4
  244.  
  245.        and do
  246.         A>submit test
  247.  
  248.    What you'll find:
  249.  
  250.     1) If no RSX's are present -- if they are, reboot and start over --
  251.        you will get only addresses and some dumps.
  252.  
  253.     2) When the first one runs, you will see RSX's indicated,
  254.        the first (lowest) with a name that, if present at all, is
  255.        probably gibberish.  The LOADER .RSX will also be present.  It
  256.        is always resident when other RSX's are there, and is always
  257.        the RSX highest in memory.
  258.  
  259.        The second cpm+add4 will show no RSX's -- all cleared out.
  260.  
  261.     3) Like 2), except you will see the RSX SUBMIT.COM uses (GET,
  262.        on my system, though from reading DRI's literature I expected
  263.        it to be called something else); also you'll see the LOADER RSX.
  264.  
  265.        The second cpm+add4 run by the SUBMIT file will show no RSX's.
  266.     
  267.  
  268. PATCHING SESSION -- We set two Wild-Card Dumps
  269.  
  270.     The two dumps we set are the pair of SCB dumps described above.
  271.     This should explain through doing what the function is of the
  272.     format or index word we set.  It also provides something that
  273.     should check versus the SCB dumps CPM+ADD4.COM produces.
  274.  
  275.     My system has SCB_BASE (SCB_BASE+0h) = F29ch, and the origin
  276.     of the full SCB per Lopushinsky's guidance is F268h.  These 
  277.     numbers came from running CPM+ADD4.  Yours may and probably
  278.     will differ.  Only the page (F2) will differ.  You should
  279.     therefore use the addresses you find, not mine in trying to
  280.     repeat the stuff below.
  281.  
  282.  
  283.  
  284. B>SID b:cpm+add4.com
  285.  
  286. CP/M 3 SID - Version 3.0
  287. NEXT MSZE  PC  END
  288. 2200 2200 0100 C9FF
  289.  
  290.         [First. verify our patch area, should start at 0120h]
  291. #d100,d145
  292. 0100: C3 FA 01 5E 7E 22 7D 00 00 00 00 00 00 00 00 00 ...^~"}.........
  293. 0110: 00 00 00 00 00 00 00 00 20 30 31 32 30 48 2D 3E ........ 0120H->
  294. 0120: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
  295. 0130: 00 00 00 00 00 00 3C 2D 45 4E 44 20 50 41 54 43 ......<-END PATC
  296. 0140: 48 20 41 52 45 41                               H AREA
  297.  
  298. #s120            [set the first "enable bit" at 120h to ffh]
  299. 0120 00 ff
  300. 0121 00 .
  301.  
  302. #sw121
  303. 0121 0000 0098        [dump the whole 152 (98h) byte SCB...]
  304. 0123 0000 f268        [...from f268h]
  305. 0125 0000 f268        [dump will show f268h as first byte]
  306. 0127 0000 .
  307.  
  308. #s127
  309. 0127 00 ff        [Now at 120h+7h, set enable byte for second w-c dump]
  310. 0128 00 .
  311.  
  312. #sw128
  313. 0128 0000 0064    [dump the part of the SCB that DRI document, 100 (64h)bytes]
  314. 012A 0000 f29c    [starting here]
  315. 012C 0000 0000    [dump indexed to zero so all entries are relative to start]
  316. 012E 0000 .
  317.  
  318. #wb:cpm+add4.com    [write file back to disk]
  319. 0042h record(s) written.
  320. #g0            [exit SID]
  321.  
  322. Run CPM+ADD4.  You should have two new dumps providing the same information
  323. as in the two SCB dumps.
  324.  
  325.  
  326.        
  327.  
  328.                             Jerry Levy
  329.                             1129 Dundee Drive
  330.                             Dresher, PA 19025
  331.                             (215) 657-0898
  332.                             (voice - evenings)
  333.  
  334.