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