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