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

4.104.114.84.95
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: 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
177
178@c
179@c  pget_blf
180@c
181
182@page
183@subsection pget_blf - Poll and Get Fixed-Size Memory Block
184
185@subheading CALLING SEQUENCE:
186
187@ifset is-C
188@example
189ER ercd =pget_blf(
190  VP *p_blf,
191  ID mpfid
192);
193@end example
194@end ifset
195
196@ifset is-Ada
197@end ifset
198
199@subheading STATUS CODES:
200
201@code{E_OK} - Normal Completion
202 
203@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
204 
205@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
206 
207@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
208a user task.  This is implementation dependent.)
209 
210@code{E_PAR} - Parameter error (tmout is -2 or less)
211 
212@code{E_DLT} - The object being waited for was deleted (the specified memorypool
213was deleted while waiting)
214 
215@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
216waiting)
217 
218@code{E_TMOUT} - Polling failure or timeout exceeded
219 
220@code{E_CTX} - Context error (issued from task-independent portions or a
221task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
222
223@subheading DESCRIPTION:
224
225The 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.
226
227  - If there is a free memory block available, processing is the same as
228    get_blf: that is, the requested memory is allocated and the system call
229    completes normally.
230
231  - If there is no free memory block, an E_TMOUT error is returned to
232    indicate polling failed and the system call finishes.  Unlike get_blf,
233    the issuing task does not wait in this case.  Also, the issuing task
234    does not get any memory.
235
236@subheading NOTES:
237
238
239@c
240@c  tget_blf
241@c
242
243@page
244@subsection tget_blf - Get Fixed-Size Memory Block with Timeout
245
246@subheading CALLING SEQUENCE:
247
248@ifset is-C
249@example
250ER ercd =tget_blf(
251  VP *p_blf,
252  ID mpfid,
253  TMO tmout
254);
255@end example
256@end ifset
257
258@ifset is-Ada
259@end ifset
260
261@subheading STATUS CODES:
262
263@code{E_OK} - Normal Completion
264 
265@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
266 
267@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
268 
269@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
270a user task.  This is implementation dependent.)
271 
272@code{E_PAR} - Parameter error (tmout is -2 or less)
273 
274@code{E_DLT} - The object being waited for was deleted (the specified memorypool
275was deleted while waiting)
276 
277@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
278waiting)
279 
280@code{E_TMOUT} - Polling failure or timeout exceeded
281 
282@code{E_CTX} - Context error (issued from task-independent portions or a
283task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
284
285@subheading DESCRIPTION:
286
287The 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).
288
289@subheading NOTES:
290
291@c
292@c  rel_blf
293@c
294
295@page
296@subsection rel_blf - Release Fixed-Size Memory Block
297
298@subheading CALLING SEQUENCE:
299
300@ifset is-C
301@example
302ER rel_blf(
303  ID mpfid,
304  VP blf
305);
306@end example
307@end ifset
308
309@ifset is-Ada
310@end ifset
311
312@subheading STATUS CODES:
313
314@code{E_OK} - Normal Completion
315 
316@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
317 
318@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
319 
320@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
321a user task.  This is implementation dependent.)
322 
323@code{E_PAR} - Parameter error (blf is invalid or an attempt was made to return
324the memory block to the wrong memorypool)
325
326@subheading DESCRIPTION:
327
328This 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.
329
330@subheading NOTES:
331
332The 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.
333
334@c
335@c  ref_mpf
336@c
337
338@page
339@subsection ref_mpf - Reference Fixed-Size Memorypool Status
340
341@subheading CALLING SEQUENCE:
342
343@ifset is-C
344@example
345ER ref_mpf(
346  T_RMPF *pk_rmpf,
347  ID mpfid
348);
349@end example
350@end ifset
351
352@ifset is-Ada
353@end ifset
354
355@subheading STATUS CODES:
356
357@code{E_OK} - Normal Completion
358
359@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
360 
361@code{E_NOEXS} - Object does not exist \(the memorypool specified by mpfid does
362not exist.)
363                                                                                                                                                 
364@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
365a user task.  This is implementation dependent.)
366 
367@code{E_PAR} - Parameter error (the packet address for the return parameters
368could not be used)
369
370@subheading DESCRIPTION:
371
372This 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.
373
374@subheading NOTES:
375
376While 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.
377
378Depending on the implementation, additional information besides wtsk and frbcnt (such as memorypool attributes, mpfatr) may also be referred.
379
Note: See TracBrowser for help on using the repository browser.