Atmel Software Framework

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Memory Bag Allocator

The Membag allocator is a optimized, fragmentationless general purpose memory allocator utility module designed to replace the standard C library malloc() and free() functions in resource constrained environments.

Internally, the Membag allocator uses several user defined "bags" of one or more fixed-size blocks to form a memory pool for use in a user application. When an allocation is requested, the Membag module will search all available bags and find the smallest unallocated block of sufficient size, and return this block to the calling function. The size of each bag and number of blocks in each bag is user configurable, via the conf_membag.h header file added to the user project.

The allocator also has basic statistics functionality to obtain the size of the entire memory pool, amount of free memory, and the size of the smallest and largest free memory block.

The memory bag allocator always allocates memory as a block from a fixed size bag/pool. This helps reduce memory fragmentation compared to an generic allocator that gives exactly the bytes requested. While this gives a trade-off of the maximum number of concurrent allocations and the size of allocations that are allowable, the allocator prevents memory fragmentation from occuring in an embedded application.

The allocation and deallocation of memory with the Membag module is non-deterministic, however the module functions all have a maximum run time that is dependent on the number of bags that have been configured.

Macros

#define MEMBAG(objsize, nr_objs)   { .block_size = objsize, .num_blocks = nr_objs }
 Macro used to create memory bags in conf_membag.h. More...
 
#define MEMBAG_SIZE(objsize, nr_objs)   (objsize * nr_objs)
 Macro used to store the size of the membags in conf_membag.h. More...
 

Functions

void * membag_alloc (const size_t size)
 Allocate a memory block via a block from the Membag pool. More...
 
void membag_free (const void *ptr)
 Free a previously allocated memory block from the Membag pool. More...
 
size_t membag_get_largest_free_block_size (void)
 Determine the largest available block size. More...
 
size_t membag_get_smallest_free_block_size (void)
 Determine the smallest available block size. More...
 
size_t membag_get_total (void)
 Determine the total memory from all membags. More...
 
size_t membag_get_total_free (void)
 Determine the total remaining free memory from all membags. More...
 
void membag_init (void)
 Initialize the membag system. More...
 

#define MEMBAG (   objsize,
  nr_objs 
)    { .block_size = objsize, .num_blocks = nr_objs }

Macro used to create memory bags in conf_membag.h.

Note
Multiple bags of the same size are allowed, if more than 32 bags of a given size are required in an application.
Parameters
objsizeSize of each block in the bag
nr_objsNumber of blocks in the bag, a value less than 32
#define MEMBAG_SIZE (   objsize,
  nr_objs 
)    (objsize * nr_objs)

Macro used to store the size of the membags in conf_membag.h.

Note
Multiple bags of the same size are allowed, if more than 32 bags of a given size are required in an application.
Parameters
objsizeSize of each block in the bag
nr_objsNumber of blocks in the bag, a value less than 32

void* membag_alloc ( const size_t  size)

Allocate a memory block via a block from the Membag pool.

Allocates memory to the user from one of the available Membag pools. Each Membag pool is examined in sequence, and the first free block of sufficient size (if any) is chosen for the allocation. Allocated blocks persist until either the Membag module is re-initialized, or an allocation block is freed via membag_free().

Note
The execution cycle time for this function is not deterministic; each allocation request may take a variable amount of cycles to complete.
Parameters
sizeSize of memory block requested, in bytes
Returns
Pointer to the start of an allocated block if one was found in the Membag pool, NULL if no suitable block was found.

References membag::allocated, ARRAY_LEN, membag::block_size, block_size, membag::blocks_free, i, NULL, membag::num_blocks, and membag::start.

Referenced by win_create(), wtk_basic_frame_create(), wtk_button_create(), wtk_check_box_create(), wtk_frame_create(), wtk_icon_button_create(), wtk_icon_group_create(), wtk_label_change(), wtk_label_create(), wtk_plot_create(), wtk_progress_bar_create(), wtk_radio_button_create(), wtk_radio_group_create(), wtk_slider_create(), and wtk_start_drag().

void membag_free ( const void *  ptr)

Free a previously allocated memory block from the Membag pool.

This function frees memory which has been allocated previously via a successful call to membag_alloc(). Once deallocated, the given pointer is no longer valid and should not be used in the user application unless re-allocated.

Note
The execution cycle time for this function is not deterministic; each allocation request may take a variable amount of cycles to complete.
Parameters
ptrPointer to an allocated memory block to free

References membag::allocated, ARRAY_LEN, block_size, membag::blocks_free, end, i, start, and membag::start.

Referenced by win_destroy(), win_destroy_children(), wtk_basic_frame_create(), wtk_basic_frame_handler(), wtk_button_create(), wtk_button_handler(), wtk_check_box_create(), wtk_check_box_handler(), wtk_frame_create(), wtk_frame_handler(), wtk_icon_button_create(), wtk_icon_button_handler(), wtk_label_change(), wtk_label_create(), wtk_label_handler(), wtk_plot_create(), wtk_plot_handler(), wtk_progress_bar_create(), wtk_progress_bar_handler(), wtk_radio_button_create(), wtk_radio_button_handler(), wtk_slider_create(), wtk_slider_handler(), wtk_start_drag(), and wtk_stop_drag().

size_t membag_get_largest_free_block_size ( void  )

Determine the largest available block size.

Calculates the largest block which can be allocated by the Membag allocator if requested. Allocations larger than this amount are guaranteed to fail.

Returns
Size of the largest available block, in bytes.

References ARRAY_LEN, membag::block_size, membag::blocks_free, i, and NULL.

size_t membag_get_smallest_free_block_size ( void  )

Determine the smallest available block size.

Calculates the smallest block which can be allocated by the Membag allocator if requested. Allocations larger than this amount are not guaranteed to complete successfully.

Returns
Size of the smallest available block, in bytes.

References ARRAY_LEN, membag::block_size, membag::blocks_free, i, and NULL.

size_t membag_get_total ( void  )

Determine the total memory from all membags.

Returns
Sum of all blocks in all bags, in bytes.

References ARRAY_LEN, membag::block_size, i, membag::num_blocks, and total.

size_t membag_get_total_free ( void  )

Determine the total remaining free memory from all membags.

Returns
Sum of all free memory, in bytes.

References ARRAY_LEN, membag::block_size, membag::blocks_free, and i.

void membag_init ( void  )

Initialize the membag system.

This function sets up the membags, allocates memory from the memory pool, and initializes them. Any existing allocations are destroyed and all memory pools reset to their initial states.

References membag::allocated, ARRAY_LEN, Assert, membag::block_size, block_size, membag::blocks_free, membag::end, i, membag_pool, membag::num_blocks, num_blocks, and membag::start.