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