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