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