mdw@git.distorted.org.uk Git - ssr/blob - StraySrc/Libraries/Sapphire/sh/chunk

   1 ;
   2 ; chunk.sh
   3 ;
   4 ; Loading and management of options chunks
   5 ;
   6 ; © 1995-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 ;  chunk_create
  32 ;  chunk_destroy
  33 ;  chunk_claim
  34 ;  chunk_makeBinary
  35 ;  chunk_read
  36 ;  chunk_enum
  37 ;  chunk_save
  38
  39                 [       :LNOT::DEF:chunk__dfn
  40                 GBLL    chunk__dfn
  41
  42 ; --- chunk_create ---
  43 ;
  44 ; On entry:     --
  45 ;
  46 ; On exit:      R0 == chunk file handle
  47 ;               May return an error
  48 ;
  49 ; Use:          Creates a new chunk file structure and returns a handle to
  50 ;               it.
  51
  52                 IMPORT  chunk_create
  53
  54 ; --- chunk_destroy ---
  55 ;
  56 ; On entry:     R0 == chunk file handle
  57 ;
  58 ; On exit:      --
  59 ;
  60 ; Use:          Removes a chunk file structure from memory.  Chunk data in
  61 ;               flex blocks is freed; chunk claimers who free flex blocks
  62 ;               should clear the anchors to 0.
  63
  64                 IMPORT  chunk_destroy
  65
  66 ; --- chunk_claim ---
  67 ;
  68 ; On entry:     R0 == chunk file handle
  69 ;               R1 == pointer to chunk name
  70 ;               R2 == pointer to saver routine, or 0 for none, or -1 for no
  71 ;                       change
  72 ;               R3 == R10 value to pass to saver
  73 ;               R4 == R12 value to pass to saver
  74 ;
  75 ; On exit:      R1 == chunk handle/anchor
  76 ;               CS if the chunk already existed
  77 ;               May return an error
  78 ;
  79 ; Use:          Claims a chunk, installing a save handler for it.  The chunk
  80 ;               handle returned is actually the address of a flex anchor for
  81 ;               the chunk's data (use flex_size to find the block's size).
  82 ;               If the save handle is 0, the data in the flex block (which
  83 ;               may be modified) is saved directly from the block.  Otherwise
  84 ;               the save routine is expected to save its data, using xsave.
  85 ;
  86 ;               The anchor is followed by 3 unused words -- you can use them
  87 ;               for whatever you want.
  88 ;
  89 ;               Warning: this routine may move flex blocks.
  90
  91                 IMPORT  chunk_claim
  92
  93 ; --- chunk_makeBinary ---
  94 ;
  95 ; On entry:     R0 == chunk file handle
  96 ;               R1 == chunk handle
  97 ;
  98 ; On exit:      --
  99 ;
 100 ; Use:          Marks a given chunk as containing binary data.
 101
 102                 IMPORT  chunk_makeBinary
 103
 104 ; --- chunk_read ---
 105 ;
 106 ; On entry:     R0 == chunk file handle
 107 ;               R1 == address of a flex anchor
 108 ;
 109 ; On exit:      May return an error
 110 ;
 111 ; Use:          Merges the data contained in the flex block with that already
 112 ;               in the chunk file.  If the chunk file is empty, this is
 113 ;               equivalent to a load.  Data from the flex block is appended
 114 ;               to chunks already loaded where appropriate.
 115 ;
 116 ;               Warning: this routine may move flex blocks.
 117
 118                 IMPORT  chunk_read
 119
 120 ; --- chunk_enum ---
 121 ;
 122 ; On entry:     R0 == chunk file handle
 123 ;               R1 == 0 for first call or continuation value
 124 ;
 125 ; On exit:      CC if this isn't over yet, and
 126 ;                 R1 == continuation value for next call
 127 ;                 R2 == pointer to chunk name
 128 ;               else CS and
 129 ;                 R1 == 0
 130 ;                 R2 preserved
 131 ;
 132 ; Use:          Allows you to enumerate the chunks in a chunk file structure.
 133
 134                 IMPORT  chunk_enum
 135
 136 ; --- chunk_save ---
 137 ;
 138 ; On entry:     R0 == chunk file handle
 139 ;
 140 ; On exit:      May return an error
 141 ;
 142 ; Use:          Saves a chunk file to xsave's current output.
 143
 144                 IMPORT  chunk_save
 145
 146                 ]
 147
 148 ;----- That's all, folks ----------------------------------------------------
 149
 150                 END