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