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