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