ChibiOS/NIL  3.2.2
chmemheaps.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio.
3 
4  This file is part of ChibiOS.
5 
6  ChibiOS is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 3 of the License, or
9  (at your option) any later version.
10 
11  ChibiOS is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  GNU General Public License for more details.
15 
16  You should have received a copy of the GNU General Public License
17  along with this program. If not, see <http://www.gnu.org/licenses/>.
18 */
19 
20 /**
21  * @file chmemheaps.h
22  * @brief Memory heaps macros and structures.
23  *
24  * @addtogroup oslib_memheaps
25  * @{
26  */
27 
28 #ifndef CHMEMHEAPS_H
29 #define CHMEMHEAPS_H
30 
31 #if (CH_CFG_USE_HEAP == TRUE) || defined(__DOXYGEN__)
32 
33 /*===========================================================================*/
34 /* Module constants. */
35 /*===========================================================================*/
36 
37 /**
38  * @brief Minimum alignment used for heap.
39  * @note Cannot use the sizeof operator in this macro.
40  */
41 #if (SIZEOF_PTR == 4) || defined(__DOXYGEN__)
42 #define CH_HEAP_ALIGNMENT 8U
43 #elif (SIZEOF_PTR == 2)
44 #define CH_HEAP_ALIGNMENT 4U
45 #else
46 #error "unsupported pointer size"
47 #endif
48 
49 /*===========================================================================*/
50 /* Module pre-compile time settings. */
51 /*===========================================================================*/
52 
53 /*===========================================================================*/
54 /* Derived constants and error checks. */
55 /*===========================================================================*/
56 
57 #if CH_CFG_USE_MEMCORE == FALSE
58 #error "CH_CFG_USE_HEAP requires CH_CFG_USE_MEMCORE"
59 #endif
60 
61 #if (CH_CFG_USE_MUTEXES == FALSE) && (CH_CFG_USE_SEMAPHORES == FALSE)
62 #error "CH_CFG_USE_HEAP requires CH_CFG_USE_MUTEXES and/or CH_CFG_USE_SEMAPHORES"
63 #endif
64 
65 /*===========================================================================*/
66 /* Module data structures and types. */
67 /*===========================================================================*/
68 
69 /**
70  * @brief Type of a memory heap.
71  */
72 typedef struct memory_heap memory_heap_t;
73 
74 /**
75  * @brief Type of a memory heap header.
76  */
77 typedef union heap_header heap_header_t;
78 
79 /**
80  * @brief Memory heap block header.
81  */
82 union heap_header {
83  struct {
84  heap_header_t *next; /**< @brief Next block in free list. */
85  size_t pages; /**< @brief Size of the area in pages. */
86  } free;
87  struct {
88  memory_heap_t *heap; /**< @brief Block owner heap. */
89  size_t size; /**< @brief Size of the area in bytes. */
90  } used;
91 };
92 
93 /**
94  * @brief Structure describing a memory heap.
95  */
96 struct memory_heap {
97  memgetfunc2_t provider; /**< @brief Memory blocks provider for
98  this heap. */
99  heap_header_t header; /**< @brief Free blocks list header. */
100 #if (CH_CFG_USE_MUTEXES == TRUE) || defined(__DOXYGEN__)
101  mutex_t mtx; /**< @brief Heap access mutex. */
102 #else
103  semaphore_t sem; /**< @brief Heap access semaphore. */
104 #endif
105 };
106 
107 /*===========================================================================*/
108 /* Module macros. */
109 /*===========================================================================*/
110 
111 /**
112  * @brief Allocation of an aligned static heap buffer.
113  */
114 #define CH_HEAP_AREA(name, size) \
115  ALIGNED_VAR(CH_HEAP_ALIGNMENT) \
116  uint8_t name[MEM_ALIGN_NEXT((size), CH_HEAP_ALIGNMENT)]
117 
118 /*===========================================================================*/
119 /* External declarations. */
120 /*===========================================================================*/
121 
122 #ifdef __cplusplus
123 extern "C" {
124 #endif
125  void _heap_init(void);
126  void chHeapObjectInit(memory_heap_t *heapp, void *buf, size_t size);
127  void *chHeapAllocAligned(memory_heap_t *heapp, size_t size, unsigned align);
128  void chHeapFree(void *p);
129  size_t chHeapStatus(memory_heap_t *heapp, size_t *totalp, size_t *largestp);
130 #ifdef __cplusplus
131 }
132 #endif
133 
134 /*===========================================================================*/
135 /* Module inline functions. */
136 /*===========================================================================*/
137 
138 /**
139  * @brief Allocates a block of memory from the heap by using the first-fit
140  * algorithm.
141  * @details The allocated block is guaranteed to be properly aligned for a
142  * pointer data type.
143  *
144  * @param[in] heapp pointer to a heap descriptor or @p NULL in order to
145  * access the default heap.
146  * @param[in] size the size of the block to be allocated. Note that the
147  * allocated block may be a bit bigger than the requested
148  * size for alignment and fragmentation reasons.
149  * @return A pointer to the allocated block.
150  * @retval NULL if the block cannot be allocated.
151  *
152  * @api
153  */
154 static inline void *chHeapAlloc(memory_heap_t *heapp, size_t size) {
155 
156  return chHeapAllocAligned(heapp, size, CH_HEAP_ALIGNMENT);
157 }
158 
159 /**
160  * @brief Returns the size of an allocated block.
161  * @note The returned value is the requested size, the real size is the
162  * same value aligned to the next @p CH_HEAP_ALIGNMENT multiple.
163  *
164  * @param[in] p pointer to the memory block
165  * @return Size of the block.
166  *
167  * @api
168  */
169 static inline size_t chHeapGetSize(const void *p) {
170 
171  return ((heap_header_t *)p - 1U)->used.size;
172 }
173 
174 #endif /* CH_CFG_USE_HEAP == TRUE */
175 
176 #endif /* CHMEMHEAPS_H */
177 
178 /** @} */
void chHeapFree(void *p)
Frees a previously allocated memory block.
Definition: chmemheaps.c:293
Memory heap block header.
Definition: chmemheaps.h:82
memgetfunc2_t provider
Memory blocks provider for this heap.
Definition: chmemheaps.h:97
static void * chHeapAlloc(memory_heap_t *heapp, size_t size)
Allocates a block of memory from the heap by using the first-fit algorithm.
Definition: chmemheaps.h:154
heap_header_t header
Free blocks list header.
Definition: chmemheaps.h:99
static size_t chHeapGetSize(const void *p)
Returns the size of an allocated block.
Definition: chmemheaps.h:169
void *(* memgetfunc2_t)(size_t size, unsigned align, size_t offset)
Enhanced memory get function.
Definition: chmemcore.h:76
void * chHeapAllocAligned(memory_heap_t *heapp, size_t size, unsigned align)
Allocates a block of memory from the heap by using the first-fit algorithm.
Definition: chmemheaps.c:172
mutex_t mtx
Heap access mutex.
Definition: chmemheaps.h:101
size_t chHeapStatus(memory_heap_t *heapp, size_t *totalp, size_t *largestp)
Reports the heap status.
Definition: chmemheaps.c:357
size_t pages
Size of the area in pages.
Definition: chmemheaps.h:85
void chHeapObjectInit(memory_heap_t *heapp, void *buf, size_t size)
Initializes a memory heap from a static memory area.
Definition: chmemheaps.c:131
size_t size
Size of the area in bytes.
Definition: chmemheaps.h:89
#define CH_HEAP_ALIGNMENT
Minimum alignment used for heap.
Definition: chmemheaps.h:42
heap_header_t * next
Next block in free list.
Definition: chmemheaps.h:84
memory_heap_t * heap
Block owner heap.
Definition: chmemheaps.h:88
Structure representing a queue of threads.
Definition: ch.h:579
void _heap_init(void)
Initializes the default heap.
Definition: chmemheaps.c:107
Structure describing a memory heap.
Definition: chmemheaps.h:96