1 2 3 4 5 6 7 8 9 10 11 12
13 14 15 16 17
18
19 /*!
20 * ======== HeapStd ========
21 * Malloc/free based heap implementation.
22 *
23 * This heap is based on the ANSI C Standard Library functions
24 * `malloc()` and `free()` and assumes that these functions are thread-safe.
25 * Please refer to the target specific documentation of the ANSI C Standard
26 * Library for details.
27 *
28 * The largest free block that can be returned form `malloc()` cannot be
29 * determined. Therefore, the property `largestFreeSize` in
30 * `{@link Memory#Stats}` returned from `{@link #getStats()}` always returns
31 * 0.
32 *
33 * @a(Constraints)
34 * The `{@link #alloc()}` function only supports alignment requests up to
35 * value returned from
36 * `{@link Memory#getMaxDefaultTypeAlign()}`.
37 */
38
39 @InstanceInitError
40 @RomConsts
41
42 module HeapStd inherits xdc.runtime.IHeap {
43
44 /*! @_nodoc */
45 @XmlDtd
46 metaonly struct Instance_View {
47 Ptr address;
48 String label;
49 Memory.Size remainSize;
50 Memory.Size startSize;
51 }
52
53 /*!
54 * ======== HEAP_MAX ========
55 * Maximum heap size of HeapStd
56 *
57 * This parameter defines maximum heap size that can be allocated to a
58 * `HeapStd` instance. Using this parameter to create `HeapStd` instances
59 * will disable the internal size checks in `HeapStd` module.
60 */
61 const SizeT HEAP_MAX = ~0U;
62
63 /*!
64 * ======== E_noRTSMemory ========
65 * Error raised if all the RTS heap is used up
66 *
67 * The total size of all `HeapStd` instance allocations added together
68 * cannot exceed the `malloc`/`free` heap size determined by
69 * `{@link xdc.cfg.Program#heap}`.
70 */
71 config Error.Id E_noRTSMemory = {
72 msg: "The RTS heap is used up. Examine Program.heap."
73 };
74
75 /*!
76 * ======== A_zeroSize ========
77 * Assert that the `{@link #size}` is non-zero on the create
78 */
79 config Assert.Id A_zeroSize = {
80 msg: "HeapStd_create cannot have a zero size value"
81 };
82
83 /*!
84 * ======== A_align ========
85 * Assert that the `{@link #size}` is a power of 2
86 */
87 config Assert.Id A_align = {
88 msg: "HeapStd_alloc alignment must be a power of 2"
89 };
90
91 /*!
92 * ======== A_invalidTotalFreeSize ========
93 * Assert that remaining size is less than or equal to starting size.
94 *
95 * If this assertion is raised, it means that either incorrect sizes
96 * were passed to `{@link #free}` or multiple calls to `{@link #free}`
97 * were made with the same buffer.
98 */
99 config Assert.Id A_invalidTotalFreeSize = {
100 msg: "HeapStd instance totalFreeSize is greater than starting size"
101 };
102
103 /*!
104 * ======== A_invalidAlignment ========
105 * Assert that the alignment argument in alloc is valid
106 * @_nodoc
107 *
108 * If this assertion is raised, it means that the requested alignment is
109 * greater than the maximum alignment allowed on the target.
110 */
111 config Assert.Id A_invalidAlignment = {
112 msg: "HeapStd_alloc - requested alignment is greater than allowed"
113 };
114
115 instance:
116
117 /*!
118 * ======== create ========
119 * Create a `HeapStd` heap
120 *
121 * This heap uses the ANSI C Standard Library functions
122 * `malloc()` and `free()` to manage memory and assumes that these
123 * functions are thread-safe.
124 *
125 * @see HeapStd#Params
126 */
127 create();
128
129 /*!
130 * ======== size ========
131 * Size (in MAUs) of the heap.
132 *
133 * This parameter specifies the size of the heap managed by a
134 * `HeapStd` instance. `HeapStd` is built upon the ANSI C Standard
135 * Library functions `malloc()` and `free()`.
136 *
137 * The total size of all `HeapStd` instance allocations added together
138 * cannot exceed the `malloc`/`free` heap size determined by
139 * `{@link xdc.cfg.Program#heap Program.heap}`.
140 *
141 * This is a required parameter. It must be set by the caller. Failure
142 * to do so, will result in a build error for the static create or an
143 * assert for the runtime create.
144 */
145 config Memory.Size size = 0;
146
147 /*!
148 * ======== alloc ========
149 * Allocates a block of memory from the heap.
150 *
151 * @a(Constraints)
152 * The only alignment currently supported is the default
153 * alignment returned by the underlying `malloc()` implementation.
154 * The align value must be less than or equal to the value returned from
155 * `{@link Memory#getMaxDefaultTypeAlign()}`.
156 *
157 * @see IHeap#alloc
158 */
159 override Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
160
161 /*!
162 * ======== isBlocking ========
163 * Returns whether the heap may block during an `HeapStd_alloc()` or
164 * `HeapStd_free()`.
165 *
166 * @a(returns)
167 * Since the implementation of the underlaying ANSI C Standard Library
168 * is not known, this function always returns the more restrictive case
169 * which is `TRUE`.
170 */
171 override Bool isBlocking();
172
173 internal:
174
175 struct Module_State {
176 Memory.Size remainRTSSize;
177 };
178
179 struct Instance_State {
180 Memory.Size remainSize;
181 Memory.Size startSize;
182 };
183 }
184 185 186
187