source: rtems/doc/itron3.0/fixedblock.t @ a5f5acad

4.104.114.84.95
Last change on this file since a5f5acad was a5f5acad, checked in by Joel Sherrill <joel.sherrill@…>, on 11/10/99 at 13:38:34

Updated to include more documentation from CS595.

  • Property mode set to 100644
File size: 12.3 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 fixed block
4@c  manager.
5@c
6@c  $Id$
7@c
8
9@chapter Fixed Block Manager
10
11@section Introduction
12
13The fixed block manager provides functions for creating, deleting, getting, polling, getting with timeout, releasing, and referencing the fixed-sized memorypool. This manager is based on ITRON 3.0 standard.
14
15The services provided by the fixed block manager are:
16
17@itemize @bullet
18@item @code{cre_mpf} - Create Fixed-Size Memorypool
19@item @code{del_mpf} - Delete Fixed-Size Memorypool
20@item @code{get_blf} - Get Fixed-Size Memory Block
21@item @code{pget_blf} - Poll and Get Fixed-Size Memory Block
22@item @code{tget_blf} - Get Fixed-Size Memory Block with Timeout
23@item @code{rel_blf} - Release Fixed-Size Memory Block
24@item @code{ref_mpf} - Reference Fixed-Size Memorypool Status
25@end itemize
26
27@section Background
28
29@section Operations
30
31@section System Calls
32
33This section details the fixed block manager's services.
34A subsection is dedicated to each of this manager's services
35and describes the calling sequence, related constants, usage,
36and status codes.
37
38
39@c
40@c  cre_mpf
41@c
42
43@page
44@subsection cre_mpf - Create Fixed-Size Memorypool
45
46@subheading CALLING SEQUENCE:
47
48@ifset is-C
49@example
50ER cre_mpf(
51  ID mpfid,
52  T_CMPF *pk_cmpf
53);
54@end example
55@end ifset
56
57@ifset is-Ada
58@end ifset
59
60@subheading STATUS CODES:
61
62@code{E_OK} - Normal Completion
63 
64@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for
65memorypool cannot be allocated)
66 
67@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
68 
69@code{E_RSATR} - Reserved attribute (mpfatr was invalid or could not be used)
70 
71@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists)
72 
73@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
74a user task.  This is implementation dependent.)
75 
76@code{E_PAR} - Parameter error (pk_cmpf is invalid or mpfsz and/or blfsz is
77negative or invalid)
78
79@subheading DESCRIPTION:
80
81This system call creates a fixed-size memorypool having the ID number specified by mpfid.  Specifically, a memory area of a size based on values of mpfcnt and blfsz is reserved for use as a memorypool.  A control block for the memorypool being created is also allocated.  The get_blf system call specifying the memorypool created by this call can be issued to allocate memory blocks of the size given by blfsz (in bytes).
82
83@subheading NOTES:
84
85The memory area required for creating memorypools and for allocating control blocks for each object is allocated while system initialization. Associated parameters are therefore specified at system configuration.
86
87@c
88@c  del_mpf
89@c
90
91@page
92@subsection del_mpf - Delete Fixed-Size Memorypool
93
94@subheading CALLING SEQUENCE:
95
96@ifset is-C
97@example
98ER del_mpf(
99  ID mpfid
100);
101@end example
102@end ifset
103
104@ifset is-Ada
105@end ifset
106
107@subheading STATUS CODES:
108
109@code{E_OK} - Normal Completion
110
111@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
112
113@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
114 
115@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from a user task.  This is implementation dependent.)
116
117@subheading DESCRIPTION:
118
119This system call deletes the fixed-size memorypool specified by mpfid.  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.  This system call will complete normally even if there are tasks waiting to get memory blocks from the memorypool.  In that case, an E_DLT error will be returned to each waiting task.
120
121@subheading NOTES:
122
123When 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.
124
125
126@c
127@c  get_blf
128@c
129
130@page
131@subsection get_blf - Get Fixed-Size Memory Block
132
133@subheading CALLING SEQUENCE:
134
135@ifset is-C
136@example
137ER get_blf(
138  VP *p_blf,
139  ID mpfid
140);
141@end example
142@end ifset
143
144@ifset is-Ada
145@end ifset
146
147@subheading STATUS CODES:
148 
149@code{E_OK} - Normal Completion
150
151@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
152 
153@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
154 
155@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
156a user task.  This is implementation dependent.)
157 
158@code{E_PAR} - Parameter error (tmout is -2 or less)
159 
160@code{E_DLT} - The object being waited for was deleted (the specified memorypool
161was deleted while waiting)
162 
163@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
164waiting)
165 
166@code{E_TMOUT} - Polling failure or timeout exceeded
167 
168@code{E_CTX} - Context error (issued from task-independent portions or a
169task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
170
171@subheading DESCRIPTION:
172
173A memory block is allocated from the fixed-size memorypool specified by mpfid.  The start address of the memory block allocated is returned to blf.  The size of the memory block allocated is specified by the blfsz parameter when the fixed-size memorypool was created.  The allocated memory block is not cleared to zero.  The contents of the allocated memory block are undefined.  If the memory block cannot be obtained from the specified memorypool when get_blf is issued, the task issuing get_blf will be placed on the memory allocation queue of the specified memorypool, and wait until it can get the memory it requires.  If the object being waited for is deleted (the specified memorypool is deleted while waiting), an E_DLT error will be returned.
174
175@subheading NOTES:
176
177NONE
178
179
180@c
181@c  pget_blf
182@c
183
184@page
185@subsection pget_blf - Poll and Get Fixed-Size Memory Block
186
187@subheading CALLING SEQUENCE:
188
189@ifset is-C
190@example
191ER ercd =pget_blf(
192  VP *p_blf,
193  ID mpfid
194);
195@end example
196@end ifset
197
198@ifset is-Ada
199@end ifset
200
201@subheading STATUS CODES:
202
203@code{E_OK} - Normal Completion
204 
205@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
206 
207@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
208 
209@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
210a user task.  This is implementation dependent.)
211 
212@code{E_PAR} - Parameter error (tmout is -2 or less)
213 
214@code{E_DLT} - The object being waited for was deleted (the specified memorypool
215was deleted while waiting)
216 
217@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
218waiting)
219 
220@code{E_TMOUT} - Polling failure or timeout exceeded
221 
222@code{E_CTX} - Context error (issued from task-independent portions or a
223task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
224
225@subheading DESCRIPTION:
226
227The pget_blf system call has the same function as get_blf except for the waiting feature.  Pget_blf polls whether or not the task should wait if get_blf is executed.  The meaning of parameters to pget_blf are the same with get_blf.  The specific operations by pget_blf are as follows.
228
229  - If there is a free memory block available, processing is the same as
230    get_blf: that is, the requested memory is allocated and the system call
231    completes normally.
232
233  - If there is no free memory block, an E_TMOUT error is returned to
234    indicate polling failed and the system call finishes.  Unlike get_blf,
235    the issuing task does not wait in this case.  Also, the issuing task
236    does not get any memory.
237
238@subheading NOTES:
239
240NONE
241
242
243@c
244@c  tget_blf
245@c
246
247@page
248@subsection tget_blf - Get Fixed-Size Memory Block with Timeout
249
250@subheading CALLING SEQUENCE:
251
252@ifset is-C
253@example
254ER ercd =tget_blf(
255  VP *p_blf,
256  ID mpfid,
257  TMO tmout
258);
259@end example
260@end ifset
261
262@ifset is-Ada
263@end ifset
264
265@subheading STATUS CODES:
266
267@code{E_OK} - Normal Completion
268 
269@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
270 
271@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
272 
273@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
274a user task.  This is implementation dependent.)
275 
276@code{E_PAR} - Parameter error (tmout is -2 or less)
277 
278@code{E_DLT} - The object being waited for was deleted (the specified memorypool
279was deleted while waiting)
280 
281@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
282waiting)
283 
284@code{E_TMOUT} - Polling failure or timeout exceeded
285 
286@code{E_CTX} - Context error (issued from task-independent portions or a
287task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
288
289@subheading DESCRIPTION:
290
291The tget_blf system call has the same function as get_blf 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 free memory becoming available).
292
293@subheading NOTES:
294
295NONE
296
297@c
298@c  rel_blf
299@c
300
301@page
302@subsection rel_blf - Release Fixed-Size Memory Block
303
304@subheading CALLING SEQUENCE:
305
306@ifset is-C
307@example
308ER rel_blf(
309  ID mpfid,
310  VP blf
311);
312@end example
313@end ifset
314
315@ifset is-Ada
316@end ifset
317
318@subheading STATUS CODES:
319
320@code{E_OK} - Normal Completion
321 
322@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
323 
324@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
325 
326@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
327a user task.  This is implementation dependent.)
328 
329@code{E_PAR} - Parameter error (blf is invalid or an attempt was made to return
330the memory block to the wrong memorypool)
331
332@subheading DESCRIPTION:
333
334This system call releases the memory block specified by blf and returns it to the fixed-size memorypool specified by mpfid.  Executing rel_blf allows memory to be allocated to the next task waiting for memory allocation from the memorypool given by mpfid, thus releasing that task from its WAIT state.
335
336@subheading NOTES:
337
338The fixed-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.
339
340@c
341@c  ref_mpf
342@c
343
344@page
345@subsection ref_mpf - Reference Fixed-Size Memorypool Status
346
347@subheading CALLING SEQUENCE:
348
349@ifset is-C
350@example
351ER ref_mpf(
352  T_RMPF *pk_rmpf,
353  ID mpfid
354);
355@end example
356@end ifset
357
358@ifset is-Ada
359@end ifset
360
361@subheading STATUS CODES:
362
363@code{E_OK} - Normal Completion
364
365@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
366 
367@code{E_NOEXS} - Object does not exist \(the memorypool specified by mpfid does
368not exist.)
369                                                                                                                                                 
370@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
371a user task.  This is implementation dependent.)
372 
373@code{E_PAR} - Parameter error (the packet address for the return parameters
374could not be used)
375
376@subheading DESCRIPTION:
377
378This system call refers to the state of the fixed-size memorypool specified by mpfid, and returns the current number of free blocks (frbcnt), 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 fixed-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.
379
380@subheading NOTES:
381
382While the frsz return parameter of ref_mpl returns the total size of free memory, the frbcnt return parameter of ref_mpf returns the number of free blocks.
383
384Depending on the implementation, additional information besides wtsk and frbcnt (such as memorypool attributes, mpfatr) may also be referred.
385
Note: See TracBrowser for help on using the repository browser.