source: rtems/cpukit/include/rtems/malloc.h @ 21275b58

5
Last change on this file since 21275b58 was 6efc831, checked in by Sebastian Huber <sebastian.huber@…>, on 11/09/18 at 11:11:11

Add rtems_malloc() and rtems_calloc()

Close #3583.

  • Property mode set to 100644
File size: 6.6 KB
Line 
1/**
2 * @file rtems/malloc.h
3 *
4 * This file defines the interface to RTEMS extensions to the Malloc Family.
5 */
6
7/*
8 *  COPYRIGHT (c) 1989-2011.
9 *  On-Line Applications Research Corporation (OAR).
10 *
11 *  The license and distribution terms for this file may in
12 *  the file LICENSE in this distribution or at
13 *  http://www.rtems.org/license/LICENSE.
14 */
15
16#ifndef _RTEMS_MALLOC_H
17#define _RTEMS_MALLOC_H
18
19#include <rtems.h>
20#include <rtems/bspIo.h>
21#include <rtems/libcsupport.h> /* for malloc_walk() */
22
23#include <stdint.h>
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29/**
30 *  @defgroup MallocSupport Malloc Support
31 *
32 *  @ingroup libcsupport
33 *
34 *  @brief RTEMS extensions to the Malloc Family
35 */
36
37/**
38 *  @brief C program heap control.
39 *
40 *  This is the pointer to the heap control structure used to manage the C
41 *  program heap.
42 */
43extern Heap_Control *RTEMS_Malloc_Heap;
44
45void RTEMS_Malloc_Initialize(
46  const Heap_Area *areas,
47  size_t area_count,
48  Heap_Initialization_or_extend_handler extend
49);
50
51extern ptrdiff_t RTEMS_Malloc_Sbrk_amount;
52
53static inline void rtems_heap_set_sbrk_amount( ptrdiff_t sbrk_amount )
54{
55  RTEMS_Malloc_Sbrk_amount = sbrk_amount;
56}
57
58typedef void *(*rtems_heap_extend_handler)(
59  Heap_Control *heap,
60  size_t alloc_size
61);
62
63/**
64 *  @brief RTEMS Extend Heap via Sbrk
65 */
66void *rtems_heap_extend_via_sbrk(
67  Heap_Control *heap,
68  size_t alloc_size
69);
70
71void *rtems_heap_null_extend(
72  Heap_Control *heap,
73  size_t alloc_size
74);
75
76extern const rtems_heap_extend_handler rtems_malloc_extend_handler;
77
78/*
79 * Malloc Plugin to Dirty Memory at Allocation Time
80 */
81typedef void (*rtems_malloc_dirtier_t)(void *, size_t);
82extern rtems_malloc_dirtier_t rtems_malloc_dirty_helper;
83
84/**
85 *  @brief Dirty Memory Function
86 *
87 *  This method fills the specified area with a non-zero pattern
88 *  to aid in debugging programs which do not initialize their
89 *  memory allocated from the heap.
90 */
91void rtems_malloc_dirty_memory(
92  void   *start,
93  size_t  size
94);
95
96/**
97 *  @brief RTEMS Variation on Aligned Memory Allocation
98 *
99 *  This method is a help memalign implementation which does all
100 *  error checking done by posix_memalign() EXCEPT it does NOT
101 *  place numeric restrictions on the alignment value.
102 *
103 *  @param[in] pointer points to the user pointer
104 *  @param[in] alignment is the desired alignment
105 *  @param[in] size is the allocation request size in bytes
106 *
107 *  @return This methods returns zero on success and a POSIX errno
108 *          value to indicate the failure condition.  On success
109 *          *pointer will contain the address of the allocated memory.
110 */
111int rtems_memalign(
112  void   **pointer,
113  size_t   alignment,
114  size_t   size
115);
116
117/**
118 * @brief Allocates a memory area of size @a size bytes from the heap.
119 *
120 * If the alignment parameter @a alignment is not equal to zero, the allocated
121 * memory area will begin at an address aligned by this value.
122 *
123 * If the boundary parameter @a boundary is not equal to zero, the allocated
124 * memory area will comply with a boundary constraint.  The boundary value
125 * specifies the set of addresses which are aligned by the boundary value.  The
126 * interior of the allocated memory area will not contain an element of this
127 * set.  The begin or end address of the area may be a member of the set.
128 *
129 * A size value of zero will return a unique address which may be freed with
130 * free().
131 *
132 * The memory allocated by this function can be released with a call to free().
133 *
134 * @return A pointer to the begin of the allocated memory area, or @c NULL if
135 * no memory is available or the parameters are inconsistent.
136 */
137void *rtems_heap_allocate_aligned_with_boundary(
138  size_t size,
139  uintptr_t alignment,
140  uintptr_t boundary
141) RTEMS_MALLOCLIKE RTEMS_ALLOC_SIZE(1) RTEMS_ALLOC_ALIGN(2)
142  RTEMS_WARN_UNUSED_RESULT;
143
144/**
145 * @brief Allocates a memory area of the specified size from the heap.
146 *
147 * This function is almost identical to malloc(). The only exception is that
148 * errno is not set in case of a memory allocation failure.
149 *
150 * @param[in] size The memory area size in bytes.
151 *
152 * @retval NULL The memory allocation failed or @a size is zero.
153 * @retval otherwise The begin address of the allocated memory area.
154 */
155void *rtems_malloc(size_t size)
156  RTEMS_MALLOCLIKE RTEMS_ALLOC_SIZE(1) RTEMS_WARN_UNUSED_RESULT;
157
158/**
159 * @brief Allocates a memory area for the specified count of elements from the
160 * heap.
161 *
162 * The allocated memory area is fully filled with zero bits.
163 *
164 * This function is almost identical to calloc(). The only exception is that
165 * errno is not set in case of a memory allocation failure.
166 *
167 * @param[in] nelem The count of elements.
168 * @param[in] elsize The size of each elements.
169 *
170 * @retval NULL The memory allocation failed or @a nelem is zero or @a elsize
171 *   is zero.
172 * @retval otherwise The begin address of the allocated memory area.
173 */
174void *rtems_calloc(size_t nelem, size_t elsize)
175  RTEMS_MALLOCLIKE RTEMS_ALLOC_SIZE_2(1, 2) RTEMS_WARN_UNUSED_RESULT;
176
177/**
178 * @brief Extends the memory available for the heap using the memory area
179 * starting at @a area_begin of size @a area_size bytes.
180 *
181 * There are no alignment requirements.  The memory area must be big enough to
182 * contain some maintenance blocks.  It must not overlap parts of the current
183 * heap areas.  Disconnected subordinate heap areas will lead to used blocks
184 * which cover the gaps.  Extending with an inappropriate memory area will
185 * corrupt the heap.
186 *
187 * @retval RTEMS_SUCCESSFUL Successful operation.
188 * @retval RTEMS_INVALID_ADDRESS Invalid memory area.
189 */
190rtems_status_code rtems_heap_extend(
191  void *area_begin,
192  uintptr_t area_size
193);
194
195/**
196 * @brief Greedy allocate that empties the heap.
197 *
198 * Afterwards the heap has at most @a block_count allocatable blocks of sizes
199 * specified by @a block_sizes.  The @a block_sizes must point to an array with
200 * @a block_count members.  All other blocks are used.
201 *
202 * @see rtems_heap_greedy_free().
203 */
204void *rtems_heap_greedy_allocate(
205  const uintptr_t *block_sizes,
206  size_t block_count
207);
208
209/**
210 * @brief Greedy allocate all blocks except the largest free block.
211 *
212 * Afterwards the heap has at most one allocatable block.  This block is the
213 * largest free block if it exists.  The allocatable size of this block is
214 * stored in @a allocatable_size.  All other blocks are used.
215 *
216 * @see rtems_heap_greedy_free().
217 */
218void *rtems_heap_greedy_allocate_all_except_largest(
219  uintptr_t *allocatable_size
220);
221
222/**
223 * @brief Frees space of a greedy allocation.
224 *
225 * The @a opaque argument must be the return value of
226 * rtems_heap_greedy_allocate() or
227 * rtems_heap_greedy_allocate_all_except_largest().
228 */
229void rtems_heap_greedy_free( void *opaque );
230
231#ifdef __cplusplus
232}
233#endif
234
235#endif
Note: See TracBrowser for help on using the repository browser.