home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / 22rsx / rsx12.ark.2 / RSX.DOC < prev    next >
Encoding:
Text File  |  1985-11-09  |  7.4 KB  |  168 lines
  1.  
  2.                RSX system Documentation (85/01/25)
  3.                               revised   (85/09/24)
  4.                ===================================
  5.  
  6. What is an RSX  (Resident System Extension for CPM 2.2 only)
  7. ==============
  8.  
  9. An RSX is a method of adding new system calls to the CPM system,  which can
  10. then be called just like any other BDOS function.  The RSX can also be used
  11. to intercept native calls and change their operation (ex. list output calls
  12. could be intercepted and spooled,  or a program can "chain" to an arbitrary
  13. program by passing the command line).  The RSX is also a mechanism (in this
  14. implementation)  for installing new/revised i/o drivers,  such  as  foreign
  15. disk systems,  keyboard translators,  spoolers,  etc.   This was written to
  16. implement foreign disk systems and the "chain" ability.
  17.  
  18.  
  19. Executing an RSX
  20. ================
  21.  
  22. Under this system,  an RSX is stored as any other .COM file.  To install it
  23. the .COM file is executed by typeing its name at the CCP prompt.  To remove
  24. it enter its name again.   In between installation and removal the RSX will
  25. be memory resident,  and warm boots will not reload the CCP or BDOS system.
  26. At the same time the added BDOS call(s) or drivers are available.
  27.  
  28. CAUTION:  Some  systems  require a physical reboot (eg Kaypro 4) to  change
  29. disk formats (density, single/double sided, etc).  This will not occur when
  30. the RSX is active.  NEWROM.LBR contains a system that corrects this,  among
  31. other things, for the 1983 version Kaypro 4.  Published.
  32.  
  33. CAUTION:  The original Digital Research CCP will not start up a SUBMIT  job
  34. when  the RSX is active.  In addition logging on to an invalid  drive  will
  35. hang  the system until a reset.   You can avoid this by installing  CCPLUS,
  36. which will also provide automatic drive searches for applications. ZCPR has
  37. not been tested with this system.  CCPLUS has been published.
  38.  
  39. Memory usage:
  40. ============
  41.  
  42. The  RSX  is  mounted below the CCP area,  and thus reduces  the  available
  43. application  memory.    The  utility  HOWBIG  shows  the  effective  memory
  44. available at any time.  Just enter d>howbig
  45.  
  46.  
  47. Making a new RSX  (This system is for CPM 2.2)
  48. ================
  49.  
  50. Obviously,  someone must write the system code needed.   That is you.  This
  51. system provides a standard method of installing and removing the code  from
  52. your  running system.   File RSXMAST.MAC is heavily annotated to show where
  53. the custom code should be inserted.  The RSX installed by this only outputs
  54. a   short  message when called by an application program.   You  need  only
  55. create the RSCCUST.DEF, RSXIO.INC, RSXINIT.INC and RSXMAIN.INC files, using
  56. the various .XXX files as templates.
  57.  
  58. You  can test by loading it,   then under DDT create system calls with  the
  59. argument  100 (064h) (assuming you use that value for @RSX).   If the  (de)
  60. argument  is  0  the returned value is 0 for no RSX  present,  non-zero  if
  61. present  and active.  If the (de) argument is -1 (0ffffh) the RSX  is  made
  62. inactive, and will be removed on the next warm boot (^C). Alternatively the
  63. utility  ENQUIRE  can  be used to pass arguments and display  the  results.
  64. Usage (parameters in hex) is:
  65.  
  66. d>ENQUIRE rsxnum [param]   executes BDOS call rsxnum,  with  de=param (hex)
  67.  
  68. To create a new RSX, you must first assemble (or relocate) two versions
  69.  
  70.     rsxzero.$$$    is "orged" or relocated to start at 0
  71.     rsxone.$$$     is "orged" or relocated to start at 0100h (normal)
  72.  
  73. With DDT, load RELOCCP.SYS, and append, at 0200h, rsxzero.$$$ by
  74.  
  75.     B>DDT reloccp.sys
  76.     ...signon etc...
  77.     -irsxzero.$$$
  78.     -r100                  (note the 0100h offset command)
  79.     .....info. returned    (This assumes a .COM type file.  If it is)
  80.                            (a hex file with .HEX extension use r200)
  81.  
  82. Now examine the bytes loaded at locations 203 thru 204
  83.  
  84.     -d200,204
  85.     0200 C3 00 54 30 05    <--note this number, hex 0530, right byte 1st
  86.                               (number is for example only)
  87.  
  88. Now find the location (-0100h) of the first free byte in the relocated
  89. image by:
  90.  
  91.     -h100,530
  92.     0630 0430              <--The left number (0630) is what you want
  93.  
  94. and append the 0100h based image by
  95.  
  96.     -irsxone.$$$
  97.     -r630                  (using the above number as offset)
  98.     Next  PC  Save
  99.     nnnn 0100    m         (The "save" value from DDTY only)
  100.  
  101. Note  the "next" value loaded,  use the left two digits as a hex number and
  102. save that number of pages.  (DDTY5 will tell you in decimal) by exiting and
  103. executing save
  104.  
  105.     -^C                    (control-c)
  106.     A>SAVE 12 temp.com     (The "12" is for example only)
  107.  
  108. Now execute temp.com.  It will tell you how much to save
  109.  
  110.     A>temp
  111.     now SAVE 7
  112.     A>SAVE 7 rsx.com                    (do it)
  113.  
  114. You now have a usable new version of RSX,  which will relocate itself  into
  115. high memory when executed.
  116.  
  117. If  you are using other systems mounted below CCP in high memory,  such  as
  118. KEYS  or  one  or more additional RSXs,  the first such  loaded  will  have
  119. protected  the  CCP memory (of 2k),  and a further run of RSX will  save  a
  120. totally  useless additional 2k.   To avoid this by having the loader detect
  121. this situation and automatically avoid the extra memory save do:
  122.  
  123.     A>ddt rsx.com
  124.     ....signon etc...
  125.     -ireloccp.ovr                  (the "smarter" overlay for load only)
  126.     -r
  127.     -^C                            (control-c)
  128.     A>save 7 rsx.com               (same number as before)
  129.  
  130. and you are all done.
  131.  
  132.  
  133. RSX call conventions
  134. ====================
  135.  
  136. When the RSX is installed it appears as a new CPM BDOS call,  identified by
  137. the  value in C,  and receiving a parameter in DE.   The DE parameter  will
  138. usually   be   a   pointer to some user memory  area,  e.g.  an  FCB.   The
  139. following parameter values have been reserved (Note that under CPM a  valid
  140. pointer to usable memory can never have these values):
  141.      0    Residence  enquiry.   If  the RSX is mounted and active  it  will
  142.           returng  a non-zero value in A.   If not mounted or inactive zero
  143.           is returned (as will BDOS 2.2 for any invalid calls)
  144.      1    Return  a pointer (in HL) to any data areas specific to the  RSX.
  145.           ex:   disk   drive   parameters  for  a  general   foreign   disk
  146.           reader/writer,  or table of key translation strings for a console
  147.           key redefinition system.   If the RSX is not resident or does not
  148.           use such an area obviously the pointer is invalid.  The code that
  149.           uses  such a pointer is specific to the RSX,  and thus this usage
  150.           is optional.
  151.     -1    (or 0FFFFh).  Remove the RSX.  The memory used will be reclaimed,
  152.           if possible, on the next warm boot.
  153.  
  154. A limitation
  155. ============
  156.  
  157. Only one RSX (the first installed) can provide i/o drivers visible to BDOS.
  158. Any  further  ones cannot reliably find/modify/restore the  BIOS  pointers.
  159. Thus checks have been built in,  and the user equate "driver", or patchable
  160. variable "chkflg" cause these checks to be executed.   However,  later RSXs
  161. can  install bios modifications visible ONLY to application programs  using
  162. direct BIOS calls through the pointer at location 1.  KEYS is an example of
  163. an  RSX providing BDOS visible bios changes (although  built  earlier,  and
  164. does not use this exact mechanism).
  165.  
  166.                                    C.B Falconer  (85/Jan/25)
  167.      revised 85/9/24 and 85/11/9
  168. ╜÷