lib/tlsf/README

   1
   2 TLSF Memory Storage allocator implementation.
   3 Version 2.4 Feb 2008
   4
   5 Authors: Miguel Masmano, Ismael Ripoll & Alfons Crespo.
   6 Copyright UPVLC, OCERA Consortium.
   7
   8 TLSF is released in the GPL/LGPL licence. The exact terms of the licence
   9 are described in the COPYING file.
  10
  11 This component provides basic memory allocation functions:
  12 malloc and free, as defined in the standard "C" library.
  13
  14 This allocator was designed to provide real-time performance, that is:
  15 1.- Bounded time malloc and free.
  16 2.- Fast response time.
  17 3.- Efficient memory management, that is low fragmentation.
  18
  19
  20 The worst response time for both malloc and free is O(1).
  21
  22
  23
  24 How to use it:
  25
  26 This code  is prepared to  be used as  a stand-alone code that  can be
  27 linked with a regular application or  it can be compiled to be a Linux
  28 module  (which  required the  BigPhysicalArea  patch).  Initially  the
  29 module was  designed to  work jointly with  RTLinux-GPL, but it  can be
  30 used as a stand alone Linux module.
  31
  32 When compiled as a regular linux process the API is:
  33
  34 Initialisation and destruction functions
  35 ----------------------------------------
  36
  37 init_memory_pool may be called before any request or release call:
  38
  39 - size_t init_memory_pool(size_t, void *);
  40 - void destroy_memory_pool(void *);
  41
  42 Request and release functions
  43 -----------------------------
  44
  45 As can be seen, there are two functions for each traditional memory
  46 allocation function (malloc, free, realloc, and calloc). One with the
  47 prefix "tlsf_" and the other with the suffix "_ex".
  48
  49 The versions with the prefix "tlsf_" provides the expected behaviour,
  50 that is, allocating/releasing memory from the default memory pool. The
  51 default memory pool is the last pool initialised by the
  52 init_memory_pool function.
  53
  54 On the other hand, the functions with the prefix "_ex" enable the use of several memory pools.
  55
  56 - void *tlsf_malloc(size_t);
  57 - void *malloc_ex(size_t, void *);
  58
  59 - void tlsf_free(void *ptr);
  60 - void free_ex(void *, void *);
  61
  62 - void *tlsf_realloc(void *ptr, size_t size);
  63 - void *realloc_ex(void *, size_t, void *);
  64
  65 - void *tlsf_calloc(size_t nelem, size_t elem_size);
  66 - void *calloc_ex(size_t, size_t, void *);
  67
  68 EXAMPLE OF USE:
  69
  70 char memory_pool[1024*1024];
  71
  72 {
  73         ...
  74
  75         init_memory_pool(1024*1024, memory_pool);
  76
  77         ...
  78
  79         ptr1=malloc_ex(100, memory_pool);
  80         ptr2=tlsf_malloc(100); // This function will use memory_pool
  81
  82         ...
  83
  84         tlsf_free(ptr2);
  85         free_ex(ptr1, memory_pool);
  86 }
  87
  88 Growing the memory pool
  89 -----------------------
  90
  91 Starting from the version 2.4, the function add_new_area adds an
  92 memory area to an existing memory pool.
  93
  94 - size_t add_new_area(void *, size_t, void *);
  95
  96 This feature is pretty useful when an existing memory pool is running
  97 low and we want to add more free memory to it.
  98 EXAMPLE OF USE:
  99
 100 char memory_pool[1024*1024];
 101 char memory_pool2[1024*1024];
 102
 103 {
 104         ...
 105
 106         init_memory_pool(1024*1024, memory_pool);
 107
 108         ...
 109
 110         ptr[0]=malloc_ex(1024*256 memory_pool);
 111         ptr[1]=malloc_ex(1024*512, memory_pool);
 112         add_new_area(memory_pool2, 1024*1024, memory_pool);
 113         // Now we have an extra free memory area of 1Mb
 114         // The next malloc may not fail
 115         ptr[2]=malloc_ex(1024*512, memory_pool);
 116
 117         ...
 118
 119 }
 120
 121
 122 SBRK and MMAP support
 123 ---------------------
 124
 125 The version 2.4 can use the functions SBRK and MMAP to _automatically_
 126 growing the memory pool, before running out of memory.
 127
 128 So, when this feature is enabled, unless the operating system were out
 129 of memory, a malloc operation would not fail due to an "out-of-memory"
 130 error.
 131
 132 To enable this support, compile tlsf.c with the FLAGS -DUSE_MMAP=1 or
 133 -DUSE_SBRK=1 depending on whether you want to use "mmap" or "sbrk" or both.
 134
 135 ** By default (default Makefile) this feature is enabled.
 136
 137 EXAMPLE OF USE:
 138
 139 gcc -o tlsf.o -O2 -Wall -DUSE_MMAP=1 -DUSE_SBRK=1
 140
 141 ---
 142
 143 If the sbrk/mmap support is enabled and we are _only_ going to use one
 144 memory pool, it is not necessary to call init_memory_pool
 145
 146 EXAMPLE OF USE (with MMAP/SBRK support enabled):
 147
 148 {
 149         ...
 150
 151         ptr2=tlsf_malloc(100); // This function will use memory_pool
 152
 153         ...
 154
 155         tlsf_free(ptr2);
 156 }
 157
 158
 159
 160
 161 This work has been supported by the followin projects:
 162 EUROPEAN: IST-2001-35102(OCERA) http://www.ocera.org.
 163 SPANISH: TIN2005-08665-C3-03