home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / zcpr33 / jltools.lbr / JLCFG.MZO / JLCFG.MMO
Encoding:
Text File  |  1988-07-14  |  5.3 KB  |  197 lines
  1. JLCFG.MMO        7/8/88
  2.  
  3. In reading these notes, also look at the files:
  4.  
  5.     TESTCFG.ASM    - illustrates CFG parameters
  6.     RSXCFG.ASM    - configures a vanilla RSX 
  7.     TESTRSX.ASM    - very simple RSX
  8.     OKDRIVES.ASM    - simple RSX
  9.  
  10.  
  11. Current buffer limits:
  12.  
  13. Any single source file: 8K
  14. Initialization buffer:    1K
  15. ID buffer:        1K
  16.  
  17.          Rough notes on CFG option with JetLDR.
  18.  
  19. A configuration (CFG) module (in ZRL format) may be loaded as one
  20. file/member of the command-line list.  The file is loaded to a buffer,
  21. and relocated to that address.  The resulting code is then called
  22. at key points in the Jetload process, and may be used to customize
  23. the normal loading process.
  24.  
  25. The CFG feature is intended to  help automate the installation
  26. of system segments/modules that require special configuration.
  27. Examples would be:  linking up DateStamper to a DOS, loading an
  28. RSX or BSX, loading a DOS requiring special patches,  loading/relocating
  29. code into a new Z-COM patch area, and deinitializing/initializing
  30. an interrupt-driven bios module.
  31.  
  32.  
  33. For each file being loaded, JetLDR calls the CFG module at these
  34. points:
  35.  
  36. 1. Before relocating a ZRL file on pass1.  The CFG code can specify
  37.    a custom set of relocation base labels and addresses. (PASS1_FN).
  38.  
  39. 2. Before final relocation of a ZRL file on pass2. (PASS2_FN).
  40.  
  41. 3. Before validating the final image of the absolute or relocated
  42.    file.  CFG can do its own supplementary or alternative
  43.    checking here. (VALID_FN)
  44.  
  45. 4. Before moving the final image to the system address.  CFG
  46.    can, instead, move the image to banked memory, write
  47.    a system track, or whatever.  It may have specified
  48.    loading directly to the final address, in which case
  49.    no move is needed. (MOVE_FN)
  50.  
  51. 5. following completion of loading of the file.  CFG can
  52.    make any final patches here. (UPDATE_FN)
  53.   
  54.  
  55. ENTRY
  56.  
  57. The entry parameters when JetLDR calls CFG are:
  58.  
  59.   A =  package type (see below)
  60.   C =  JetLDR function number (1...5)
  61.  HL =  ptr to data structure (see below)
  62.  
  63.  
  64. EXIT
  65.  
  66. CFG must:
  67.   preserve ix, iy, af', bc', de', hl'
  68.   return A = result code (see below)
  69.  
  70.     To specify an alternate relocation base when
  71.     called at PASS1_FN and PASS2_FN, return
  72.  
  73.     hl  -> common_name_table
  74.     de  -> load_table
  75.     bc  -> final_table
  76.      a  =  ADDRESS_CODE
  77.  
  78.  
  79.                Initialization Code
  80.  
  81. For each module loaded (including CFG) JetLDR calls the "initbuf"
  82. code once, just before its UPDATE_FN call to CFG.  It then replaces
  83. the code in initbuf with a dummy routine.
  84.  
  85. Thus, any module may have initialization code, and this code will
  86. be executed after the module is relocated and moved to its final
  87. address. (For portability, the standard Z-System segments will
  88. not have, but they could, in principle; this feature is primarily
  89. for RSX, BSX, and other specialized modules).
  90.  
  91. Put the initialization code in the _INIT_ named common.  (The buffer
  92. is 1k).  The code should return A = 0 if all is ok.
  93. To cancel the UPDATE_FN call to CFG, set A = ABORTCODE = 0FFh.
  94.  
  95.  
  96. ;------------------------------------
  97.  
  98.            Required structrue of a CFG module:
  99.  
  100. name    CFGxxx            ; "CFG" required
  101.  
  102. CSEG
  103. begin:    jp    cfgstart    ; absolute jump to code
  104.     db    'Z3CFG'        ; exact signature
  105. ;....
  106. cfgstart:
  107.  
  108. ;...
  109.     ret
  110.  
  111. ; optionally, 
  112.  
  113.     include    Z3COMMON.LIB
  114.  
  115. ; to make system-segment references conveniently
  116. ; in the CFG code.
  117.  
  118. ; optionally,
  119.  
  120.     common /_INIT_/
  121. ;
  122. ; note that this is not called until AFTER the CFG code
  123. ; has ALREADY been entered (with module type = C = CFGCODE)
  124. ;...
  125.     ld    a,0        ; ok to proceed, or
  126.     ld    a,ABORTCODE    ; omit UPDATE_FN call to CFG
  127.     ret
  128.  
  129.  
  130. ;-------------------------------------------
  131.  
  132. ; (A) Package type value passed to cfg by JetLDR
  133. ;
  134. NOCODE        equ    0
  135. ;
  136. ENVCODE        equ    1    ; absolute
  137. TCAPCODE    equ    2    ; "
  138. NDRCODE        equ    3    ; "
  139. ;
  140. RCPCODE        equ    4    ; the rest are ZRL/REL
  141. FCPCODE        equ    5
  142. ;
  143. IOPCODE        equ    6
  144. CCPCODE        equ    7
  145. CP3CODE        equ    8
  146. DOSCODE        equ    9
  147. DO3CODE        equ    10
  148. BIOCODE        equ    11
  149. CFGCODE        equ    12
  150. RSXCODE        equ    13
  151. BSXCODE        equ    14
  152. ;
  153. LASTCODE    equ    14
  154. ;
  155. UNKNOWNCODE    equ    0FFh    ; none of the above was identified
  156. ;
  157. ;
  158. ; (C) function value passed to cfg
  159. ;
  160. PASS1_FN    equ    1
  161. PASS2_FN    equ    2
  162. VALID_FN    equ    3
  163. MOVE_FN        equ    4
  164. UPDATE_FN    equ    5
  165.  
  166. ; (A) code returned by cfg
  167. ; 
  168. EXIT_CODE    equ    0FEh    ; exit immediately from JetLDR
  169. ABORT_CODE    equ    0FFh    ; abort loading this file, go to next file
  170. PROCEED_CODE    equ    0    ; JL continues with the current function
  171. SLEEP_CODE    equ    1    ; JL replaces CFG code with a dummy cfg
  172. SKIP_CODE    equ    2    ; JL skips the current function
  173. ADDRESS_CODE    equ    3    ; JL uses the CFG-supplied addresses
  174.                 ; for load/relocation
  175.  
  176. ; (HL) pointer to this structure  passed to cfg by JetLDR
  177. ;
  178. cfgstruct:
  179.     jp    pstr        ; print nul-term. string at hl
  180.     jp    malloc        ; allocate memory
  181. actfcb.:ds    2        ; ptr to fcb (or lbr directory entry)
  182. relname.:ds    2        ; ptr to name of REL module
  183. time.:    ds    2        ; ptr to 4-byte time string (SLR only)
  184.     dw    idbuf        ; ptr to _ID_ buffer
  185.     dw    initbuf        ; ptr to _INIT_ buffer
  186.     dw    sourcebuf    ; ptr to source buffer
  187.     dw    relbuf        ; ptr to (relocated) code buffer
  188.     dw    cmnnametbl    ; ptr to named-common structures
  189.     dw    loadtbl        ; ptr to load buffer table
  190.     dw    finaltbl    ; ptr to final bases
  191.     dw    sizetbl        ; ptr to sizes of segments
  192. ;
  193. 
  194. ; (A) code returned by cfg
  195. ; 
  196. EXIT_CODE    equ    0FEh    ; exit immediately from JetLDR
  197. ABORT_CODE    equ    0F