chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/sh/xfer/load

   1 ;
   2 ; load.sh
   3 ;
   4 ; Loading and importing of files
   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 ;  load
  32 ;  load_initBuf
  33 ;  load_killBuf
  34 ;  load_extendBuf
  35 ;  load_doneBuf
  36 ;  load_file
  37
  38                 [       :LNOT::DEF:load__dfn
  39                 GBLL    load__dfn
  40
  41 ; --- load ---
  42 ;
  43 ; On entry:     R0 == pointer to entry point block
  44 ;               R1 == value of R10 to pass to entry points
  45 ;               R2 == value of R12 to pass to entry points
  46 ;
  47 ; On exit:      --
  48 ;
  49 ; Use:          Attempts to load a file after receipt of a Message_DataSave,
  50 ;               Message_DataLoad or Message_DataOpen.  If user entries for
  51 ;               RAM transfer are provided, this is attempted, although the
  52 ;               entries must also be aware that file transfer may be
  53 ;               required.
  54
  55                 IMPORT  load
  56
  57 ; --- load_initBuf ---
  58 ;
  59 ; On entry:     R1 == estimated file size
  60 ;               R2 == pointer to flex anchor (unallocated)
  61 ;
  62 ; On exit:      R0 == pointer to buffer start
  63 ;               R1 == buffer size
  64 ;               May return an error
  65 ;
  66 ; Use:          Initialises a flex block for use as a RAM transfer buffer.
  67 ;               This routine is suitable for use as the initBuf routine for
  68 ;               RAM transfer loading.
  69
  70                 IMPORT  load_initBuf
  71
  72 ; --- load_killBuf ---
  73 ;
  74 ; On entry:     R2 == pointer to flex anchor
  75 ;
  76 ; On exit:      --
  77 ;
  78 ; Use:          Frees a flex block.  This routine should be used to free
  79 ;               the buffer used for RAM transfer.
  80
  81                 IMPORT  load_killBuf
  82
  83 ; --- load_extendBuf ---
  84 ;
  85 ; On entry:     R0 == pointer to previous buffer
  86 ;               R1 == size of previous buffer
  87 ;               R2 == pointer to flex anchor
  88 ;
  89 ; On exit:      R0 == pointer to a new buffer
  90 ;               R1 == size of the new buffer
  91 ;               May return an error
  92 ;
  93 ; Use:          Extends the flex block if it was initially too small.
  94 ;               This routine is designed to be used as the extend routine
  95 ;               during RAM transfer.
  96
  97                 IMPORT  load_extendBuf
  98
  99 ; --- load_doneBuf ---
 100 ;
 101 ; On entry:     R1 == actual size of data
 102 ;               R2 == pointer to flex anchor
 103 ;
 104 ; On exit:      --
 105 ;
 106 ; Use:          Sets the block into which the data has been loaded to the
 107 ;               correct exact size.
 108
 109                 IMPORT  load_doneBuf
 110
 111 ; --- load_file ---
 112 ;
 113 ; On entry:     R1 == pointer to filename to load
 114 ;               R2 == pointer to flex anchor
 115 ;
 116 ; On exit:      R0 == size of file loaded
 117 ;               May return an error
 118 ;
 119 ; Use:          Loads a named file into a flex block for your delectation.
 120
 121                 IMPORT  load_file
 122
 123 ;----- User entry points ----------------------------------------------------
 124
 125                 ^       0
 126
 127 lEntry__initBuf #       4                       ;Create a load buffer
 128                                                 ;On entry:
 129                                                 ;  R0 == ptr to `filename'
 130                                                 ;  R1 == estimated file size
 131                                                 ;  R2 == 0
 132                                                 ;On exit:
 133                                                 ;  R0 == ptr to buffer start
 134                                                 ;  R1 == ptr to buffer end
 135                                                 ;  R2 == buffer `handle'
 136                                                 ;  R10 may be updated
 137
 138 lEntry__killBuf #       4                       ;Destroy the load buffer
 139                                                 ;On entry:
 140                                                 ;  R0 == ptr to buffer start
 141                                                 ;  R1 == ptr to buffer end
 142                                                 ;  R2 == buffer `handle'
 143                                                 ;On exit:
 144                                                 ;  --
 145
 146 lEntry__extend  #       4                       ;Extend the load buffer
 147                                                 ;On entry:
 148                                                 ;  R0 == ptr to buffer start
 149                                                 ;  R1 == ptr to buffer end
 150                                                 ;  R2 == buffer `handle'
 151                                                 ;On exit:
 152                                                 ;  R0-R2 updated
 153
 154 lEntry__doneBuf #       4                       ;All data is now loaded
 155                                                 ;On entry:
 156                                                 ;  R0 == ptr to `filename'
 157                                                 ;  R1 == total size of data
 158                                                 ;  R2 == buffer `handle'
 159                                                 ;On exit:
 160                                                 ;  --
 161
 162 lEntry__file    #       4                       ;Load data from a file
 163                                                 ;On entry:
 164                                                 ;  R0 == ptr to `filename'
 165                                                 ;  R1 == file to load
 166                                                 ;  R2 == 0 if file unsafe
 167                                                 ;On exit:
 168                                                 ;  R10 may be updated
 169
 170 lEntry__done    #       4                       ;Completed loading
 171                                                 ;On entry:
 172                                                 ;  R0 == ptr to `filename'
 173                                                 ;  R1 == safeness indicator
 174                                                 ;On exit:
 175                                                 ;  --
 176
 177 lEntry__failed  #       4                       ;Failed to load file
 178                                                 ;On entry:
 179                                                 ;  R0 == pointer to error
 180                                                 ;  R1 == 1
 181                                                 ;On exit:
 182                                                 ;  --
 183
 184                 ]
 185
 186 ;----- That's all, folks ----------------------------------------------------
 187
 188                 END