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