RSX system Documentation (84/01/25) =================================== What is an RSX (Resident System Extension for CPM 2.2 only) ============== An RSX is a method of adding new system calls to the CPM system, which can then be called just like any other BDOS function. The RSX can also be used to intercept native calls and change their operation (ex. list output calls could be intercepted and spooled, or a program can "chain" to an arbitrary program by passing the command line). The RSX is also a mechanism (in this implementation) for installing new/revised i/o drivers, such as foreign disk systems, keyboard translators, spoolers, etc. This was written to implement the "chain" ability. Executing an RSX ================ Under this system, an RSX is stored as any other .COM file. To install it the .COM file is executed by typeing its name at the CCP prompt. To remove it enter its name again. In between installation and removal the RSX will be memory resident, and warm boots will not reload the CCP or BDOS system. At the same time the added BDOS call(s) or drivers are available. CAUTION: Some systems require a physical reboot (eg Kaypro 4) to change disk formats (density, single/double sided, etc). This will not occur when the RSX is active. CAUTION: The original Digital Research CCP will not start up a SUBMIT job when the RSX is active. In addition logging on to an invalid drive will hang the system until a reset. You can avoid this by installing CCPLUS, which will also provide automatic drive searches for applications. ZCPR has not been tested with this system. Memory usage: ============ The RSX is mounted below the CCP area, and thus reduces the available application memory. The utility HOWBIG shows the effective memory available at any time. Just enter d>howbig Making a new RSX (This system is for CPM 2.2) ================ Obviously, someone must write the system code needed. That is you. This system provides a standard method of installing and removing the code from your running system. The file RSX.Z80 is heavily annotated to show where the custom code should be inserted. The RSX installed by this only outputs a short message when called by an application program. You can test by loading it, then under DDT create system calls with the argument 100 (064h). If the (de) argument is 0 the returned value is 0 for no RSX present, non-zero if present and active. If the (de) argument is -1 (0ffffh) the RSX is made inactive, and will be removed on the next warm boot (^C). Alternatively the utility ENQUIRE can be used to pass arguments and display the results. Usage (parameters in hex) is: d>ENQUIRE rsxnum [param] which executes BDOS call rsxnum, with de=param To create a new RSX, you must first assemble (or relocate) two versions rsxzero.$$$ is "orged" or relocated to start at 0 rsxone.$$$ is "orged" or relocated to start at 0100h (normal) With DDT, load RELOCCP.SYS, and append, at 0200h, rsxzero.$$$ by B>DDT reloccp.sys ...signon etc... -irsxzero.$$$ -r100 (note the 0100h offset command) .....info. returned (This assumes a .COM type file. If it is) (a hex file with .HEX extension use r200) Now examine the bytes loaded at locations 203 thru 204 -d200,204 0200 C3 00 54 30 05 <--note this number, hex 0530, right byte 1st (number is for example only) Now find the location (-0100h) of the first free byte in the relocated image by: -h100,530 0630 0430 <--The left number (0630) is what you want and append the 0100h based image by -irsxone.$$$ -r630 (using the above number as offset) Next PC Save nnnn 0100 m (The "save" value from DDTY only) Note the "next" value loaded, use the left two digits as a hex number and save that number of pages. (DDTY5 will tell you in decimal) by exiting and executing save -^C (control-c) A>SAVE 12 temp.com (The "12" is for example only) Now execute temp.com. It will tell you how much to save A>temp now SAVE 7 A>SAVE 7 rsx.com (do it) You now have a usable new version of RSX, which will relocate itself into high memory when executed. If you are using other systems mounted below CCP in high memory, such as KEYS or one or more additional RSXs, the first such loaded will have protected the CCP memory (of 2k), and a further run of RSX will save a totally useless additional 2k. To avoid this by having the loader detect this situation and automatically avoid the extra memory save do: A>ddt rsx.com ....signon etc... -ireloccp.ovr (the "smarter" overlay for load only) -r -^C (control-c) A>save 7 rsx.com (same number as before) and you are all done. RSX call conventions ==================== When the RSX is installed it appears as a new CPM BDOS call, identified by the value in C, and receiving a parameter in DE. The DE parameter will usually be a pointer to some user memory area, e.g. an FCB. The following parameter values have been reserved (Note that under CPM a valid pointer to usable memory can never have these values): 0 Residence enquiry. If the RSX is mounted and active it will returng a non-zero value in A. If not mounted or inactive zero is returned (as will BDOS 2.2 for any invalid calls) 1 Return a pointer (in HL) to any data areas specific to the RSX. ex: disk drive parameters for a general foreign disk reader/writer, or table of key translation strings for a console key redefinition system. If the RSX is not resident or does not use such an area obviously the pointer is invalid. The code that uses such a pointer is specific to the RSX, and thus this usage is optional. -1 (or 0FFFFh). Remove the RSX. The memory used will be reclaimed, if possible, on the next warm boot. A limitation ============ Only one RSX (the first installed) can provide i/o drivers visible to BDOS. Any further ones cannot reliably find/modify/restore the BIOS pointers. Thus checks have been built in, and the user equate "driver", or patchable variable "chkflg" cause these checks to be executed. However, later RSXs can install bios modifications visible ONLY to application programs using direct BIOS calls through the pointer at location 1. KEYS is an example of an RSX providing BDOS visible bios changes (although built earlier, and does not use this exact mechanism). C.B Falconer (85/Jan/25)