home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / ENTERPRS / CPM / UTILS / F / RSXMAKER.LZH / RSXMAKER.DOC < prev    next >
Text File  |  1991-01-15  |  19KB  |  498 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                             RSXMAKER
  11.  
  12.                           User's Guide
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.            Copyright (c) 1986 by AutoSoft Incorporated
  24.  
  25.       This software may be used for non-commercial purposes
  26.       only.  No commercial use may be made of RSXMAKER or
  27.      any utilties produced by RSXMAKER without the express
  28.           written permission of AutoSoft Incorporated.
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.                      AutoSoft Incorporated
  43.                      166 Santa Clara Avenue
  44.                       Oakland,  CA  94610
  45.                          (415) 658-2881
  46.  
  47.  
  48.         For assistance with this or other AutoSoft products,
  49.          use the AutoSoft Customer Service ModemMail BBS at
  50.                 (408) 336-8080.  Post mail to SYSOP.
  51.  
  52. 1 INTRODUCTION
  53.  
  54.  
  55. 1.1 WHAT IS AN RSX?
  56.  
  57. RSX stands for "Resident System Extension".  What this means is that 
  58. an RSX is an extension to the operating system (in this case CP/M-80) 
  59. that resides in memory along with the operating system.  Usually an 
  60. RSX is used to provide a facility or capability which the operating 
  61. system lacks in such a way that transient programs are unaware of the 
  62. change.
  63.  
  64. Facilities that might be added to CP/M-80 through the use of an RSX 
  65. include print spoolers, keyboard macros, remote consoles, access 
  66. control to disks/user areas, etc.
  67.  
  68. RSX's operate by relocating themselves in memory to a location just 
  69. below CP/M's CCP (Console Command Processor), which allows other 
  70. programs to run in the normal way without interfering with the RSX.
  71.  
  72. Some other utility programs operate in this way, co-residing with 
  73. a transient program and the operating system in memory.  Usually, these 
  74. utilities do not tolerate the presence of another such utility very 
  75. well.  
  76.  
  77. An RSX, however, is specifically designed to allow many RSX-based 
  78. utilities to be present in memory together, and either cooperate or 
  79. ignore each other, as required.  Thus, an access control RSX can be 
  80. combined with a remote console RSX, for example, to create a secure 
  81. remote CP/M system.  If the access control is not needed, that RSX is 
  82. simply not loaded.
  83.  
  84.  
  85. 1.2 RSX MEMORY MANAGEMENT
  86.  
  87. RSX's are loaded just under the CCP, each succeeding installation 
  88. loading its RSX just under the previous one.  Thus, as more RSX's are 
  89. installed, the available TPA (Transient Program Area), the space 
  90. available for normal programs, gets smaller and smaller.
  91.  
  92. The RSXMAKER, when it removes an RSX, reclaims the memory used by 
  93. that RSX by shuffling the remaining RSX's up in memory after the 
  94. removal.  This is unlike other RSX-type systems, which merely mark an 
  95. RSX for removal, waiting until all those below it in memory are also 
  96. marked for removal before removing the whole lot.
  97.  
  98.  
  99. 1.3 RSX CONTROL FLOW
  100.  
  101. An RSX's code executes by intercepting BDOS calls from transient 
  102. programs, effectively "hitching a ride" on the operating system.  The 
  103. last-installed RSX always gains control first, and when it is done, 
  104. passes control either back to the transient program or on to the next 
  105. RSX between it and the BDOS.  If all the RSX's allow control to pass 
  106. upward, eventually the BDOS will get the request.
  107.  
  108. This allows RSX's to modify system behavior independent of the 
  109. transient program being executed.
  110.  
  111.  
  112. 1.4 WHAT IS IN THIS PACKAGE?
  113.  
  114. This package includes a utility program to allow easy construction of 
  115. RSX's of your own, and to manage a collection of RSX's in memory.  
  116. The program RSX.COM allows you to install and remove RSX's as well as 
  117. show information about currently resident RSX's.  It also allows you 
  118. to create self-installing RSX's of your own so that you needn't use 
  119. the RSX.COM program to use the RSX.
  120.  
  121. Also included is a template RSX source file with all the standard 
  122. routines already coded so that you can devote your efforts to the 
  123. function of the RSX you are building rather than the details of the 
  124. RSX implementation.
  125.  
  126.  
  127.  
  128. 2 THE RSXMAKER UTILITY (RSX.COM)
  129.  
  130.  
  131. 2.1 RSX COMMANDS
  132.  
  133. The RSXMAKER, RSX.COM, accepts arguments on the command line as 
  134. shown below.  All of the commands may be shortened to a single 
  135. character (e.g. SHOW can be entered as S).
  136.     
  137.     A>RSX                       No arguments - displays a help screen
  138.     
  139.     A>RSX SHOW                  Displays information about the RSX's
  140.                                 currently resident in memory.  
  141.                                 Information includes the base address,
  142.                                 name, description, and control flags
  143.                                 for each RSX.
  144.     
  145.     A>RSX INSTALL filename      Installs the RSX contained in the file
  146.                                 specified.  The file must have a 
  147.                                 filetype of .RSX, and must have been
  148.                                 prepared as described in the section
  149.                                 on creating an RSX.
  150.     
  151.     A>RSX REMOVE rsxname        Removes the specified RSX from memory,
  152.                                 relocating any remaining RSX's so as 
  153.                                 to reclaim the memory space used by 
  154.                                 the removed RSX.
  155.     
  156.     A>RSX MAKE filename         Creates a .COM file which, when 
  157.                                 executed, installs the RSX contained
  158.                                 in the specified file.  The file must
  159.                                 have a filetype of .RSX, and must have
  160.                                 been prepared as described in the
  161.                                 section on creating an RSX.  The .COM
  162.                                 file's filename is derived from the
  163.                                 RSX NAME string contained in the RSX
  164.                                 header.
  165.  
  166.  
  167. 2.2 FILE NAMING CONVENTIONS
  168.  
  169. It is not necessary that the file containing an RSX have the same 
  170. name as the RSX.  It is, however, advisable to make them the same in 
  171. order to avoid confusion.  Since the RSX name is a maximum of eight 
  172. characters and so it a CP/M filename, this recommendation should 
  173. place little hardship on the implementor.
  174.  
  175. The filetype .RSX is reserved for RSX files to be used as input to 
  176. the RSXMAKER.  They would otherwise be .COM files, being the 
  177. product of LOAD.  The renaming is required to help avoid the 
  178. incidence of installing a .COM file which is not an RSX -- this 
  179. usually crashes the system.
  180.  
  181.  
  182. 3 CREATING AN RSX
  183.  
  184. An RSX consists of two major pieces: the RSX header and the RSX code. 
  185.  
  186.  
  187. 3.1 THE RSX HEADER
  188.  
  189. The header contains information required by the RSXMAKER for 
  190. installation and relocation of the RSX.  The majority of the header 
  191. need not be altered from that found in the template RSX RSXTEM.ASM.
  192. Those fields which are of interest to the RSX creator are discussed 
  193. below.
  194.  
  195.  
  196. 3.1.1 THE RSX HEADER FLAGS
  197.  
  198. The RFLAGS word contains bit flags used by the RSXMAKER.  Depending 
  199. on the purpose of your RSX, you may want to include or leave out some 
  200. or all of the flags.  The flags and their functions are listed below.
  201.  
  202.     FIRST       This flag is set by the RSXMAKER in the RSX 
  203.                 residing in the highest memory location.  It is 
  204.                 cleared by the RSXMAKER in RSX's residing in other 
  205.                 locations.
  206.                 
  207.     LAST        This flag is set by the RSXMAKER to mark the RSX 
  208.                 residing in the lowest memory location.  It is 
  209.                 cleared by the RSXMAKER in RSX's residing in other 
  210.                 locations.
  211.                 
  212.     NOREMOV     If this flag is included in the RFLAGS word, the
  213.                 RSXMAKER will not remove the RSX even if it is 
  214.                 commanded to do so.  This might be desirable, for 
  215.                 example, in an RSX performing password control.
  216.  
  217.     MULTI       If this flag is included, the RSXMAKER will load 
  218.                 additional copies of an existing RSX on subsequent 
  219.                 install requests.  If this flag in not included, 
  220.                 multiple install requests of the same RSX will not 
  221.                 result in additional copies being placed in memory.
  222.  
  223.     REINIT      If this flag is set, each install request for an 
  224.                 existing RSX causes the initialization routines of 
  225.                 those already in memory to be executed.
  226.                 
  227.     NOMORE      If this flag is set, the RSXMAKER will not load
  228.                 any more RSX's after this one.  This might be useful 
  229.                 in a situation where the RSX is performing vital 
  230.                 security functions which could be compromised by 
  231.                 another RSX.
  232.                 
  233.     NORELO      If this flag is set, the RSX will not be relocated in 
  234.                 the event of an RSX in upper memory being removed.  
  235.                 This will result in the memory used by the removed 
  236.                 RSX not being reclaimed.  This might be needed in an 
  237.                 RSX which is referenced by other software which could 
  238.                 lose track of the RSX if it moved in memory.
  239.                 
  240.     RELINI      This flag is an alternative, although not a required 
  241.                 one, to the NORELO flag.  If this flag is set, after 
  242.                 relocation, the RSX's initialization will be called, 
  243.                 allowing the RSX to adjust to its new location, if 
  244.                 required.
  245.                 
  246.     OVRLAY      This flag causes the RSX to overlay the CP/M CCP if 
  247.                 it is the first one installed.  This might be useful 
  248.                 in applications where a maximum amount of memory is 
  249.                 needed.  Note that no commands may be issued after 
  250.                 RSX installation, since the CCP is no longer in 
  251.                 memory.
  252.                 
  253. The flags are inserted in the RFLAGS word by specifying them in a 
  254. series separated by "+" signs.  For example, if I wished my RSX to be 
  255. re-initialized upon subsequent install attempts and when relocated, I 
  256. would edit the RFLAGS declaration to be as shown below.
  257.  
  258.     RFLAGS: DB      REINIT+RELINI       ; Init on install and relocate
  259.     
  260.  
  261. 3.1.2 THE RNAME AND RDESC FIELDS
  262.  
  263. The RNAME string is the name by which the RSXMAKER will recognize 
  264. the RSX.  This string *must* be eight characters long, must be padded 
  265. with spaces on the right, must be uppercase, and may not contain any 
  266. embedded spaces.  The following list of valid and invalid RSX names 
  267. exemplifies these constraints.
  268.  
  269.     Valid RSX Names     Invalid RSX Names
  270.     
  271.     "REMOTE  "          "remote  "              lowercase not allowed
  272.     "MYRSX   "          "MY RSX  "              no embedded spaces
  273.     "SECURITY"          "SECURITYRSX"           too long
  274.     "ACCESS  "          "  ACCESS"              spaces on left
  275.     "THERSX  "          "THERSX"                no padding to 8 chars
  276.     
  277. The RDESC string may be of any length, although a maximum of about 16 
  278. characters is probably a practical limit.  This description string is 
  279. displayed by the RSXMAKER's SHOW command.  The RDESC string is 
  280. null-terminated, meaning it must end with a byte of zero.  An example 
  281. is shown below.
  282.  
  283.     RDESC: DB      'This is the description',0  ; Note null terminated
  284.     
  285.  
  286. 3.2 RSX CODE SECTION
  287.  
  288. The code of an RSX consists of four routines, which are called at 
  289. various times throughout the life of the RSX.
  290.  
  291.     o  The Initialization Routine
  292.     
  293.     o  The Termination Routine
  294.     
  295.     o  The BDOS Intercept Routine
  296.     
  297.     o  The WBOOT Intercept Routine
  298.     
  299.     
  300. Depending on the purpose of your RSX, one or more of these routines 
  301. may be altered from the default routines provided in the template RSX.
  302.  
  303.  
  304. 3.2.1 THE INITIALIZATION ROUTINE
  305.  
  306. The initialization routine is called after the RSX is loaded, if 
  307. the REINIT flag is set, on subsequent installs of the same RSX, and, 
  308. if the RELINIT flag is set, whenever the RSX is relocated in memory.
  309.  
  310. In the template RSX, the initialization routine just writes a message 
  311. to the console indicating that the RSX has been successfully 
  312. installed.
  313.  
  314. A print spooler RSX might use the initialization routine to locate 
  315. the filename in the CP/M default FCB at 5CH and open the file.
  316.  
  317.  
  318. 3.2.2 THE TERMINATION ROUTINE
  319.  
  320. The termination routine is called just before the RSXMAKER removes 
  321. the RSX from memory.
  322.  
  323. In the template RSX, the termination routine merely issues a message 
  324. stating that the RSX is terminating.
  325.  
  326. If your RSX altered any CCP, BDOS, or BIOS addresses, this routine 
  327. could be used to undo the alterations.
  328.  
  329.  
  330. 3.2.3 THE BDOS INTERCEPT ROUTINE
  331.  
  332. This routine gains control whenever a transient program issues a CP/M 
  333. BDOS call.  The function number is contained in C, and the parameter, 
  334. if any in E or DE.  This routine allows you to alter or monitor the 
  335. behavior of BDOS functions, and to add new functions of your own.
  336.  
  337. Note that in returning from a new function, you should obey the CP/M 
  338. BDOS conventions for register usage described in the CP/M 2.2 
  339. Interface Guide.
  340.  
  341. The template BDOS intercept routine switches to a local stack and 
  342. then passes the call on to the next RSX, or the BDOS, using a JMP 
  343. NEXT, taking no action.
  344.  
  345. Note that you should never CALL 0005 from within an RSX, but rather 
  346. use CALL NEXT instead, giving the RSX's higher in memory a chance to 
  347. intercept the function also.  Generally, passing the function through 
  348. location 0005 will result in an endless loop as the RSX repeatedly 
  349. traps the call and passes it back through location 0005.
  350.  
  351. This is perhaps the most potentially useful routine in the RSX code 
  352. section.
  353.  
  354.  
  355. 3.2.4 THE WBOOT INTERCEPT ROUTINE
  356.  
  357. This routine is called whenever a BDOS function zero is passed to the 
  358. BDOS, and whenever control is passed through the warm boot vector at 
  359. location 0000.
  360.  
  361. The template routine, if the RSX is FIRST (i.e. it is the last in the 
  362. RSX chain), issues a disk reset and reloads some addresses in low 
  363. memory, mimicking the expected BIOS warm boot activity.  You might 
  364. find it useful, in a hard-disk environment, to dipense entirely with 
  365. the disk reset, which will markedly speed up the warm boot function.
  366.  
  367. Note that the BIOS warm boot code is never called; control is merely 
  368. passed back to the CCP after all the RSX;s have had a chance.
  369.  
  370.  
  371. 3.3 CODING NOTES
  372.  
  373. A number of items must be kept in mind by the RSX programmer.
  374.  
  375.  
  376. 3.3.1 USE OF THE 8080 INSTRUCTION SET
  377.  
  378. The relocation system currently does not recognize Z80 opcodes.  
  379. Thus, RSX's must be written entirely in 8080 assembly code.
  380.  
  381.  
  382. 3.3.2 USE OF THE LXI INSTRUCTION
  383.  
  384. Since it is impossible for the relocation code to determine whether 
  385. the operand of an LXI instruction is a value or an address, assuming 
  386. that the value lies within the address range being relocated, the RSX 
  387. programmer should never load a value into a register pair with the 
  388. LXI instruction.  Only addresses should be loaded using the LXI 
  389. instruction.
  390.  
  391. Instead of the LXI instruction, use two MVI instructions as shown 
  392. below.
  393.  
  394.     ;   LXI     D,035AH         ; Don't use LXI to load values
  395.         MVI     E,5AH           ; Instead, use two MVI's
  396.         MVI     D,03H           ; Thusly
  397.     
  398.  
  399. 3.3.3 USE CALL NEXT FOR BDOS ACCESS
  400.  
  401. Never use CALL 0005 to issue BDOS calls.  Use instead CALL NEXT, 
  402. which obeys the RSX chaining rules.
  403.  
  404.  
  405. 3.3.4 ALWAYS USE A LOCAL STACK
  406.  
  407. Always switch to an RSX-local stack before doing any processing.  Use 
  408. the code shown in the template RSX to do this.
  409.  
  410.  
  411. 3.3.5 DO NOT MIX CODE AND DATA
  412.  
  413. The RSXMAKER's relocation routines will not properly relocate data 
  414. which is embeeded within a code segment.  Thus in-line print routines 
  415. which require the text to be printed to follow the CALL to the print 
  416. routine may not be used within an RSX.
  417.  
  418. Only code is allowed between the labels RSXCODE and RSXDATA in the 
  419. RSX template, and only data is allowed between the labels RSXDATA and 
  420. RSXEND.
  421.  
  422.  
  423. 3.4 BUILDING THE RSX
  424.  
  425.  
  426. 3.4.1 STEP BY STEP
  427.  
  428. Follow the steps described below in building your RSX.
  429.  
  430.     1. Make a copy of the RSXTEM.ASM template file with the name
  431.        you plan to use for your RSX.
  432.     
  433.     2. Edit the new template file to accomplish the functions required
  434.        of your RSX.
  435.     
  436.     3. Assemble the .ASM RSX source file.
  437.     
  438.     4. Create a .COM file from the assembler's output using LOAD.COM.
  439.     
  440.     5. Change the filetype of the .COM file to .RSX using the REN 
  441.        command.
  442.  
  443.     6. Install the RSX with RSXMAKER and test its function.
  444.     
  445.     7. Repeat steps 2 through 6 until the RSX is functioning properly.
  446.     
  447.     8. User RSXMAKER's MAKE command to create a self-installing RSX.
  448.     
  449.  
  450. 3.4.2 EXAMPLE USING RSXTEM
  451.  
  452. The following is an example using the supplied RSXTEM template RSX to 
  453. demonstrate steps 3 through 8 above.
  454.  
  455.     A>ASM RSXTEM                        Assemble the template source
  456.     CP/M ASSEMBLER - VER 2.0
  457.     0205
  458.     002H USE FACTOR
  459.     END OF ASSEMBLY
  460.     
  461.     A>LOAD RSXTEM                       Create .COM file from .HEX
  462.     FIRST ADDRESS 0100
  463.     LAST  ADDRESS 0204
  464.     BYTES READ    00F5
  465.     RECORDS WRITTEN 03
  466.     
  467.     A>REN RSXTEM.RSX=RSXTEM.COM         Rename the .COM to .RSX
  468.     
  469.     A>RSX INS RSXTEM                    Install using RSXMAKER
  470.     Template RSX initialized.           Initialization message
  471.     
  472.     A>^C                                Warm boot
  473.     Template RSX active.                Warm boot message
  474.     
  475.     A>RSX SHO                           Show installed RSX's
  476.     
  477.     Base Name     Description
  478.     ----------------------------------------------------------------
  479.     D200 RSXTEM   AutoSoft RSX Template (first last reinit multi)
  480.     
  481.     A>RSX REM RSXTEM                    Remove the RSX
  482.     Template RSX terminated.            Termination message.
  483.     
  484.     A>RSX SHO                           Show installed RSX's
  485.     
  486.     There are no RSX's installed.
  487.     
  488.     A>RSX MAKE RSXTEM                   Make self-installing RSXTEM
  489.     
  490.     RSXTEM.COM created.
  491.     
  492.     A>RSXTEM                            Test self-installing RSXTEM
  493.     Template RSX initialized.           Initialization message.
  494.     
  495.     A>RSX REM RSXTEM                    Remove it
  496.     Template RSX terminated.            Termination message.
  497.     
  498.