home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / enterprs / cpm / utils / f / rsxdemo.lzh / RSXDEMO.DOC < prev   
Encoding:
Text File  |  1991-01-16  |  9.8 KB  |  254 lines
  1. RSXDEMO.DOC                            7-15-83    
  2.  
  3.       Copyright (c) 1983 by George F Peace.  All rights reserved.
  4.  
  5. 1.  Introduction
  6.  
  7. This document and the accompanying program are provided to assist the CP/M
  8. Plus user in understanding the operation of the Resident System Extension
  9. (RSX) feature.  Some of the information presented is also available in the
  10. "CP/M Plus (CP/M Version 3) Operating System Programmer's Guide" by Digital
  11. Research.
  12.  
  13. An RSX is a Page Relocatable (PRL) file with the file type RSX.  RSXs are
  14. combined with a CP/M Plus program by the GENCOM utility.  At execution time,
  15. the program loader dynamically relocates the RSXs to the top of the TPA
  16. and updates the RSX headers and page zero address six to reflect the
  17. presence of those routines.  Control is then passed to the COM file to
  18. perform any operation required to initialize the RSXs and/or the CP/M Plus
  19. environment.
  20.  
  21. CP/M-Plus is released with several RSXs or programs with attached RSXs.
  22. These include GET, PUT, SAVE and SUBMIT. GET and PUT intercept console input
  23. and output requests respectively and convert those requests into CP/M file
  24. I/O requests.  SAVE intercepts the warm boot BDOS function following
  25. execution of a program and allows the user to save memory to disk.  SUBMIT
  26. functions similarly to GET by replacing console input requests with file I/O.
  27.  
  28. The CP/M Plus user can create an RSX to perform functions that in the past
  29. typically required a detailed understanding of CP/M memory organization and
  30. operation.  Those functions might include
  31.  
  32.     - Restricting certain BDOS function calls according to
  33.       specific security requirements
  34.     - data manipulation (i.e. encryption)
  35.     - Implementation of RAM disks
  36.     - Implementation of hard disk interfaces
  37.  
  38. The RSX accompanying this document receives all BDOS function calls and
  39. intercepts those that are console-related following its relocation and
  40. initialization.  The program displays the function number for each one
  41. intercepted.  If BDOS was CALLed via address 0005h, the address of that
  42. CALL will also be displayed.  Its operation thus generates a run-time
  43. trace of BDOS calls.
  44.  
  45.  
  46. 2.  Resident System Extension Structure
  47.  
  48. Each RSX must contain a standard 27 byte prefix.  The following is an
  49. example of that structure.
  50.  
  51. 0    serial:    db    0,0,0,0,0,0    ;room to insert serial number
  52. 1    start:    jmp    ftest        ;beginning of program
  53. 2    next:    db    0C3H        ;jump instruction op-code
  54. 3        dw    0        ;next module in line (or BDOS)
  55. 4    prev:    dw    0        ;previous module
  56. 5    remov:    db    00h        ;remove flag clear
  57. 6    nonbnk:    db    0        ;>0 to load only in non-banked CP/M
  58. 7    rsxnam:    db    'RSXDEMO '    ;the name of this RSX
  59. 8    loader:    db    0        ;loader flag
  60. 9        db    0,0        ;reserved
  61.  
  62.  
  63. Updated                Legend
  64.   by
  65.  
  66. loader     0 - This area is reserved for the program loader to insert the
  67.         CP/M Plus serial number.  This allows existing programs that
  68.         use that value (always expected to be the first six bytes of
  69.         the first page of BDOS) to operate without error in an RSX
  70.         environment.
  71.  user    1 - This is the jump to the actual start of the RSX code
  72. loader    2 - This field points to the next higher RSX or BDOS if this
  73.         is the last RSX
  74. loader    4 - This is the address of the previous RSX or 0005 if this is
  75.         the first RSX
  76.  user    5 - This flag is set to zero if the RSX is to remain in memory
  77.         indefinitely.  It is set to 0FFh to force its removal from
  78.         memory on the next warm boot
  79.  user   6 - Set this to 0FFh if this RSX is to be loaded only when being
  80.         executed on a non-banked CP/M Plus.  DIRLBL.RSX is an example
  81.         of the use of this flag.  The RSX handles BDOS function 100
  82.         in a non-banked environment
  83.  user   7 - This field is any eight byte literal to uniquely identify
  84.         the RSX
  85. loader    8 - This flag is set to 0FFh if the RSX is the CP/M Plus LOADER
  86.         and zero if it is a user RSX
  87.  
  88.  
  89. 3.  Resident System Extension Logic Flow
  90.  
  91.   The first thing a programmer needs to do in any RSX is save the caller's
  92. environment to allow normal processing of the BDOS request in subsequent
  93. RSXs.
  94.   Next, the RSX should retrieve the BDOS function number (from register C)
  95. and test for one of those being intercepted.
  96.   If the BDOS function is not one of those being intercepted, restore the
  97. caller's environment and jump to tag NEXT: (see line 2 in the RSX prefix
  98. above).  Note that any time an RSX passes control to BDOS, tag NEXT: must
  99. be used.  Remember that the RSX is essentially a part of BDOS and a call
  100. to address 0005 will produce unpredictable results.
  101.   If the BDOS function is being intercepted, perform any processing
  102. required and restore the caller's environment (except for any flags or
  103. indicators being returned).
  104.   Now, determine whether this RSX preprocesses or replaces the BDOS function
  105. and pass control either to label NEXT: to continue with the next RSX or an
  106. RET instruction to return immediately to the caller.
  107.  
  108.  
  109. 4.  BDOS Function 60 (call Resident System Extension)
  110.  
  111. This is the special BDOS function to be used to communicate with an active
  112. RSX.  The function is called with 60 (03Ch) in C and the RSX Parameter Block
  113. address in DE.  The parameter block has a structure as follows:
  114.  
  115.     RSXPB:    db    FUNCTION    ;the RSX function number
  116.         db    NUMPARMS    ;the number of parameter words
  117.         dw    PARAM1        ;parameter word 1
  118.         dw    PARAM2        ;parameter word 2
  119.         .
  120.         .
  121.         dw    PARAMn        ;parameter word n
  122.  
  123. The FUNCTION byte must a number between 0 and 127.  By use of this BDOS
  124. function, data and commands can be passed to or from an active RSX.  If
  125. no RSX traps this BDOS function, the BDOS returns 0FFh in registers A and L.
  126.  
  127. It might be useful to designate parameter one of the Parameter Block as
  128. a target RSX indicator (i.e. the RSX name).  In that way, multiple RSXs
  129. obtained from different sources can each use the full range of subfunctions
  130. and yet intercept only their own subfunctions.
  131.  
  132.  
  133. 5.  Preparing a Resident System Extension for Execution
  134.  
  135. An RSX is stored and loaded as part of a specially constructed COM file.
  136. The RSX is typically attached to a COM file which performs specific
  137. operations using the extensions provided by that RSX.  The RSX can,
  138. however, be attached to a dummy COM file so that the only operation
  139. performed is the RSX load.  In that case, the RSX is normally locked into
  140. memory until triggered for removal.  The GENCOM utility constructs this
  141. COM file according to user-defined parameter input.
  142.  
  143. 5.1  Assembling the RSX
  144.  
  145. The RSX must be a page relocatable file because its execution address
  146. is determined dynamically by the loader.  The RMAC assembler and LINK-80
  147. must therefore be used to assemble and link the RSX.
  148.  
  149.     A>RMAC RSXDEMO
  150.     A>LINK RSXDEMO [op]
  151.  
  152. 5.2  Assembling the Main Program
  153.  
  154. As was indicated above, the RSX is typically attached to some COM file
  155. that uses the extensions provided by that RSX.  In this example, an
  156. assembler program will be used to demonstrate both RSX construction and
  157. use of BDOS function 60 to control that RSX.  Use your word processor
  158. to split the following program into RSXINIT.ASM.
  159.  
  160. ; RSXINIT.ASM    copyright (c) 1983 by George F Peace
  161.  
  162. ; usage: RSXINIT            loads the RSX
  163. ;      RSXINIT <any parameter>    unloads the RSX
  164.  
  165. dma    equ    80h
  166. bdos    equ    5
  167. wboot    equ    0
  168. callrsx    equ    60
  169. rsx$init equ    13
  170. rsx$term equ    14
  171.  
  172.     org    100h
  173.     lda    dma        ;get command tail length
  174.     cpi    0        ;anything there?
  175.     jnz    termrsx        ;yes - assume terminate request
  176.     mvi    a,rsx$init    ;get initialization function
  177. loadrsx:
  178.     sta    rsxpb        ;store subfunction in parameter block
  179.     mvi    c,callrsx    ;get RSX command index
  180.     lxi    d,rsxpb        ;get RSX parameter block address
  181.     call    bdos
  182.     mvi    c,wboot        ;terminate the program but not the RSX
  183.     jmp    bdos
  184. termrsx:
  185.     mvi    a,rsx$term    ;get RSX termination function
  186.     jmp    loadrsx        ;now go set up the RSX
  187.  
  188. rsxname: db    'RSXTEST '    ;name of RSX we're calling
  189. rsxpb:    db    rsx$init    ;RSX initialization function
  190.     db    1        ;1 parameter word follows
  191.     dw    rsxname        ;parameter 1 address
  192.     end
  193.  
  194. The commands to assemble the control program are
  195.  
  196.     A>MAC RSXINIT
  197.     A>HEXCOM RSXINIT
  198.  
  199.  
  200. 5.3  Attaching the RSX to the Main Program
  201.  
  202. The final step in RSX construction is the generation of the special COM
  203. file containing both the main program and the attached RSX.  The GENCOM
  204. command is used for this purpose.  GENCOM requires that the RSX have a
  205. file type of RSX so it can be properly identified and included in the COM
  206. file.  
  207.  
  208.     A>RENAME RSXDEMO.RSX=RSXDEMO.PRL
  209.     A>GENCOM RSXINIT RSXDEMO
  210.  
  211.  
  212. 5.4  Using the Resident System Extension
  213.  
  214. Now that the RSXINIT COM file has been updated by GENCOM, it's time to
  215. try it out.  To load the RSX, type
  216.  
  217.     RSXINIT
  218.  
  219. then execute a program or issue a CCP command.  When you are finished
  220. testing the RSX, type
  221.  
  222.     RSXINIT <any parameter>
  223.  
  224. to remove the RSX from memory.  You can return the RSXINIT.COM file to
  225. its original unmodified state by typing
  226.  
  227.     GENCOM RSXINIT
  228.  
  229.  
  230. 6.  Excuses and Closing Comments
  231.  
  232. There are certainly more ways to implement an RSX than the one presented
  233. here.  My intent has been to provide a general introduction to the
  234. Resident System Function capability rather than a detailed text.  I believe
  235. the Digital Research documentation is an adequate reference text.  Why did
  236. I even provide this text if the DRI documents are "adequate"?  My CP/M
  237. Plus machine was provided with only the barest (non-DRI) documentation.  I
  238. had to gather the material piece-by-piece until I purchased the DRI manual
  239. set.  Maybe there are a few other frustrated Plus users out there too.
  240.  
  241.  
  242. I can be contacted at:    George F Peace
  243.             1703 Headwaters Road
  244.             Midlothian, Virginia  23113
  245.  
  246.         or the CP-MIG on CompuServe (id 71555,1501)
  247.  
  248. -----    -----    -----    -----    -----    -----    -----    -----    -----
  249.  
  250. CP/M is a registered trademark of Digital Research
  251. CP/M Plus, LINK-80, MAC, and RMAC are trademarks of Digital Research
  252. HEXCOM is anybody's guess
  253. rademark of Digital Research
  254. CP/M Plus, LINK-80, MAC, and RMAC are trademarks of Digita