/*
* Copyright (C) 2010 Intel Corporation. All rights reserved.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of version 2 of the GNU General
* Public License as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be
* useful, but WITHOUT ANY WARRANTY; without even the implied
* warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE. See the GNU General Public License for more details.
* You should have received a copy of the GNU General Public
* License along with this program; if not, write to the Free
* Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
* The full GNU General Public License is included in this
* distribution in the file called COPYING.
*/
#ifndef MEMRAR_ALLOCATOR_H
#define MEMRAR_ALLOCATOR_H
#include <linux/mutex.h>
#include <linux/list.h>
#include <linux/types.h>
#include <linux/kernel.h>
/**
* struct memrar_address_range - struct that describes a memory range
* @begin: Beginning of available address range.
* @end: End of available address range, one past the end,
* i.e. [begin, end).
*/
struct memrar_address_range {
/* private: internal use only */
unsigned long begin;
unsigned long end;
};
/**
* struct memrar_address_ranges - list of areas of memory.
* @list: Linked list of address ranges.
* @range: Memory address range corresponding to given list node.
*/
struct memrar_address_ranges {
/* private: internal use only */
struct list_head list;
struct memrar_address_range range;
};
/**
* struct memrar_allocator - encapsulation of the memory allocator state
* @lock: Lock used to synchronize access to the memory
* allocator state.
* @base: Base (start) address of the allocator memory
* space.
* @capacity: Size of the allocator memory space in bytes.
* @block_size: The size in bytes of individual blocks within
* the allocator memory space.
* @largest_free_area: Largest free area of memory in the allocator
* in bytes.
* @allocated_list: List of allocated memory block address
* ranges.
* @free_list: List of free address ranges.
*
* This structure contains all memory allocator state, including the
* base address, capacity, free list, lock, etc.
*/
struct memrar_allocator {
/* private: internal use only */
struct mutex lock;
unsigned long base;
size_t capacity;
size_t block_size;
size_t largest_free_area;
struct memrar_address_ranges allocated_list;
struct memrar_address_ranges free_list;
};
/**
* memrar_create_allocator() - create a memory allocator
* @base: Address at which the memory allocator begins.
* @capacity: Desired size of the memory allocator. This value must
* be larger than the block_size, ideally more than twice
* as large since there wouldn't be much point in using a
* memory allocator otherwise.
* @block_size: The size of individual blocks within the memory
* allocator. This value must smaller than the
* capacity.
*
* Create a memory allocator with the given capacity and block size.
* The capacity will be reduced to be a multiple of the block size, if
* necessary.
*
* Returns an instance of the memory allocator, if creation succeeds,
* otherwise zero if creation fails. Failure may occur if not enough
* kernel memory exists to create the memrar_allocator instance
* itself, or if the capacity and block_size arguments are not
* compatible or make sense.
*/
struct memrar_allocator *memrar_create_allocator(unsigned long base,
size_t capacity,
size_t block_size);
/**
* memrar_destroy_allocator() - destroy allocator
* @allocator: The allocator being destroyed.
*
* Reclaim resources held by the memory allocator. The caller must
* explicitly free all memory reserved by memrar_allocator_alloc()
* prior to calling this function. Otherwise leaks will occur.
*/
void memrar_destroy_allocator(struct memrar_allocator *allocator);
/**
* memrar_allocator_alloc() - reserve an area of memory of given size
* @allocator: The allocator instance being used to reserve buffer.
* @size: The size in bytes of the buffer to allocate.
*
* This functions reserves an area of memory managed by the given
* allocator. It returns zero if allocation was not possible.
* Failure may occur if the allocator no longer has space available.
*/
unsigned long memrar_allocator_alloc(struct memrar_allocator *allocator,
size_t size);
/**
* memrar_allocator_free() - release buffer starting at given address
* @allocator: The allocator instance being used to release the buffer.
* @address: The address of the buffer being released.
*
* Release an area of memory starting at the given address. Failure
* could occur if the given address is not in the address space
* managed by the allocator. Returns zero on success or an errno
* (negative value) on failure.
*/
long memrar_allocator_free(struct memrar_allocator *allocator,
unsigned long address);
#endif /* MEMRAR_ALLOCATOR_H */
/*
Local Variables:
c-file-style: "linux"
End:
*/
