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

   1 ;
   2 ; alloc.sh
   3 ;
   4 ; Redirectable memory allocation
   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 ;  alloc_register
  32 ;  alloc_useOSHeap
  33 ;  alloc
  34 ;  free
  35 ;  alloc_init
  36 ;  alloc_error
  37
  38                 [       :LNOT::DEF:alloc__dfn
  39                 GBLL    alloc__dfn
  40
  41 ; --- alloc_register ---
  42 ;
  43 ; On entry:     R0 == pointer to allocator function
  44 ;               R1 == pointer to free function
  45 ;               R2 == workspace pointer to pass to them in R12
  46 ;
  47 ; On exit:      --
  48 ;
  49 ; Use:          Registers two functions to be used as a heap manager by
  50 ;               alloc and free.
  51 ;
  52 ;               The allocator is entered with R0 as the size of block
  53 ;               required, and should exit with CC and R0 == pointer to the
  54 ;               block allocated if successful, CS if there wasn't enough
  55 ;               memory and generate any other errors that occur.  Registers
  56 ;               other than R0 must be preserved.
  57 ;
  58 ;               The freer is entered with R0 == pointer to block to free.
  59 ;               It should exit with all registers preserved.  If anything
  60 ;               goes wrong, it should generate an error.
  61
  62                 IMPORT  alloc_register
  63
  64 ; --- alloc_useOSHeap ---
  65 ;
  66 ; On entry:     R1 == pointer to OS_Heap-managed heap to use
  67 ;
  68 ; On exit:      --
  69 ;
  70 ; Use:          Registers an OS_Heap heap to use to allocate memory when
  71 ;               alloc is called.
  72
  73                 IMPORT  alloc_useOSHeap
  74
  75 ; --- alloc ---
  76 ;
  77 ; On entry:     R0 == size of block to allocate from current heap
  78 ;
  79 ; On exit:      R0 == pointer to block and CC if it all worked
  80 ;               CS if there wasn't enough memory (R0 corrupted)
  81 ;
  82 ; Use:          Allocates R0 bytes from a heap manager.  This routine will
  83 ;               attempt to allocate memory from the current heaps in order
  84 ;               of registration (i.e. the Sapphire OS_Heap first etc.) until
  85 ;               either one which can service the request is found, or all
  86 ;               the heaps have been tried.
  87
  88                 IMPORT  alloc
  89
  90 ; --- free ---
  91 ;
  92 ; On entry:     R0 == pointer to block allocated by alloc
  93 ;
  94 ; On exit:      --
  95 ;
  96 ; Use:          Frees a block allocated by alloc, regardless of which heap
  97 ;               it came from.
  98
  99                 IMPORT  free
 100
 101 ; --- alloc_init ---
 102 ;
 103 ; On entry:     --
 104 ;
 105 ; On exit:      --
 106 ;
 107 ; Use:          Initialises the alloc system, and sets it up to use the
 108 ;               kernel-provided OS_Heap area.
 109
 110                 IMPORT  alloc_init
 111
 112 ; --- alloc_error ---
 113 ;
 114 ; On entry:     --
 115 ;
 116 ; On exit:      V set and R0 == pointer to an error about not having enough
 117 ;               memory.
 118 ;
 119 ; Use:          Returns an error suitable for displaying to a user if there
 120 ;               isn't enough memory left.
 121
 122                 IMPORT  alloc_error
 123
 124                 ]
 125
 126 ;----- That's all, folks ----------------------------------------------------
 127
 128                 END