1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 import xdc.rov.ViewInfo;
18
19 /*!
20 * ======== HeapMin ========
21 * Growth-only based heap implementation.
22 *
23 * `HeapMin` is a minimal footprint heap implementation. This module is
24 * is designed for applications that only create module instances and
25 * generally only allocate memory at runtime, but never delete created
26 * instances or free memory explicitly.
27 *
28 * For configuration-time `HeapMin.create`, the heap is aligned to
29 * `{@link Memory#getMaxDefaultTypeAlignMeta()}` for those targets that support
30 * static alignment. For targets that do not support static alignment, the
31 * buffer alignment is undefined.
32 *
33 * When calling `{@link #create()}` at runtime, the client
34 * is responsible for aligning the buffer.
35 */
36 @RomConsts
37
38 module HeapMin inherits xdc.runtime.IHeap {
39
40 /*! @_nodoc */
41 @XmlDtd
42 metaonly struct BasicView {
43 String label;
44 Ptr buffer;
45 Memory.Size remainSize;
46 Memory.Size startSize;
47 }
48
49 /*! @_nodoc */
50 @Facet
51 metaonly config ViewInfo.Instance rovViewInfo =
52 ViewInfo.create({
53 viewMap: [
54 [
55 'Basic',
56 {
57 type: ViewInfo.INSTANCE,
58 viewInitFxn: 'viewInitBasic',
59 structName: 'BasicView'
60 }
61 ],
62 ]
63 });
64
65 /*!
66 * ======== A_zeroSize ========
67 * Assert that the `{@link #size}` is non-zero on the create
68 */
69 config Assert.Id A_zeroSize =
70 {msg: "HeapMin_create cannot have a zero size value"};
71
72 /*!
73 * ======== E_freeError ========
74 * Error raised if `{@link #free()}` is called.
75 *
76 * This error is only raised if a `{@link #free()}`
77 * is called and `{@link #freeError}` is true.
78 */
79 config Error.Id E_freeError = {
80 msg: "free() invalid in growth-only HeapMin"
81 };
82
83 /*!
84 * ======== freeError ========
85 * Flag to control whether `{@link #E_freeError}` is enabled.
86 *
87 * If true, a `{@link #E_freeError}` error occurs when trying
88 * to free a buffer.
89 *
90 * If false, no error occurs and the `{@link #free()}` does nothing.
91 */
92 config Bool freeError = true;
93
94 instance:
95
96 /*!
97 * ======== align ========
98 * Alignment of the buffer being managed by this heap instance.
99 *
100 * In the static HeapMin.create() call, the buffer allocated for the
101 * HeapMin instance will have the alignment specified by this parameter
102 * on targets that support static alignment.
103 *
104 * In the dynamic case, the client must supply the buffer, so it is the
105 * client's responsibility to manage the buffer's alignment, and there is
106 * no 'align' parameter.
107 *
108 * The specified `align` parameter must be a power of 2.
109 *
110 * The default alignment of zero causes the buffer to get aligned using
111 * {@link Memory#getMaxDefaultTypeAlignMeta()}.
112 */
113 metaonly config SizeT align;
114
115 /*!
116 * ======== create ========
117 * Create a `HeapMin` heap
118 *
119 * This heap is a growth-only heap that is intended to be used by
120 * systems that never delete objects or free memory. Objects can be
121 * created at runtime based on values determined at runtime, but
122 * objects can not be deleted.
123 *
124 * @see HeapMin#Params
125 */
126 create();
127
128 /*!
129 * ======== sectionName ========
130 * Section name of the heap
131 *
132 * When creating heaps during configuration, this parameter specifies
133 * where the heap's buffer will be placed. This parameter is passed as
134 * the section name in the `{@link Memory#staticPlace}` function.
135 *
136 * @see Memory#staticPlace
137 */
138 metaonly config String sectionName = null;
139
140 /*!
141 * ======== buf ========
142 * Buffer that will be managed by the heap instance.
143 *
144 * When creating a heap at runtime, the user must supply the memory
145 * that the heap will manage. It is up to the caller to align
146 * the buffer as needed.
147 *
148 * This parameter is ignored when creating heaps during configuration.
149 */
150 config Ptr buf = 0;
151
152 /*!
153 * ======== size ========
154 * Size (in MADUs) of the heap.
155 *
156 * This parameter specifies the size of the heap managed by a
157 * `HeapMin` instance. In the static case, a buffer of length `size`
158 * will be created. In the dynamic case, `size` specifies the size of
159 * the buffer (i.e. parameter `buf`) that the caller provides.
160 *
161 * This is a required parameter. It must be set by the caller. Failure
162 * to do so, will result in a build error for the static create or an
163 * `{@link #A_zeroSize}` assert for the runtime create.
164 */
165 config Memory.Size size = 0;
166
167 /*!
168 * ======== alloc ========
169 * Allocate a block of memory from the heap.
170 *
171 * @a(Constraints)
172 * The alignment must be a power of 2.
173 *
174 * @see IHeap#alloc
175 */
176 override Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
177
178 /*!
179 * ======== free ========
180 * Free a block of memory back to the heap.
181 *
182 * This is a growth only heap. Calling the `HeapMin_free` function
183 * will result in a `{@link #E_freeError}` error unless
184 * `{@link #freeError}` is set to `false`.
185 *
186 * @see IHeap#free
187 */
188 override Void free(Ptr block, SizeT size);
189
190 /*!
191 * ======== isBlocking ========
192 * Can this heap block the caller
193 *
194 * @a(returns)
195 * `HeapMin` always returns `FALSE` since it never blocks on a
196 * resource.
197 */
198 override Bool isBlocking();
199
200 internal:
201
202 struct Instance_State {
203 Char buf[];
204 Memory.Size remainSize;
205 Memory.Size startSize;
206 };
207 }
208 209 210
211