source: rtems/doc/itron3.0/memorypool.t @ 1baa059

4.104.114.84.9
Last change on this file since 1baa059 was 1baa059, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 9, 1999 at 4:40:44 PM

Converted from DOS to UNIX filemode.

  • Property mode set to 100644
File size: 13.8 KB
Line 
1@c
2@c  This is the chapter from the RTEMS ITRON User's Guide that
3@c  documents the services provided by the memory pool
4@c  manager.
5@c
6@c  $Id$
7@c
8
9@chapter Memory Pool Manager
10
11@section Introduction
12
13The
14memory pool manager is ...
15
16The services provided by the memory pool manager are:
17
18@itemize @bullet
19@item @code{cre_mpl} - Create Variable-Size Memorypool
20@item @code{del_mpl} - Delete Variable-Size Memorypool
21@item @code{get_blk} - Get Variable-Size Memory Block
22@item @code{pget_blk} - Poll and Get Variable-Size Memory Block
23@item @code{tget_blk} - Get Variable-Size Memory Block with Timeout
24@item @code{rel_blk} - Release Variable-Size Memory Block
25@item @code{ref_mpl} - Reference Variable-Size Memorypool Status
26@end itemize
27
28@section Background
29
30Memorypool management functions manage memorypools and allocate memory blocks.
31There are two types of memorypool: fixed-size memorypools and variable-size
32memorypools.  Both are considered separate objects and require different
33system calls for manipulation.  While the size of memory blocks allocated
34from fixed-size memorypools are all fixed, blocks of any size may be
35specified when allocating memory blocks from variable-size memorypools.
36
37@section Operations
38
39@section System Calls
40
41This section details the memory pool manager's services.
42A subsection is dedicated to each of this manager's services
43and describes the calling sequence, related constants, usage,
44and status codes.
45
46
47@c
48@c  cre_mpl
49@c
50
51@page
52@subsection cre_mpl - Create Variable-Size Memorypool
53
54@subheading CALLING SEQUENCE:
55
56@ifset is-C
57@example
58ER cre_mpl(
59  ID mplid,
60  T_CMPL *pk_cmpl
61);
62@end example
63@end ifset
64
65@ifset is-Ada
66@end ifset
67
68@subheading STATUS CODES:
69
70@code{E_OK} - Normal Completion
71
72@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for
73memorypool cannot be allocated)
74
75@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
76
77@code{E_RSATR} - Reserved attribute (mplatr was invalid or could not be used)
78
79@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists)
80
81@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
82a user task.  This is implementation dependent.)
83
84@code{E_PAR} - Parameter error (pk_cmpl is invalid or mplsz is negative or
85invalid)
86
87@subheading DESCRIPTION:
88
89The cre_mpl directive creates a variable-size memorypool having the ID number specified by mplid.  Specifically, a memory area of the size determined by mplsz is allocated for use as a memorypool.  A control block for the memorypool being created is also allocated.  User memorypools have positive ID numbers, while system memorypools have negative ID numbers.  User tasks (tasks having positive task IDs) cannot access system memorypools (memorypools having negative ID numbers).
90
91@subheading NOTES:
92
93The memory required for creating memorypools and for allocating control blocks for each object is reserved while system initialization. Associated parameters are therefore specified at system configuration.
94
95@c
96@c  del_mpl
97@c
98
99@page
100@subsection del_mpl - Delete Variable-Size Memorypool
101
102@subheading CALLING SEQUENCE:
103
104@ifset is-C
105@example
106ER del_mpl(
107  ID mplid
108);
109@end example
110@end ifset
111
112@ifset is-Ada
113@end ifset
114
115@subheading STATUS CODES:
116 
117@code{E_OK} - Normal Completion
118 
119@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
120 
121@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
122 
123@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
124a user task.  This is implementation dependent.)
125
126@subheading DESCRIPTION:
127
128This system call deletes the variable-size memorypool specified by mplid.  No check or error report is performed even if there are tasks using memory from the memorypool to be deleted.  This system call completes normally even if some of the memory blocks are not returned.  Issuing this system call causes memory used for the control block of the associated memorypool and the memory area making up the memorypool itself to be released.  After this system call is invoked, another memorypool having the same ID number can be created.
129
130@subheading NOTES:
131
132When a memorypool being waited for by more than one tasks is deleted, the order of tasks on the ready queue after the WAIT state is cleared is implementation dependent in the case of tasks having the same priority.
133
134@c
135@c  get_blk
136@c
137
138@page
139@subsection get_blk - Get Variable-Size Memory Block
140
141@subheading CALLING SEQUENCE:
142
143@ifset is-C
144@example
145ER get_blk(
146  VP *p_blk,
147  ID mplid,
148  INT blksz
149);
150@end example
151@end ifset
152
153@ifset is-Ada
154@end ifset
155
156@subheading STATUS CODES:
157
158@code{E_OK} - Normal Completion
159 
160@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
161 
162@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
163 
164@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
165a user task.  This is implementation dependent.)
166 
167@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
168 
169@code{E_DLT} - The object being waited for was deleted (the specified memorypool
170was deleted while waiting)
171 
172@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
173waiting)
174 
175@code{E_TMOUT} - Polling failure or timeout
176
177@code{E_CTX} - Context error (issued from task-independent portions or a
178task in dispatch disabled state; implementation dependent for
179pget_blk and tget_blk(tmout=TMO_POL))
180
181@subheading DESCRIPTION:
182
183A memory block of the size in bytes given by blksz is allocated from the variable-size memorypool specified by mplid.  The start address of the memory block allocated is returned in blk.  The allocated memory block is not cleared to zero.  The contents of the memory block allocated are undefined.  If the memory block cannot be obtained from the specified memorypool when get_blk is issued, the task issuing get_blk will be placed on the memory allocation queue of the specified memorypool, and wait until it can get the memory it requires.
184
185The order in which tasks wait on the queue when waiting to be allocated memory blocks is according to either FIFO or task priority.  The specification whereby tasks wait according to task priority is considered an extended function [level X] for which compatibility is not guaranteed.  Furthermore, when tasks form a memory allocation queue, it is implementation dependent whether priority is given to tasks requesting the smaller size of memory or those at the head of the queue.
186
187@subheading NOTES:
188
189Pget_blk and get_blk represent the same processing as specifying certain values (TMO_POL or TMO_FEVR) to tget_blk for tmout.  It is allowed that only tget_blk is implemented in the kernel and that pget_blk and get_blk are implemented as macros which call tget_blk.
190
191@c
192@c  pget_blk
193@c
194
195@page
196@subsection pget_blk - Poll and Get Variable-Size Memory Block
197
198@subheading CALLING SEQUENCE:
199
200@ifset is-C
201@example
202ER ercd =pget_blk(
203  VP *p_blk,
204  ID mplid,
205  INT blksz
206);
207@end example
208@end ifset
209
210@ifset is-Ada
211@end ifset
212
213@subheading STATUS CODES:
214
215@code{E_OK} - Normal Completion
216 
217@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
218 
219@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
220 
221@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
222a user task.  This is implementation dependent.)
223 
224@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
225
226@code{E_DLT} - The object being waited for was deleted (the specified memorypool
227was deleted while waiting)
228 
229@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
230waiting)
231 
232@code{E_TMOUT} - Polling failure or timeout
233 
234@code{E_CTX} - Context error (issued from task-independent portions or a
235task in dispatch disabled state; implementation dependent for
236pget_blk and tget_blk(tmout=TMO_POL))
237
238@subheading DESCRIPTION:
239
240The pget_blk system call has the same function as get_blk except for the waiting feature.  Pget_blk polls whether or not the task should wait if get_blk is executed.  The meaning of parameters to pget_blk are the same with get_blk.  The specific operations by pget_blk are as follows.
241
242  - If there is enough free memory to get the memory block of specified size
243    immediately, processing is the same as get_blk: that is, the
244    requested memory is allocated and the system call completes normally.
245
246  - If there is not enough free memory, an E_TMOUT error is returned to
247    indicate polling failed and the system call finishes.  Unlike get_blk,
248    the issuing task does not wait in this case.  Also, the issuing task
249    does not get any memory.
250
251@subheading NOTES:
252
253@c
254@c  tget_blk
255@c
256
257@page
258@subsection tget_blk - Get Variable-Size Memory Block with Timeout
259
260@subheading CALLING SEQUENCE:
261
262@ifset is-C
263@example
264ER ercd =tget_blk(
265  VP *p_blk,
266  ID mplid,
267  INT blksz,
268  TMO tmout
269);
270@end example
271@end ifset
272
273@ifset is-Ada
274@end ifset
275
276@subheading STATUS CODES:
277
278@code{E_OK} - Normal Completion
279 
280@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
281 
282@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
283 
284@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
285a user task.  This is implementation dependent.)
286 
287@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
288
289@code{E_DLT} - The object being waited for was deleted (the specified memorypool
290was deleted while waiting)
291 
292@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
293waiting)
294 
295@code{E_TMOUT} - Polling failure or timeout
296 
297@code{E_CTX} - Context error (issued from task-independent portions or a
298task in dispatch disabled state; implementation dependent for
299pget_blk and tget_blk(tmout=TMO_POL))
300
301
302@subheading DESCRIPTION:
303
304The tget_blk system call has the same function as get_blk with an additional timeout feature.  A maximum wait time (timeout value) can be specified using the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT, will result and the system call will finish if the period specified by tmout elapses without conditions for releasing wait being satisfied (i.e. without sufficient free memory becoming available).
305
306@subheading NOTES:
307
308@c
309@c  rel_blk
310@c
311
312@page
313@subsection rel_blk - Release Variable-Size Memory Block
314
315@subheading CALLING SEQUENCE:
316
317@ifset is-C
318@example
319ER rel_blk(
320  ID mplid,
321  VP blk
322);
323@end example
324@end ifset
325
326@ifset is-Ada
327@end ifset
328
329@subheading STATUS CODES:
330 
331@code{E_OK} - Normal Completion
332 
333@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
334 
335@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
336 
337@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
338            a user task.  This is implementation dependent.)
339 
340@code{E_PAR} - Parameter error (blk is invalid or an attempt was made to return
341the memory block to the wrong memorypool)
342
343@subheading DESCRIPTION:
344
345This system call releases the memory block specified by blk and returns it to the variable-size memorypool specified by mplid.  Executing rel_blk allows memory to be allocated to the next task waiting for memory allocation from the memorypool given by mplid, thus releasing that task from its WAIT state.  The variable-size memorypool to which the memory block is returned must be the same memorypool from which it was originally allocated.  An E_PAR error will result if an attempt is made to return a memory block to another memorypool than that from which it was originally allocated.
346
347@subheading NOTES:
348
349When memory is returned to a variable-size memorypool for which more than one task is waiting, multiple tasks may be released from waiting at the same time depending on the number of bytes of memory.  The order of tasks on the ready queue among tasks having the same priority after being released from waiting for memory is implementation dependent.
350
351@c
352@c  ref_mpl
353@c
354
355@page
356@subsection ref_mpl - Reference Variable-Size Memorypool Status
357
358@subheading CALLING SEQUENCE:
359
360@ifset is-C
361@example
362ER ref_mpl(
363  T_RMPL *pk_rmpl,
364  ID mplid
365);
366@end example
367@end ifset
368
369@ifset is-Ada
370@end ifset
371
372@subheading STATUS CODES:
373 
374@code{E_OK} - Normal Completion
375 
376@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
377 
378@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
379 
380@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
381a user task.  This is implementation dependent.) Note: User tasks can issue ref_mpl in order to reference memorypools of mplid = TMPL_OS = -4.  Whether or not memorypools of mplid = -3 or -2 may be specified to ref_mpl by user tasks is implementation dependent.
382 
383@code{E_PAR} - Parameter error (the packet address for the return parameters
384could not be used)
385
386@subheading DESCRIPTION:
387
388This system call refers to the state of the variable-size memorypool specified by mplid, and returns the total free memory size currently available (frsz), the maximum continuous memory size of readily available free memory (maxsz), information of a task waiting to be allocated memory (wtsk), and its extended information (exinf).  Wtsk indicates, whether or not there is a task waiting to be allocated memory from the variable-size memorypool specified.  If there is no waiting task, wtsk is returned as FALSE = 0.  If there is a waiting task, wtsk is returned as a value other than 0.
389
390@subheading NOTES:
391
392In some implementations, memorypools having mplid = -3 or -2 may be referred with ref_mpl as memorypools used by implementation-dependent parts of the OS (such as those used for the stack only).  This system call can provide more detailed information regarding remaining memory if the usage of memorypools having mplid = -3 or -2 is more clearly defined.  Whether or not this feature is used and any details regarding information provided are implementation dependent.
393
Note: See TracBrowser for help on using the repository browser.