chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/csapph/h/alloc

   1 /*
   2  * alloc.h
   3  *
   4  * [Generated from alloc, 25 September 1996]
   5  */
   6
   7 #if !defined(__CC_NORCROFT) || !defined(__arm)
   8   #error You must use the Norcroft ARM Compiler for Sapphire programs
   9 #endif
  10
  11 #pragma include_only_once
  12 #pragma force_top_level
  13
  14 #ifndef __alloc_h
  15 #define __alloc_h
  16
  17 #ifndef __sapphire_h
  18   #include "sapphire.h"
  19 #endif
  20
  21 /*----- Overview ----------------------------------------------------------*
  22  *
  23  * Functions provided:
  24  *
  25  *  alloc_register
  26  *  alloc_useOSHeap
  27  *  alloc
  28  *  free
  29  *  alloc_init
  30  *  alloc_error
  31  */
  32
  33 /* --- alloc_register --- *
  34  *
  35  * On entry:    R0 == pointer to allocator function
  36  *              R1 == pointer to free function
  37  *              R2 == workspace pointer to pass to them in R12
  38  *
  39  * On exit:     --
  40  *
  41  * Use:         Registers two functions to be used as a heap manager by
  42  *              alloc and free.
  43  *
  44  *              The allocator is entered with R0 as the size of block
  45  *              required, and should exit with CC and R0 == pointer to the
  46  *              block allocated if successful, CS if there wasn't enough
  47  *              memory and generate any other errors that occur.  Registers
  48  *              other than R0 must be preserved.
  49  *
  50  *              The freer is entered with R0 == pointer to block to free.
  51  *              It should exit with all registers preserved.  If anything
  52  *              goes wrong, it should generate an error.
  53  */
  54
  55 extern routine alloc_register;
  56
  57 /* --- alloc_useOSHeap --- *
  58  *
  59  * On entry:    R1 == pointer to OS_Heap-managed heap to use
  60  *
  61  * On exit:     --
  62  *
  63  * Use:         Registers an OS_Heap heap to use to allocate memory when
  64  *              alloc is called.
  65  */
  66
  67 extern routine alloc_useOSHeap;
  68
  69 /* --- alloc --- *
  70  *
  71  * On entry:    R0 == size of block to allocate from current heap
  72  *
  73  * On exit:     R0 == pointer to block and CC if it all worked
  74  *              CS if there wasn't enough memory (R0 corrupted)
  75  *
  76  * Use:         Allocates R0 bytes from a heap manager.  This routine will
  77  *              attempt to allocate memory from the current heaps in order
  78  *              of registration (i.e. the Sapphire OS_Heap first etc.) until
  79  *              either one which can service the request is found, or all
  80  *              the heaps have been tried.
  81  */
  82
  83 extern routine alloc;
  84
  85 /* --- free --- *
  86  *
  87  * On entry:    R0 == pointer to block allocated by alloc
  88  *
  89  * On exit:     --
  90  *
  91  * Use:         Frees a block allocated by alloc, regardless of which heap
  92  *              it came from.
  93  */
  94
  95 extern routine free;
  96
  97 /* --- alloc_init --- *
  98  *
  99  * On entry:    --
 100  *
 101  * On exit:     --
 102  *
 103  * Use:         Initialises the alloc system, and sets it up to use the
 104  *              kernel-provided OS_Heap area.
 105  */
 106
 107 extern routine alloc_init;
 108
 109 /* --- alloc_error --- *
 110  *
 111  * On entry:    --
 112  *
 113  * On exit:     V set and R0 == pointer to an error about not having enough
 114  *              memory.
 115  *
 116  * Use:         Returns an error suitable for displaying to a user if there
 117  *              isn't enough memory left.
 118  */
 119
 120 extern routine alloc_error;
 121
 122 /*----- That's all, folks -------------------------------------------------*/
 123
 124 #endif