source: rtems/doc/itron3.0/memorypool.t @ 086a898a

4.104.114.84.95
Last change on this file since 086a898a was 086a898a, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 16, 1999 at 7:47:37 PM

Added copyright.

  • Property mode set to 100644
File size: 13.9 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1999.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  This is the chapter from the RTEMS ITRON User's Guide that
7@c  documents the services provided by the memory pool
8@c  manager.
9@c
10@c  $Id$
11@c
12
13@chapter Memory Pool Manager
14
15@section Introduction
16
17The
18memory pool manager is ...
19
20The services provided by the memory pool manager are:
21
22@itemize @bullet
23@item @code{cre_mpl} - Create Variable-Size Memorypool
24@item @code{del_mpl} - Delete Variable-Size Memorypool
25@item @code{get_blk} - Get Variable-Size Memory Block
26@item @code{pget_blk} - Poll and Get Variable-Size Memory Block
27@item @code{tget_blk} - Get Variable-Size Memory Block with Timeout
28@item @code{rel_blk} - Release Variable-Size Memory Block
29@item @code{ref_mpl} - Reference Variable-Size Memorypool Status
30@end itemize
31
32@section Background
33
34Memorypool management functions manage memorypools and allocate memory blocks.
35There are two types of memorypool: fixed-size memorypools and variable-size
36memorypools.  Both are considered separate objects and require different
37system calls for manipulation.  While the size of memory blocks allocated
38from fixed-size memorypools are all fixed, blocks of any size may be
39specified when allocating memory blocks from variable-size memorypools.
40
41@section Operations
42
43@section System Calls
44
45This section details the memory pool manager's services.
46A subsection is dedicated to each of this manager's services
47and describes the calling sequence, related constants, usage,
48and status codes.
49
50
51@c
52@c  cre_mpl
53@c
54
55@page
56@subsection cre_mpl - Create Variable-Size Memorypool
57
58@subheading CALLING SEQUENCE:
59
60@ifset is-C
61@example
62ER cre_mpl(
63  ID mplid,
64  T_CMPL *pk_cmpl
65);
66@end example
67@end ifset
68
69@ifset is-Ada
70@end ifset
71
72@subheading STATUS CODES:
73
74@code{E_OK} - Normal Completion
75
76@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for
77memorypool cannot be allocated)
78
79@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
80
81@code{E_RSATR} - Reserved attribute (mplatr was invalid or could not be used)
82
83@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists)
84
85@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
86a user task.  This is implementation dependent.)
87
88@code{E_PAR} - Parameter error (pk_cmpl is invalid or mplsz is negative or
89invalid)
90
91@subheading DESCRIPTION:
92
93The 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).
94
95@subheading NOTES:
96
97The 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.
98
99@c
100@c  del_mpl
101@c
102
103@page
104@subsection del_mpl - Delete Variable-Size Memorypool
105
106@subheading CALLING SEQUENCE:
107
108@ifset is-C
109@example
110ER del_mpl(
111  ID mplid
112);
113@end example
114@end ifset
115
116@ifset is-Ada
117@end ifset
118
119@subheading STATUS CODES:
120 
121@code{E_OK} - Normal Completion
122 
123@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
124 
125@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
126 
127@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
128a user task.  This is implementation dependent.)
129
130@subheading DESCRIPTION:
131
132This 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.
133
134@subheading NOTES:
135
136When 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.
137
138@c
139@c  get_blk
140@c
141
142@page
143@subsection get_blk - Get Variable-Size Memory Block
144
145@subheading CALLING SEQUENCE:
146
147@ifset is-C
148@example
149ER get_blk(
150  VP *p_blk,
151  ID mplid,
152  INT blksz
153);
154@end example
155@end ifset
156
157@ifset is-Ada
158@end ifset
159
160@subheading STATUS CODES:
161
162@code{E_OK} - Normal Completion
163 
164@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
165 
166@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
167 
168@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
169a user task.  This is implementation dependent.)
170 
171@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
172 
173@code{E_DLT} - The object being waited for was deleted (the specified memorypool
174was deleted while waiting)
175 
176@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
177waiting)
178 
179@code{E_TMOUT} - Polling failure or timeout
180
181@code{E_CTX} - Context error (issued from task-independent portions or a
182task in dispatch disabled state; implementation dependent for
183pget_blk and tget_blk(tmout=TMO_POL))
184
185@subheading DESCRIPTION:
186
187A 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.
188
189The 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.
190
191@subheading NOTES:
192
193Pget_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.
194
195@c
196@c  pget_blk
197@c
198
199@page
200@subsection pget_blk - Poll and Get Variable-Size Memory Block
201
202@subheading CALLING SEQUENCE:
203
204@ifset is-C
205@example
206ER ercd =pget_blk(
207  VP *p_blk,
208  ID mplid,
209  INT blksz
210);
211@end example
212@end ifset
213
214@ifset is-Ada
215@end ifset
216
217@subheading STATUS CODES:
218
219@code{E_OK} - Normal Completion
220 
221@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
222 
223@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
224 
225@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
226a user task.  This is implementation dependent.)
227 
228@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
229
230@code{E_DLT} - The object being waited for was deleted (the specified memorypool
231was deleted while waiting)
232 
233@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
234waiting)
235 
236@code{E_TMOUT} - Polling failure or timeout
237 
238@code{E_CTX} - Context error (issued from task-independent portions or a
239task in dispatch disabled state; implementation dependent for
240pget_blk and tget_blk(tmout=TMO_POL))
241
242@subheading DESCRIPTION:
243
244The 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.
245
246  - If there is enough free memory to get the memory block of specified size
247    immediately, processing is the same as get_blk: that is, the
248    requested memory is allocated and the system call completes normally.
249
250  - If there is not enough free memory, an E_TMOUT error is returned to
251    indicate polling failed and the system call finishes.  Unlike get_blk,
252    the issuing task does not wait in this case.  Also, the issuing task
253    does not get any memory.
254
255@subheading NOTES:
256
257NONE
258
259@c
260@c  tget_blk
261@c
262
263@page
264@subsection tget_blk - Get Variable-Size Memory Block with Timeout
265
266@subheading CALLING SEQUENCE:
267
268@ifset is-C
269@example
270ER ercd =tget_blk(
271  VP *p_blk,
272  ID mplid,
273  INT blksz,
274  TMO tmout
275);
276@end example
277@end ifset
278
279@ifset is-Ada
280@end ifset
281
282@subheading STATUS CODES:
283
284@code{E_OK} - Normal Completion
285 
286@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
287 
288@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
289 
290@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
291a user task.  This is implementation dependent.)
292 
293@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
294
295@code{E_DLT} - The object being waited for was deleted (the specified memorypool
296was deleted while waiting)
297 
298@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
299waiting)
300 
301@code{E_TMOUT} - Polling failure or timeout
302 
303@code{E_CTX} - Context error (issued from task-independent portions or a
304task in dispatch disabled state; implementation dependent for
305pget_blk and tget_blk(tmout=TMO_POL))
306
307
308@subheading DESCRIPTION:
309
310The 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).
311
312@subheading NOTES:
313
314NONE
315
316@c
317@c  rel_blk
318@c
319
320@page
321@subsection rel_blk - Release Variable-Size Memory Block
322
323@subheading CALLING SEQUENCE:
324
325@ifset is-C
326@example
327ER rel_blk(
328  ID mplid,
329  VP blk
330);
331@end example
332@end ifset
333
334@ifset is-Ada
335@end ifset
336
337@subheading STATUS CODES:
338 
339@code{E_OK} - Normal Completion
340 
341@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
342 
343@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
344 
345@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
346            a user task.  This is implementation dependent.)
347 
348@code{E_PAR} - Parameter error (blk is invalid or an attempt was made to return
349the memory block to the wrong memorypool)
350
351@subheading DESCRIPTION:
352
353This 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.
354
355@subheading NOTES:
356
357When 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.
358
359@c
360@c  ref_mpl
361@c
362
363@page
364@subsection ref_mpl - Reference Variable-Size Memorypool Status
365
366@subheading CALLING SEQUENCE:
367
368@ifset is-C
369@example
370ER ref_mpl(
371  T_RMPL *pk_rmpl,
372  ID mplid
373);
374@end example
375@end ifset
376
377@ifset is-Ada
378@end ifset
379
380@subheading STATUS CODES:
381 
382@code{E_OK} - Normal Completion
383 
384@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
385 
386@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
387 
388@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
389a 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.
390 
391@code{E_PAR} - Parameter error (the packet address for the return parameters
392could not be used)
393
394@subheading DESCRIPTION:
395
396This 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.
397
398@subheading NOTES:
399
400In 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.
401
Note: See TracBrowser for help on using the repository browser.