1 /*
2 * Copyright (c) 2013, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32 /*
33 * ======== HeapCallback.xdc ========
34 */
35
36 package ti.sysbios.heaps;
37
38 import xdc.rov.ViewInfo;
39 import xdc.runtime.Memory;
40
41 /*!
42 * ======== HeapCallback ========
43 * A heap that calls user supplied callback functions
44 *
45 * The HeapCallback module enables users to provide a custom heap
46 * implementation by providing callback functions that will be invoked
47 * by HeapCallback for the various heap management functions.
48 *
49 * The user-supplied HeapCallback.initInstFxn is called during boot time to
50 * initialize any HeapCallback objects that were created in the .cfg file.
51 * The user-supplied HeapCallback.createInstFxn is called during runtime
52 * for any calls to HeapCallback_create(). Both of these functions return
53 * a context value (typically a pointer to an object managed by the
54 * user-supplied heap code). This context value is passed to subsequent
55 * user allocInstFxn, freeInstFxn, etc. functions.
56 *
57 * HeapCallback_alloc(), HeapCallback_free() and HeapCallback_getStats()
58 * call the user-supplied allocInstFxn, freeInstFxn and getStatsInstFxn
59 * functions with the context value returned by initInstFxn or createInstFxn.
60 *
61 * HeapCallback_delete() calls the user-supplied instDeleteFxn with the
62 * context returned by the createInstFxn.
63 *
64 * @a(Examples) 65 * Configuration example: The following XDC configuration statements
66 * creates a HeapCallback instance and plugs in the user defined functions.
67 *
68 * @p(code) 69 * var HeapCallback = xdc.useModule('ti.sysbios.heaps.HeapCallback');
70 *
71 * var params = new HeapCallback.Params();
72 * params.arg = 1;
73 * HeapCallback.create(params);
74 *
75 * HeapCallback.initInstFxn = '&userInitFxn';
76 * HeapCallback.createInstFxn = '&userCreateFxn';
77 * HeapCallback.deleteInstFxn = '&userDeleteFxn';
78 * HeapCallback.allocInstFxn = '&userAllocFxn';
79 * HeapCallback.freeInstFxn = '&userFreeFxn';
80 * HeapCallback.getStatsInstFxn = '&userGetStatsFxn';
81 * HeapCallback.isBlockingInstFxn = '&userIsBlockingFxn';
82 *
83 * @p 84 */
85 @ModuleStartup
86 @InstanceFinalize
87 module HeapCallback inherits xdc.runtime.IHeap {
88
89 /*! @_nodoc */
90 metaonlystruct BasicView {
91 UArg arg;
92 UArg context;
93 }
94
95 /*! @_nodoc */
96 metaonlystruct ModuleView {
97 String initInstFxn;
98 String createInstFxn;
99 String deleteInstFxn;
100 String allocInstFxn;
101 String freeInstFxn;
102 String getStatsInstFxn;
103 String isBlockingInstFxn;
104 }
105
106 /*!
107 * ======== rovViewInfo ========
108 * @_nodoc 109 */
110 @Facet
111 metaonlyconfig xdc.rov.ViewInfo.Instance rovViewInfo =
112 xdc.rov.ViewInfo.create({
113 viewMap: [
114 ['Basic',
115 {
116 type: ViewInfo.INSTANCE,
117 viewInitFxn: 'viewInitBasic',
118 structName: 'BasicView'
119 }
120 ],
121 ['Module',
122 {
123 type: xdc.rov.ViewInfo.MODULE,
124 viewInitFxn: 'viewInitModule',
125 structName: 'ModuleView'
126 }
127 ]
128 ]
129 });
130
131 /*!
132 * ======== AllocInstFxn ========
133 * Instance alloc callback function signature
134 *
135 * This function takes the context return from createInstFxn(), the
136 * size to be allocated and the align value. The return value from
137 * this function is a pointer to the allocated memory block.
138 */
139 typedef Ptr (*AllocInstFxn)(UArg, SizeT, SizeT);
140
141 /*!
142 * ======== CreateInstFxn ========
143 * Instance create callback function signature
144 *
145 * {@link HeapCallback#arg} is passed as an argument to this function.
146 * The return value from this function (context) will be passed as an
147 * argument to the other instance functions.
148 */
149 typedef UArg (*CreateInstFxn)(UArg);
150
151 /*!
152 * ======== DeleteInstFxn ========
153 * Instance delete callback function signature
154 *
155 * The context returned from createInstFxn() is passed as an argument to
156 * this function.
157 */
158 typedef Void (*DeleteInstFxn)(UArg);
159
160 /*!
161 * ======== FreeInstFxn ========
162 * Instance free callback function signature
163 *
164 * This function takes the context returned by createInstFxn() and a
165 * pointer to the buffer to be freed and the size to be freed.
166 */
167 typedef Void (*FreeInstFxn)(UArg, Ptr, SizeT);
168
169 /*!
170 * ======== GetStatsInstFxn ========
171 * Instance getStats callback function signature
172 *
173 * This function takes the context returned by createInstFxn() and a
174 * pointer to a memory stats object.
175 */
176 typedef Void (*GetStatsInstFxn)(UArg, Memory.Stats *);
177
178 /*!
179 * ======== InitInstFxn ========
180 * Instance init callback function signature
181 *
182 * `{@link HeapCallback#arg} is passed as an argument to this function.
183 * The return value from this function (context) will passed as an
184 * argument to the other instance functions.
185 */
186 typedef UArg (*InitInstFxn)(UArg);
187
188 /*!
189 * ======== IsBlockingInstFxn ========
190 * Instance isblocking callback function signature
191 *
192 * The context return from createInstFxn() is passed as an argument to
193 * this function. The return value is 'TRUE' or 'FALSE'.
194 */
195 typedef Bool (*IsBlockingInstFxn)(UArg);
196
197 /*!
198 * ======== allocInstFxn ========
199 * User supplied instance alloc function
200 *
201 * This function is called when the `{@link HeapCallback#alloc}` is
202 * called.
203 *
204 * This parameter is configured with a default alloc function. The
205 * default alloc function returns NULL.
206 */
207 config AllocInstFxn allocInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultAlloc';
208
209 /*!
210 * ======== createInstFxn ========
211 * User supplied instance create function
212 *
213 * This function is called when the `{@link HeapCallback#create}` is
214 * called.
215 *
216 * This parameter is configured with a default create function.
217 * The default create function returns 0.
218 */
219 config CreateInstFxn createInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultCreate';
220
221 /*!
222 * ======== deleteInstFxn ========
223 * User supplied instance delete function
224 *
225 * This function is called when the `{@link HeapCallback#delete}` is
226 * called.
227 *
228 * This parameter is configured with a default delete function.
229 */
230 config DeleteInstFxn deleteInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultDelete';
231
232 /*!
233 * ======== freeInstFxn ========
234 * User supplied instance free function
235 *
236 * This function is called when the `{@link HeapCallback#free}` is
237 * called.
238 *
239 * This parameter is configured with a default free function.
240 */
241 config FreeInstFxn freeInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultFree';
242
243 /*!
244 * ======== getStatsInstFxn ========
245 * User supplied getStat function
246 *
247 * This function is called when the `{@link HeapCallback#getStat}` is
248 * called.
249 *
250 * This parameter is configured with a default getStats function.
251 * The default getStats function does not make any changes to stats
252 * structure.
253 */
254 config GetStatsInstFxn getStatsInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultGetStats';
255
256 /*!
257 * ======== initInstFxn ========
258 * User supplied init function
259 *
260 * This function is called in Module startup for statically created
261 * instances. The user-supplied function must not do any memory
262 * allocations or call any module create functions (e.g.,
263 * Semaphore_create()).
264 *
265 * This parameter is configured with a default init function. The
266 * default init function returns NULL.
267 */
268 config InitInstFxn initInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultInit';
269
270 /*!
271 * ======== isBlockingInstFxn ========
272 * User supplied isBlocking function
273 *
274 * This function is called when the `{@link HeapCallback#isBlocking}` is
275 * called.
276 *
277 * This parameter is configured with a default isBlocking function. The
278 * default isBlocking returns FALSE.
279 */
280 config IsBlockingInstFxn isBlockingInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultIsBlocking';
281
282 instance:
283
284 /*!
285 * ======== create ========
286 * Create a `HeapCallback` Heap instance
287 */
288 create();
289
290 /*!
291 * ======== getContext ========
292 * Get the context returned from user supplied create function
293 */
294 UArg getContext();
295
296 /*!
297 * ======== arg ========
298 * User supplied argument for the user supplied create function.
299 *
300 * This user supplied argument will be passed back as an argument to the
301 * `createInstFxn` function. It can be used by the
302 * `{@link HeapCallback#createInstFxn}` function at runtime to
303 * differentiate between the multiple Heap instances configured in the
304 * user config script.
305 *
306 * The user can skip configuring this argument. In such a case, the
307 * default value `0` will be passed back as an argument to the
308 * `createInstFxn` function.
309 */
310 config UArg arg = 0;
311
312 internal: /* not for client use */
313
314 struct Instance_State {
315 UArg context; /* context returned from createInstFxn */
316 UArg arg; /* argument to createInstFxn */
317 };
318 }