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

   1 ;
   2 ; xfer.xload.sh
   3 ;
   4 ; Simplified loading with coroutines
   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 ;  xload_file
  32 ;  xload_initBuf
  33 ;  xload_killBuf
  34 ;  xload_extend
  35 ;  xload_doneBuf
  36 ;  xload_done
  37 ;  xload_failed
  38 ;  xload_byte
  39 ;  xload_word
  40 ;  xload_block
  41
  42                 [       :LNOT::DEF:xload__dfn
  43                 GBLL    xload__dfn
  44
  45 ; --- xload_file ---
  46 ;
  47 ; On entry:     R0 == pointer to loader routine
  48 ;               R1 == R10 value to pass to loader
  49 ;               R2 == R12 value to pass to loader
  50 ;               R3 == pointer to leafname of file (passed to loader in R0)
  51 ;               R4 == pointer to filename to load from
  52 ;               R5 == whether the file is safe (passed to loader in R1)
  53 ;
  54 ; On exit:      May return an error
  55 ;
  56 ; Use:          Calls a generalised loader routine to read data from a file.
  57
  58                 IMPORT  xload_file
  59
  60 ; --- xload_initBuf ---
  61 ;
  62 ; On entry:     R0 == pointer to loader routine
  63 ;               R1 == R10 value to pass to loader
  64 ;               R2 == R12 value to pass to loader
  65 ;               R3 == pointer to leafname of file (passed to loader in R0)
  66 ;
  67 ; On exit:      R0 == pointer to load buffer
  68 ;               R1 == size of load buffer
  69 ;               May return an error
  70 ;
  71 ; Use:          Starts a RAM transfer and starts up a generalised load
  72 ;               routine.
  73
  74                 IMPORT  xload_initBuf
  75
  76 ; --- xload_killBuf ---
  77 ;
  78 ; On entry:     --
  79 ;
  80 ; On exit:      --
  81 ;
  82 ; Use:          Does a buffer destroy for a failed load operation.
  83
  84                 IMPORT  xload_killBuf
  85
  86 ; --- xload_extend ---
  87 ;
  88 ; On entry:     R1 == size of last buffer used for receiving
  89 ;
  90 ; On exit:      R0 == pointer to new buffer
  91 ;               R1 == size of new buffer
  92 ;               May return an error
  93 ;
  94 ; Use:          Performs a buffer extent operation during an xload RAM
  95 ;               transfer.
  96
  97                 IMPORT  xload_extend
  98
  99 ; --- xload_doneBuf ---
 100 ;
 101 ; On entry:     R1 == total size of data received
 102 ;
 103 ; On exit:      R0 corrupted
 104 ;               May return an error
 105 ;
 106 ; Use:          Handles the last bufferful of a RAM load.
 107
 108                 IMPORT  xload_doneBuf
 109
 110 ; --- xload_done ---
 111 ;
 112 ; On entry:     --
 113 ;
 114 ; On exit:      --
 115 ;
 116 ; Use:          Tidies up after a successful load job.
 117
 118                 IMPORT  xload_done
 119
 120 ; --- xload_failed ---
 121 ;
 122 ; On entry:     R0 == pointer to error block
 123 ;
 124 ; On exit:      --
 125 ;
 126 ; Use:          Tidies up a RAM transfer after an error.
 127
 128                 IMPORT  xload_failed
 129
 130 ; --- xload_byte ---
 131 ;
 132 ; On entry:     --
 133 ;
 134 ; On exit:      CC if data read OK, and
 135 ;                 R0 == byte read
 136 ;               else CC if end-of-file, and
 137 ;                 R0 corrupted
 138 ;               May return an error
 139 ;
 140 ; Use:          Reads a byte from the current input.
 141
 142                 IMPORT  xload_byte
 143
 144 ; --- xload_word ---
 145 ;
 146 ; On entry:     --
 147 ;
 148 ; On exit:      CC if data read OK, and
 149 ;                 R0 == word read
 150 ;               else CS if end-of-file and
 151 ;                 R0 corrupted
 152 ;               May return an error
 153 ;
 154 ; Use:          Reads a word from the current input.
 155
 156                 IMPORT  xload_word
 157
 158 ; --- xload_block ---
 159 ;
 160 ; On entry:     R0 == pointer to buffer to read
 161 ;               R1 == size of buffer to read
 162 ;
 163 ; On exit:      R0, R1 preserved
 164 ;               R2 == number of bytes read
 165 ;               CC if more data available, CS for end-of-file
 166 ;               May return an error
 167 ;
 168 ; Use:          Reads in a block of data.  Data is buffered, so this is
 169 ;               fairly quick for reading small objects.  Large data blocks
 170 ;               are read directly to avoid buffering overhead.
 171
 172                 IMPORT  xload_block
 173
 174                 ]
 175
 176 ;----- That's all, folks ----------------------------------------------------
 177
 178                 END