forked from Imagelibrary/rtems
cf3d2b37c8
The interfaces in the MallocSupport group belong to the implementation. They are used by confdefs.h for example.
281 lines
8.1 KiB
C
281 lines
8.1 KiB
C
/* SPDX-License-Identifier: BSD-2-Clause */
|
|
|
|
/**
|
|
* @file
|
|
*
|
|
* @ingroup MallocSupport
|
|
*
|
|
* @ingroup RTEMSAPIMalloc
|
|
*
|
|
* @brief This header file defines interfaces to support and use dynamic memory
|
|
* allocation.
|
|
*/
|
|
|
|
/*
|
|
* COPYRIGHT (c) 1989-2011.
|
|
* On-Line Applications Research Corporation (OAR).
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions
|
|
* are met:
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
|
|
#ifndef _RTEMS_MALLOC_H
|
|
#define _RTEMS_MALLOC_H
|
|
|
|
#include <rtems.h>
|
|
#include <rtems/bspIo.h>
|
|
#include <rtems/libcsupport.h> /* for malloc_walk() */
|
|
|
|
#include <stdint.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @defgroup MallocSupport Malloc Support
|
|
*
|
|
* @ingroup libcsupport
|
|
*
|
|
* @brief This group contains interfaces to support dynamic memory allocation.
|
|
*
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @brief C program heap control.
|
|
*
|
|
* This is the pointer to the heap control structure used to manage the C
|
|
* program heap.
|
|
*/
|
|
extern Heap_Control *RTEMS_Malloc_Heap;
|
|
|
|
void _Malloc_Initialize( void );
|
|
|
|
typedef void *(*rtems_heap_extend_handler)(
|
|
Heap_Control *heap,
|
|
size_t alloc_size
|
|
);
|
|
|
|
/**
|
|
* @brief RTEMS Extend Heap via Sbrk
|
|
*/
|
|
void *rtems_heap_extend_via_sbrk(
|
|
Heap_Control *heap,
|
|
size_t alloc_size
|
|
);
|
|
|
|
void *rtems_heap_null_extend(
|
|
Heap_Control *heap,
|
|
size_t alloc_size
|
|
);
|
|
|
|
extern const rtems_heap_extend_handler rtems_malloc_extend_handler;
|
|
|
|
/*
|
|
* Malloc Plugin to Dirty Memory at Allocation Time
|
|
*/
|
|
typedef void (*rtems_malloc_dirtier_t)(void *, size_t);
|
|
extern rtems_malloc_dirtier_t rtems_malloc_dirty_helper;
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup RTEMSAPIMalloc Dynamic Memory Allocation
|
|
*
|
|
* @ingroup RTEMSAPI
|
|
*
|
|
* @brief This group contains non-standard interfaces to use dynamic memory
|
|
* allocation.
|
|
*
|
|
* @{
|
|
*/
|
|
|
|
void rtems_heap_set_sbrk_amount( ptrdiff_t sbrk_amount );
|
|
|
|
/**
|
|
* @brief Greedy allocate that empties the sbrk memory
|
|
*
|
|
* Afterwards all the sbrk avialable memory will have been allocated
|
|
* to the provided heap.
|
|
*
|
|
* @see rtems_heap_extend_via_sbrk().
|
|
*/
|
|
void rtems_heap_sbrk_greedy_allocate(
|
|
Heap_Control *heap,
|
|
size_t alloc_size
|
|
);
|
|
|
|
/**
|
|
* @brief Dirty Memory Function
|
|
*
|
|
* This method fills the specified area with a non-zero pattern
|
|
* to aid in debugging programs which do not initialize their
|
|
* memory allocated from the heap.
|
|
*/
|
|
void rtems_malloc_dirty_memory(
|
|
void *start,
|
|
size_t size
|
|
);
|
|
|
|
/**
|
|
* @brief RTEMS Variation on Aligned Memory Allocation
|
|
*
|
|
* This method is a help memalign implementation which does all
|
|
* error checking done by posix_memalign() EXCEPT it does NOT
|
|
* place numeric restrictions on the alignment value.
|
|
*
|
|
* @param[in] pointer points to the user pointer
|
|
* @param[in] alignment is the desired alignment
|
|
* @param[in] size is the allocation request size in bytes
|
|
*
|
|
* @return This methods returns zero on success and a POSIX errno
|
|
* value to indicate the failure condition. On success
|
|
* *pointer will contain the address of the allocated memory.
|
|
*/
|
|
int rtems_memalign(
|
|
void **pointer,
|
|
size_t alignment,
|
|
size_t size
|
|
);
|
|
|
|
/**
|
|
* @brief Allocates a memory area of size @a size bytes from the heap.
|
|
*
|
|
* If the alignment parameter @a alignment is not equal to zero, the allocated
|
|
* memory area will begin at an address aligned by this value.
|
|
*
|
|
* If the boundary parameter @a boundary is not equal to zero, the allocated
|
|
* memory area will comply with a boundary constraint. The boundary value
|
|
* specifies the set of addresses which are aligned by the boundary value. The
|
|
* interior of the allocated memory area will not contain an element of this
|
|
* set. The begin or end address of the area may be a member of the set.
|
|
*
|
|
* A size value of zero will return a unique address which may be freed with
|
|
* free().
|
|
*
|
|
* The memory allocated by this function can be released with a call to free().
|
|
*
|
|
* @return A pointer to the begin of the allocated memory area, or @c NULL if
|
|
* no memory is available or the parameters are inconsistent.
|
|
*/
|
|
void *rtems_heap_allocate_aligned_with_boundary(
|
|
size_t size,
|
|
uintptr_t alignment,
|
|
uintptr_t boundary
|
|
) RTEMS_MALLOCLIKE RTEMS_ALLOC_SIZE(1) RTEMS_ALLOC_ALIGN(2)
|
|
RTEMS_WARN_UNUSED_RESULT;
|
|
|
|
/**
|
|
* @brief Allocates a memory area of the specified size from the heap.
|
|
*
|
|
* This function is almost identical to malloc(). The only exception is that
|
|
* errno is not set in case of a memory allocation failure.
|
|
*
|
|
* @param[in] size The memory area size in bytes.
|
|
*
|
|
* @retval NULL The memory allocation failed or @a size is zero.
|
|
* @retval otherwise The begin address of the allocated memory area.
|
|
*/
|
|
void *rtems_malloc(size_t size)
|
|
RTEMS_MALLOCLIKE RTEMS_ALLOC_SIZE(1) RTEMS_WARN_UNUSED_RESULT;
|
|
|
|
/**
|
|
* @brief Allocates a memory area for the specified count of elements from the
|
|
* heap.
|
|
*
|
|
* The allocated memory area is fully filled with zero bits.
|
|
*
|
|
* This function is almost identical to calloc(). The only exception is that
|
|
* errno is not set in case of a memory allocation failure.
|
|
*
|
|
* @param[in] nelem The count of elements.
|
|
* @param[in] elsize The size of each elements.
|
|
*
|
|
* @retval NULL The memory allocation failed or @a nelem is zero or @a elsize
|
|
* is zero.
|
|
* @retval otherwise The begin address of the allocated memory area.
|
|
*/
|
|
void *rtems_calloc(size_t nelem, size_t elsize)
|
|
RTEMS_MALLOCLIKE RTEMS_ALLOC_SIZE_2(1, 2) RTEMS_WARN_UNUSED_RESULT;
|
|
|
|
/**
|
|
* @brief Extends the memory available for the heap using the memory area
|
|
* starting at @a area_begin of size @a area_size bytes.
|
|
*
|
|
* There are no alignment requirements. The memory area must be big enough to
|
|
* contain some maintenance blocks. It must not overlap parts of the current
|
|
* heap areas. Disconnected subordinate heap areas will lead to used blocks
|
|
* which cover the gaps. Extending with an inappropriate memory area will
|
|
* corrupt the heap.
|
|
*
|
|
* @retval RTEMS_SUCCESSFUL Successful operation.
|
|
* @retval RTEMS_INVALID_ADDRESS Invalid memory area.
|
|
*/
|
|
rtems_status_code rtems_heap_extend(
|
|
void *area_begin,
|
|
uintptr_t area_size
|
|
);
|
|
|
|
/**
|
|
* @brief Greedy allocate that empties the heap.
|
|
*
|
|
* Afterwards the heap has at most @a block_count allocatable blocks of sizes
|
|
* specified by @a block_sizes. The @a block_sizes must point to an array with
|
|
* @a block_count members. All other blocks are used.
|
|
*
|
|
* @see rtems_heap_greedy_free().
|
|
*/
|
|
void *rtems_heap_greedy_allocate(
|
|
const uintptr_t *block_sizes,
|
|
size_t block_count
|
|
);
|
|
|
|
/**
|
|
* @brief Greedy allocate all blocks except the largest free block.
|
|
*
|
|
* Afterwards the heap has at most one allocatable block. This block is the
|
|
* largest free block if it exists. The allocatable size of this block is
|
|
* stored in @a allocatable_size. All other blocks are used.
|
|
*
|
|
* @see rtems_heap_greedy_free().
|
|
*/
|
|
void *rtems_heap_greedy_allocate_all_except_largest(
|
|
uintptr_t *allocatable_size
|
|
);
|
|
|
|
/**
|
|
* @brief Frees space of a greedy allocation.
|
|
*
|
|
* The @a opaque argument must be the return value of
|
|
* rtems_heap_greedy_allocate() or
|
|
* rtems_heap_greedy_allocate_all_except_largest().
|
|
*/
|
|
void rtems_heap_greedy_free( void *opaque );
|
|
|
|
/** @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|