source: rtems/cpukit/include/rtems/malloc.h @ 6c66bbb

Last change on this file since 6c66bbb was 6c66bbb, checked in by Sebastian Huber <sebastian.huber@…>, on Apr 20, 2021 at 7:58:06 AM

malloc: Hide RTEMS_Malloc_Sbrk_amount

Move RTEMS_Malloc_Sbrk_amount to the only implementation file which uses
it and make it private to hide implementation-details from an API
header.

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