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 * ======== HeapStd.xdc ========
15 *! Open Issues:
16 *! - Do not really know the largestFreeSize value in HeapStd_getStats()
17 */
18
19 /*!
20 * ======== HeapStd ========
21 * Malloc/free based heap implementation.
22 *
23 * This heap is based on the ANSI C Standard Library functions
24 * `malloc()` and `free()` and assumes that these functions are thread-safe.
25 * Please refer to the target specific documentation of the ANSI C Standard
26 * Library for details.
27 *
28 * The largest free block that can be returned form `malloc()` cannot be
29 * determined. Therefore, the property `largestFreeSize` in
30 * `{@link Memory#Stats}` returned from `{@link #getStats()}` always returns
31 * 0.
32 *
33 * @a(Constraints) 34 * The `{@link #alloc()}` function only supports alignment requests up to
35 * value returned from
36 * `{@link Memory#getMaxDefaultTypeAlign()}`.
37 */
38
39 @InstanceInitError /* instance init can fail, call finalize if so */
40
41 module HeapStd inherits xdc.runtime.IHeap {
42
43 /*! @_nodoc */
44 @XmlDtd
45 metaonlystruct Instance_View {
46 Ptr address;
47 String label;
48 Memory.Size remainSize;
49 Memory.Size startSize;
50 }
51
52 /*!
53 * ======== E_noRTSMemory ========
54 * Error raised if all the RTS heap is used up
55 *
56 * The total size of all `HeapStd` instance allocations added together
57 * cannot exceed the `malloc`/`free` heap size determined by
58 * `{@link xdc.cfg.Program#heap}`.
59 */
60 config Error.Id E_noRTSMemory = {
61 msg: "The RTS heap is used up. Examine Program.heap."
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: "HeapStd_create cannot have a zero size value"
70 };
71
72 /*!
73 * ======== A_invalidTotalFreeSize ========
74 * Assert that remaining size is less than or equal to starting size.
75 *
76 * If this assertion is raised, it means that either incorrect sizes
77 * were passed to `{@link #free}` or multiple calls to `{@link #free}`
78 * were made with the same buffer.
79 */
80 config Assert.Id A_invalidTotalFreeSize = {
81 msg: "HeapStd instance totalFreeSize is greater than starting size"
82 };
83
84 /*!
85 * ======== A_invalidAlignment ========
86 * Assert that the alignment argument in alloc is valid
87 *
88 * If this assertion is raised, it means that the requested alignment is
89 * greater than the maximum alignment allowed on the target.
90 */
91 config Assert.Id A_invalidAlignment = {
92 msg: "HeapStd_alloc - requested alignment is greater than allowed"
93 };
94
95 instance:
96
97 /*!
98 * ======== create ========
99 * Create a `HeapStd` heap
100 *
101 * This heap uses the ANSI C Standard Library functions
102 * `malloc()` and `free()` to manage memory and assumes that these
103 * functions are thread-safe.
104 *
105 * @see HeapStd#Params
106 */
107 create();
108
109 /*!
110 * ======== size ========
111 * Size (in MAUs) of the heap.
112 *
113 * This parameter specifies the size of the heap managed by a
114 * `HeapStd` instance. `HeapStd` is built upon the ANSI C Standard
115 * Library functions `malloc()` and `free()`.
116 *
117 * The total size of all `HeapStd` instance allocations added together
118 * cannot exceed the `malloc`/`free` heap size determined by
119 * `{@link xdc.cfg.Program#heap Program.heap}`.
120 *
121 * This is a required parameter. It must be set by the caller. Failure
122 * to do so, will result in a build error for the static create or an
123 * assert for the runtime create.
124 */
125 config Memory.Size size = 0;
126
127 /*!
128 * ======== alloc ========
129 * Allocates a block of memory from the heap.
130 *
131 * @a(Constraints) 132 * The only alignment currently supported is the default
133 * alignment returned by the underlying `malloc()` implementation.
134 * The align value must be less than or equal to the value returned from
135 * `{@link Memory#getMaxDefaultTypeAlign()}`.
136 *
137 * @see IHeap#alloc
138 */
139 override Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
140
141 /*!
142 * ======== isBlocking ========
143 * Returns whether the heap may block during an `HeapStd_alloc()` or
144 * `HeapStd_free()`.
145 *
146 * @a(returns) 147 * Since the implementation of the underlaying ANSI C Standard Library
148 * is not known, this function always returns the more restrictive case
149 * which is `TRUE`.
150 */
151 override Bool isBlocking();
152
153 internal:
154
155 struct Module_State {
156 Memory.Size remainRTSSize; /* Remaining size of rts heap */
157 };
158
159 struct Instance_State {
160 Memory.Size remainSize; /* Size of the remaining heap. */
161 Memory.Size startSize; /* Starting size of the heap. */
162 };
163 }
164 /*
165 * @(#) xdc.runtime; 2, 1, 0,296; 11-16-2010 11:20:23; /db/ztree/library/trees/xdc/xdc-v53x/src/packages/
166 */
167