chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/sh/sapphire

   1 ;
   2 ; sapphire.sh
   3 ;
   4 ; Initialise a Sapphire application and libraries
   5 ;
   6 ; © 1994-1998 Straylight
   7 ;
   8
   9 ;----- Licensing note -------------------------------------------------------
  10 ;
  11 ; This file is part of Straylight's Sapphire library.
  12 ;
  13 ; Sapphire is free software; you can redistribute it and/or modify
  14 ; it under the terms of the GNU General Public License as published by
  15 ; the Free Software Foundation; either version 2, or (at your option)
  16 ; any later version.
  17 ;
  18 ; Sapphire is distributed in the hope that it will be useful,
  19 ; but WITHOUT ANY WARRANTY; without even the implied warranty of
  20 ; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21 ; GNU General Public License for more details.
  22 ;
  23 ; You should have received a copy of the GNU General Public License
  24 ; along with Sapphire.  If not, write to the Free Software Foundation,
  25 ; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26
  27 ;----- Overview -------------------------------------------------------------
  28 ;
  29 ; Functions provided:
  30 ;
  31 ;  sapphire_init
  32 ;  sapphire_libInit
  33 ;  sapphire_disable
  34 ;  sapphire_doInit
  35 ;  sapphire_doLibInit
  36 ;  sapphire_doDisable
  37 ;  sapphire_heapAddr
  38 ;  sapphire_appName
  39 ;  sapphire_resetStack
  40 ;  sapphire_global
  41 ;
  42 ; Macros provided:
  43 ;
  44 ;   WSPACE
  45
  46                 [       :LNOT::DEF:sapphire__dfn
  47                 GBLL    sapphire__dfn
  48
  49 ; --- sapphire_init ---
  50 ;
  51 ; On entry:     R0 == pointer to application name
  52 ;               R1 == application's workspace size
  53 ;               R2 == size of stack required
  54 ;
  55 ; On exit:      R10 == pointer to heap base
  56 ;               R11 == pointer to ScratchPad
  57 ;               R12 == pointer to application workspace
  58 ;               R13 == pointer to full descending stack
  59 ;               Other registers are corrupted
  60 ;
  61 ; Use:          Initialises the Sapphire kernel, sets up the memory map,
  62 ;               and allocates workspace for library and client units.  The
  63 ;               initialisation performed is fairly minimal; in particular,
  64 ;               the library units are not initialised -- you must call
  65 ;               sapphire_libInit for this to take place.  This allows you
  66 ;               to check command line arguments etc. before initialising
  67 ;               the Wimp.
  68
  69                 IMPORT  sapphire_init
  70
  71 ; --- sapphire_disable ---
  72 ;
  73 ; On entry:     R0 == pointer to 0-terminated list of initialise routines
  74 ;
  75 ; On exit:      --
  76 ;
  77 ; Use:          Prevents the given initialisation routines from being called.
  78 ;               This is mainly useful in the dynamic-linking environment,
  79 ;               where all Sapphire units are normally active.  This routine
  80 ;               allows you to inactivate units which for example do not
  81 ;               have the resources they require, or use up unnecesary
  82 ;               memory.
  83
  84                 IMPORT  sapphire_disable
  85
  86 ; --- sapphire_libInit ---
  87 ;
  88 ; On entry:     --
  89 ;
  90 ; On exit:      --
  91 ;
  92 ; Use:          Initialises the Sapphire library and client units.
  93
  94                 IMPORT  sapphire_libInit
  95
  96 ; --- sapphire_doInit ---
  97 ;
  98 ; On entry:     R0 == pointer to application name
  99 ;               R1 == client workspace size
 100 ;               R2 == requested stack size
 101 ;               R3 == pointer to initialisation table
 102 ;
 103 ; On exit:      R10 == base address of Sapphire heap
 104 ;               R11 == pointer to scratchpad and global data
 105 ;               R12 == pointer to client global workspace
 106 ;               R13 == pointer to a full descendion stack
 107 ;
 108 ; Use:          Performs initialisation of the Sapphire library and the
 109 ;               client's sections.  This is intended for use by the Sapphire
 110 ;               stub, while initialising the dynamically linked version of
 111 ;               Sapphire.
 112
 113                 IMPORT  sapphire_doInit
 114
 115 ; --- sapphire_doLibInit ---
 116 ;
 117 ; On entry:     R0 == address of library initialisation table
 118 ;
 119 ; On exit:      --
 120 ;
 121 ; Use:          Initialises all currently uninitialised library units.
 122
 123                 IMPORT  sapphire_doLibInit
 124
 125 ; --- sapphire_doDisable ---
 126 ;
 127 ; On entry:     R0 == pointer to list of initialise routines to disable
 128 ;               R1 == pointer to initialisation table
 129 ;
 130 ; On exit:      --
 131 ;
 132 ; Use:          Prevents the given initialisation routines from being
 133 ;               called.  This is mainly useful in a dynamically linked
 134 ;               environment.
 135
 136                 IMPORT  sapphire_doDisable
 137
 138 ; --- sapphire_heapAddr ---
 139 ;
 140 ; On entry:     --
 141 ;
 142 ; On exit:      R1 == pointer to the heap base (for passing to OS_Heap)
 143 ;
 144 ; Use:          Returns the address of the Sapphire heap.
 145
 146                 IMPORT  sapphire_heapAddr
 147
 148 ; --- sapphire_appName ---
 149 ;
 150 ; On entry:     --
 151 ;
 152 ; On exit:      R0 == pointer to application name (NULL terminated)
 153 ;
 154 ; Use:          Returns a pointer to the application's name.
 155
 156                 IMPORT  sapphire_appName
 157
 158 ; --- sapphire_resetStack ---
 159 ;
 160 ; On entry:     --
 161 ;
 162 ; On exit:      R13 == stack pointer
 163 ;
 164 ; Use:          Resets R13 to point to the top of the stack.
 165
 166                 IMPORT  sapphire_resetStack
 167
 168 ; --- sapphire_global ---
 169 ;
 170 ; On entry:     R0 == magic identifier for global variable
 171 ;               R1 == size of area required
 172 ;
 173 ; On exit:      R0 == pointer to area
 174 ;               CS if the area already exists, CC otherwise
 175 ;
 176 ; Use:          Locates (and creates if necessary) a `named' global area
 177 ;               which can be used for inter-section communication without
 178 ;               the necessity for dependencies.
 179 ;
 180 ;               There is a limit on the number of global areas allowed, but
 181 ;               this can be raised fairly easily if necessary.
 182 ;
 183 ;               If an area can't be created, an error is generated.
 184
 185                 IMPORT  sapphire_global
 186
 187 ; --- Data relative to R11 ---
 188
 189                 ^       0,R11
 190 sapph__R11      #       0                       ;Make a symbol for R11
 191
 192 sapph_scratchpad EQU    sapph__R11-0            ;Scratchpad data area
 193                 [       :LNOT::DEF: sapph__specialWorkspace
 194 sapph_workspace EQU     sapph__R11-4            ;Workspace base address
 195                 ]
 196 sapph_stackBase EQU     sapph__R11-8            ;The top of the system stack
 197 sapph_heapBase  EQU     sapph__R11-12           ;Base address of the heap
 198 sapph_appName   EQU     sapph__R11-16           ;Pointer to application name
 199 sapph_clientWS  EQU     sapph__R11-20           ;Address of client's space
 200
 201 ; --- Macro: WSPACE ---
 202 ;
 203 ; Arguments:    addr == address of a word containing the workspace offset
 204 ;               reg == (optional) destination register -- default is R12
 205 ;               off == (optional) offset from R11 -- default is -4
 206 ;
 207 ; Use:          Locates a unit's workspace.  The code generated will corrupt
 208 ;               R14.  Therefore you must save this register.
 209
 210                 MACRO
 211 $label          WSPACE  $addr,$reg
 212
 213                 IMPORT  |__sph_workoff|,WEAK
 214
 215                 LCLS    r
 216
 217                 [       "$reg"=""
 218 r               SETS    "R12"
 219                 |
 220 r               SETS    "$reg"
 221                 ]
 222
 223                 ALIGN
 224 $label
 225                 LDR     $r,$addr
 226
 227 ;               LDR     R14,sapph_workspace
 228                 DCD     |__sph_workoff| + &E51BE004
 229
 230                 ADD     $r,R14,$r
 231
 232                 MEND
 233
 234                 ]
 235
 236 ;----- That's all, folks ----------------------------------------------------
 237
 238                 END