+++ /dev/null
-/*\r
- LUFA Library\r
- Copyright (C) Dean Camera, 2009.\r
- \r
- dean [at] fourwalledcubicle [dot] com\r
- www.fourwalledcubicle.com\r
-*/\r
-\r
-/*\r
- Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com)\r
-\r
- Permission to use, copy, modify, and distribute this software\r
- and its documentation for any purpose and without fee is hereby\r
- granted, provided that the above copyright notice appear in all\r
- copies and that both that the copyright notice and this\r
- permission notice and warranty disclaimer appear in supporting\r
- documentation, and that the name of the author not be used in\r
- advertising or publicity pertaining to distribution of the\r
- software without specific, written prior permission.\r
-\r
- The author disclaim all warranties with regard to this\r
- software, including all implied warranties of merchantability\r
- and fitness. In no event shall the author be liable for any\r
- special, indirect or consequential damages or any damages\r
- whatsoever resulting from loss of use, data or profits, whether\r
- in an action of contract, negligence or other tortious action,\r
- arising out of or in connection with the use or performance of\r
- this software.\r
-*/\r
-\r
-/** \file\r
- *\r
- * Dynamic, auto-defragmenting block memory allocator library. This library provides a convenient replacement for\r
- * the standard avr-libc dynamic memory allocation routines. Memory is handed out in block chunks, to reduce the\r
- * management memory overhead.\r
- */\r
-\r
-/** @defgroup Group_MemoryAllocator Dynamic Block Memory Allocator - LUFA/MemoryAllocator/DynAlloc.h\r
- *\r
- * \section Sec_Dependencies Module Source Dependencies\r
- * The following files must be built with any user project that uses this module:\r
- * - LUFA/MemoryAllocator/DynAlloc.c\r
- *\r
- * \section Module Description\r
- * Dynamic, auto-defragmenting block memory allocator library. This library provides a convenient replacement for\r
- * the standard avr-libc dynamic memory allocation routines. Memory is handed out in block chunks, to reduce the\r
- * management memory overhead.\r
- *\r
- * Unlike the normal memory allocation routines, this library gives out handles to memory which must be dereferenced\r
- * at the exact time of use, rather than handing back direct memory pointers. By using library managed handles\r
- * instead of pointers, allocated memory blocks can be shifted around as needed transparently to defragment the\r
- * memory as more blocks are requested.\r
- *\r
- * The memory heap is static, thus the total memory usage of the compiled application (as reported by the avr-size\r
- * tool of the AVR-GCC toolchain) includes the dynamic memory heap.\r
- *\r
- * The constants NUM_BLOCKS, BLOCK_SIZE and NUM_HANDLES must be defined in the project makefile (and passed to the\r
- * preprocessor via the -D GCC switch) for this library to compile.\r
- *\r
- * NUM_BLOCKS indicates the number of memory blocks in the memory psudoheap which can be chained together and handed\r
- * to the application via a memory handle. NUM_HANDLES is the maximum number of memory handles (pointing to one or\r
- * more chained memory blocks) which can be handed out simultaneously before requiring a handle (and its associated\r
- * memory) to be freed. BLOCK_SIZE gives the number of bytes in each memory block. \r
- *\r
- * @{\r
- */\r
-\r
-#ifndef __DYN_ALLOC__\r
-#define __DYN_ALLOC__\r
-\r
- /* Includes : */\r
- #include <avr/io.h>\r
- #include <stdbool.h>\r
- #include <string.h>\r
- \r
- /* Preprocessor Checks: */\r
- #if (!defined(NUM_BLOCKS) || !defined(BLOCK_SIZE) || !defined(NUM_HANDLES))\r
- #error NUM_BLOCKS, BLOCK_SIZE and NUM_HANDLES must be defined before use via makefile.\r
- #endif\r
-\r
- /* Public Interface - May be used in end-application: */\r
- /* Macros: */\r
- /** Macro to dereference a given memory handle into the given type. The given type should be a pointer\r
- * if the memory is to contain an array of items, or should be a standard type (such as a primitive or\r
- * structure) if the memory is to hold a single item of a single type. */\r
- #define DEREF(handle, type) (*(type*)handle)\r
- \r
- /** Constant, giving the total heap size in bytes. */\r
- #define ALLOCABLE_BYTES (1UL * NUM_BLOCKS * BLOCK_SIZE)\r
- \r
- /* Type Defines: */\r
- /** Memory handle type, used to store handles given by the library functions. */\r
- typedef const void** Mem_Handle_t;\r
- \r
- #if (ALLOCABLE_BYTES > 0xFFFF) || defined(__DOXYGEN__)\r
- /** Type define for the size (in bytes) for an allocation for passing to the library functions.\r
- * The exact type width varies depending on the value of ALLOCABLE_BYTES to ensure that a single\r
- * allocation can request the entire heap if needed.\r
- */\r
- typedef uint32_t Alloc_Size_t;\r
- #elif (ALLOCABLE_BYTES > 0xFF)\r
- typedef uint16_t Alloc_Size_t;\r
- #else \r
- typedef uint8_t Alloc_Size_t;\r
- #endif\r
-\r
- #if (NUM_BLOCKS > 0xFFFF) || defined(__DOXYGEN__)\r
- /** Type define for a block number in the heap. The exact type width varies depending on the\r
- * value of NUM_BLOCKS to ensure that the type can store an index to any block in the block pool.\r
- */\r
- typedef uint32_t Block_Number_t;\r
- #elif (NUM_BLOCKS > 0xFF)\r
- typedef uint16_t Block_Number_t;\r
- #else\r
- typedef uint8_t Block_Number_t;\r
- #endif\r
-\r
- #if (NUM_HANDLES > 0xFFFF) || defined(__DOXYGEN__)\r
- /** Type define for a handle number. The exact type width varies depending on the value of NUM_HANDLES\r
- * to ensure that the type can store the index of any handle in the handle pool.\r
- */\r
- typedef uint32_t Handle_Number_t;\r
- #elif (NUM_HANDLES > 0xFF)\r
- typedef uint16_t Handle_Number_t;\r
- #else \r
- typedef uint8_t Handle_Number_t;\r
- #endif\r
- \r
- /* Function Prototypes: */\r
- /** Allocates a given number of blocks from the heap (calculated from the requested number of bytes) and\r
- * returns a handle to the newly allocated memory.\r
- *\r
- * \param Bytes The number of bytes requested to be allocated from the heap\r
- *\r
- * \return NULL handle if the allocation fails, or handle to the allocated memory if the allocation succeeds\r
- */\r
- Mem_Handle_t Mem_Alloc(const Alloc_Size_t Bytes);\r
- \r
- /** Allocates a given number of blocks from the heap (calculated from the requested number of bytes) and\r
- * returns a handle to the newly allocated memory. Calloced memory is automatically cleared to all 0x00\r
- * values at the time of allocation.\r
- *\r
- * \param Bytes The number of pre-cleared bytes requested to be allocated from the heap\r
- *\r
- * \return NULL handle if the allocation fails, or handle to the allocated memory if the allocation succeeds\r
- */\r
- Mem_Handle_t Mem_Calloc(const Alloc_Size_t Bytes);\r
-\r
- /** Deallocates a given memory handle, and attempts to allocates the given number of blocks from the heap\r
- * (calculated from the requested number of bytes) immediately following the deallocation. The new memory\r
- * may be located in the same area as the previous memory, but this is not guaranteed.\r
- *\r
- * \param CurrAllocHdl Handle to an already allocated section of memory in the heap to deallocate\r
- * \param Bytes The number of bytes requested to be allocated from the heap following the\r
- * deallocation\r
- *\r
- * \return NULL handle if the allocation fails, or handle to the allocated memory if the allocation succeeds\r
- *\r
- * \warning Even if the allocation fails, the deallocation will still occur. Care should be taken to ensure\r
- * that the previously allocated memory is not used following an unsuccessful realloc().\r
- */\r
- Mem_Handle_t Mem_Realloc(Mem_Handle_t CurrAllocHdl, const Alloc_Size_t Bytes);\r
- \r
- /** Deallocates a given previously allocated section of memory from the heap.\r
- *\r
- * \param CurrAllocHdl Handle to a previously allocated section of memory in the heap\r
- */\r
- void Mem_Free(Mem_Handle_t CurrAllocHdl);\r
- \r
- /** Returns the total number of unallocated blocks in the heap.\r
- *\r
- * \return Number of free blocks in the heap, as a Block_Number_t integer\r
- */\r
- Block_Number_t Mem_TotalFreeBlocks(void);\r
-\r
- /** Returns the total number of unallocated handles in the handle pool.\r
- *\r
- * \return Number of free handles in the handle pool, as a Handle_Number_t integer\r
- */\r
- Handle_Number_t Mem_TotalFreeHandles(void);\r
- \r
- /* Private Interface - For use in library only: */\r
- #if !defined(__DOXYGEN__)\r
- /* Macros: */\r
- #define BLOCK_USED_MASK (1 << 0)\r
- #define BLOCK_LINKED_MASK (1 << 1)\r
- \r
- /* Function Prototypes: */\r
- #if defined(INCLUDE_FROM_DYNALLOC_C)\r
- static uint8_t Mem_GetBlockFlags(const Block_Number_t BlockNum);\r
- static void Mem_SetBlockFlags(const Block_Number_t BlockNum, const uint8_t Flags);\r
- static void Mem_Defrag(void);\r
- #endif\r
- #endif\r
- \r
-#endif\r
-\r
-/** @} */\r
projects / pub / lufa.git / blobdiff