1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 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 metaonly struct BasicView {
91 UArg arg;
92 UArg context;
93 }
94
95 /*! @_nodoc */
96 metaonly struct 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 metaonly config 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:
313
314 struct Instance_State {
315 UArg context;
316 UArg arg;
317 };
318 }