drivers/staging/memrar/memrar_allocator.h

   1 /*
   2  *      Copyright (C) 2010 Intel Corporation. All rights reserved.
   3  *
   4  *      This program is free software; you can redistribute it and/or
   5  *      modify it under the terms of version 2 of the GNU General
   6  *      Public License as published by the Free Software Foundation.
   7  *
   8  *      This program is distributed in the hope that it will be
   9  *      useful, but WITHOUT ANY WARRANTY; without even the implied
  10  *      warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  11  *      PURPOSE.  See the GNU General Public License for more details.
  12  *      You should have received a copy of the GNU General Public
  13  *      License along with this program; if not, write to the Free
  14  *      Software Foundation, Inc., 59 Temple Place - Suite 330,
  15  *      Boston, MA  02111-1307, USA.
  16  *      The full GNU General Public License is included in this
  17  *      distribution in the file called COPYING.
  18  */
  19
  20 #ifndef MEMRAR_ALLOCATOR_H
  21 #define MEMRAR_ALLOCATOR_H
  22
  23
  24 #include <linux/mutex.h>
  25 #include <linux/list.h>
  26 #include <linux/types.h>
  27 #include <linux/kernel.h>
  28
  29
  30 /**
  31  * struct memrar_address_range - struct that describes a memory range
  32  * @begin:      Beginning of available address range.
  33  * @end:        End of available address range, one past the end,
  34  *              i.e. [begin, end).
  35  */
  36 struct memrar_address_range {
  37 /* private: internal use only */
  38         unsigned long begin;
  39         unsigned long end;
  40 };
  41
  42 /**
  43  * struct memrar_address_ranges - list of areas of memory.
  44  * @list:       Linked list of address ranges.
  45  * @range:      Memory address range corresponding to given list node.
  46  */
  47 struct memrar_address_ranges {
  48 /* private: internal use only */
  49         struct list_head list;
  50         struct memrar_address_range range;
  51 };
  52
  53 /**
  54  * struct memrar_allocator - encapsulation of the memory allocator state
  55  * @lock:               Lock used to synchronize access to the memory
  56  *                      allocator state.
  57  * @base:               Base (start) address of the allocator memory
  58  *                      space.
  59  * @capacity:           Size of the allocator memory space in bytes.
  60  * @block_size:         The size in bytes of individual blocks within
  61  *                      the allocator memory space.
  62  * @largest_free_area:  Largest free area of memory in the allocator
  63  *                      in bytes.
  64  * @allocated_list:     List of allocated memory block address
  65  *                      ranges.
  66  * @free_list:          List of free address ranges.
  67  *
  68  * This structure contains all memory allocator state, including the
  69  * base address, capacity, free list, lock, etc.
  70  */
  71 struct memrar_allocator {
  72 /* private: internal use only */
  73         struct mutex lock;
  74         unsigned long base;
  75         size_t capacity;
  76         size_t block_size;
  77         size_t largest_free_area;
  78         struct memrar_address_ranges allocated_list;
  79         struct memrar_address_ranges free_list;
  80 };
  81
  82 /**
  83  * memrar_create_allocator() - create a memory allocator
  84  * @base:       Address at which the memory allocator begins.
  85  * @capacity:   Desired size of the memory allocator.  This value must
  86  *              be larger than the block_size, ideally more than twice
  87  *              as large since there wouldn't be much point in using a
  88  *              memory allocator otherwise.
  89  * @block_size: The size of individual blocks within the memory
  90  *              allocator.  This value must smaller than the
  91  *              capacity.
  92  *
  93  * Create a memory allocator with the given capacity and block size.
  94  * The capacity will be reduced to be a multiple of the block size, if
  95  * necessary.
  96  *
  97  * Returns an instance of the memory allocator, if creation succeeds,
  98  * otherwise zero if creation fails.  Failure may occur if not enough
  99  * kernel memory exists to create the memrar_allocator instance
 100  * itself, or if the capacity and block_size arguments are not
 101  * compatible or make sense.
 102  */
 103 struct memrar_allocator *memrar_create_allocator(unsigned long base,
 104                                                  size_t capacity,
 105                                                  size_t block_size);
 106
 107 /**
 108  * memrar_destroy_allocator() - destroy allocator
 109  * @allocator:  The allocator being destroyed.
 110  *
 111  * Reclaim resources held by the memory allocator.  The caller must
 112  * explicitly free all memory reserved by memrar_allocator_alloc()
 113  * prior to calling this function.  Otherwise leaks will occur.
 114  */
 115 void memrar_destroy_allocator(struct memrar_allocator *allocator);
 116
 117 /**
 118  * memrar_allocator_alloc() - reserve an area of memory of given size
 119  * @allocator:  The allocator instance being used to reserve buffer.
 120  * @size:       The size in bytes of the buffer to allocate.
 121  *
 122  * This functions reserves an area of memory managed by the given
 123  * allocator.  It returns zero if allocation was not possible.
 124  * Failure may occur if the allocator no longer has space available.
 125  */
 126 unsigned long memrar_allocator_alloc(struct memrar_allocator *allocator,
 127                                      size_t size);
 128
 129 /**
 130  * memrar_allocator_free() - release buffer starting at given address
 131  * @allocator:  The allocator instance being used to release the buffer.
 132  * @address:    The address of the buffer being released.
 133  *
 134  * Release an area of memory starting at the given address.  Failure
 135  * could occur if the given address is not in the address space
 136  * managed by the allocator.  Returns zero on success or an errno
 137  * (negative value) on failure.
 138  */
 139 long memrar_allocator_free(struct memrar_allocator *allocator,
 140                            unsigned long address);
 141
 142 #endif  /* MEMRAR_ALLOCATOR_H */
 143
 144
 145 /*
 146   Local Variables:
 147     c-file-style: "linux"
 148   End:
 149 */