Changeset 1baa059 in rtems


Ignore:
Timestamp:
11/09/99 16:40:44 (24 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
bd0b378
Parents:
aebc7aa5
Message:

Converted from DOS to UNIX filemode.

Location:
doc/itron3.0
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • doc/itron3.0/fixedblock.t

    raebc7aa5 r1baa059  
    11@c
    2 
    32@c  This is the chapter from the RTEMS ITRON User's Guide that
    4 
    53@c  documents the services provided by the fixed block
    6 
    74@c  manager.
    8 
    9 @c
    10 
     5@c
    116@c  $Id$
    12 
    13 @c
    14 
    15 
     7@c
    168
    179@chapter Fixed Block Manager
    1810
    19 
    20 
    2111@section Introduction
    2212
    23 
    24 
    2513The 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.
    2614
    27 
    28 
    2915The services provided by the fixed block manager are:
    3016
    31 
    32 
    3317@itemize @bullet
    34 
    3518@item @code{cre_mpf} - Create Fixed-Size Memorypool
    36 
    3719@item @code{del_mpf} - Delete Fixed-Size Memorypool
    38 
    3920@item @code{get_blf} - Get Fixed-Size Memory Block
    40 
    4121@item @code{pget_blf} - Poll and Get Fixed-Size Memory Block
    42 
    4322@item @code{tget_blf} - Get Fixed-Size Memory Block with Timeout
    44 
    4523@item @code{rel_blf} - Release Fixed-Size Memory Block
    46 
    4724@item @code{ref_mpf} - Reference Fixed-Size Memorypool Status
    48 
    4925@end itemize
    5026
    51 
    52 
    5327@section Background
    5428
    55 
    56 
    5729@section Operations
    5830
    59 
    60 
    6131@section System Calls
    6232
    63 
    64 
    6533This section details the fixed block manager's services.
    66 
    6734A subsection is dedicated to each of this manager's services
    68 
    6935and describes the calling sequence, related constants, usage,
    70 
    7136and status codes.
    7237
    7338
    74 
    75 
    76 
    77 @c
    78 
     39@c
    7940@c  cre_mpf
    80 
    81 @c
    82 
    83 
    84 
    85 @page
    86 
     41@c
     42
     43@page
    8744@subsection cre_mpf - Create Fixed-Size Memorypool
    8845
    89 
    90 
    91 @subheading CALLING SEQUENCE:
    92 
    93 
    94 
    95 @ifset is-C
    96 
    97 @example
    98 
     46@subheading CALLING SEQUENCE:
     47
     48@ifset is-C
     49@example
    9950ER cre_mpf(
    100 
    10151  ID mpfid,
    102 
    10352  T_CMPF *pk_cmpf
    104 
    105 );
    106 
    107 @end example
    108 
    109 @end ifset
    110 
    111 
    112 
    113 @ifset is-Ada
    114 
    115 @end ifset
    116 
    117 
    118 
    119 @subheading STATUS CODES:
    120 
    121 
    122 
    123 @code{E_OK} - Normal Completion
    124 
    125  
    126 
     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 
    12764@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for
    128 
    12965memorypool cannot be allocated)
    130 
    131  
    132 
    133 @code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
    134 
    135  
    136 
     66 
     67@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
     68 
    13769@code{E_RSATR} - Reserved attribute (mpfatr was invalid or could not be used)
    138 
    139  
    140 
     70 
    14171@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists)
    142 
    143  
    144 
    145 @code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
    146 
    147 a user task.  This is implementation dependent.)
    148 
    149  
    150 
     72 
     73@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
     74a user task.  This is implementation dependent.)
     75 
    15176@code{E_PAR} - Parameter error (pk_cmpf is invalid or mpfsz and/or blfsz is
    152 
    15377negative or invalid)
    15478
    155 
    156 
    157 @subheading DESCRIPTION:
    158 
    159 
     79@subheading DESCRIPTION:
    16080
    16181This 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).
    16282
    163 
    164 
    165 @subheading NOTES:
    166 
    167 
     83@subheading NOTES:
    16884
    16985The 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.
    17086
    171 
    172 
    173 @c
    174 
     87@c
    17588@c  del_mpf
    176 
    177 @c
    178 
    179 
    180 
    181 @page
    182 
     89@c
     90
     91@page
    18392@subsection del_mpf - Delete Fixed-Size Memorypool
    18493
    185 
    186 
    187 @subheading CALLING SEQUENCE:
    188 
    189 
    190 
    191 @ifset is-C
    192 
    193 @example
    194 
     94@subheading CALLING SEQUENCE:
     95
     96@ifset is-C
     97@example
    19598ER del_mpf(
    196 
    19799  ID mpfid
    198 
    199 );
    200 
    201 @end example
    202 
    203 @end ifset
    204 
    205 
    206 
    207 @ifset is-Ada
    208 
    209 @end ifset
    210 
    211 
    212 
    213 @subheading STATUS CODES:
    214 
    215 
    216 
    217 @code{E_OK} - Normal Completion
    218 
    219 
    220 
    221 @code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
    222 
    223 
    224 
    225 @code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
    226 
    227  
    228 
     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 
    229115@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from a user task.  This is implementation dependent.)
    230116
    231 
    232 
    233 @subheading DESCRIPTION:
    234 
    235 
     117@subheading DESCRIPTION:
    236118
    237119This 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.
    238120
    239 
    240 
    241 @subheading NOTES:
    242 
    243 
     121@subheading NOTES:
    244122
    245123When 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.
    246124
    247125
    248 
    249 
    250 
    251 @c
    252 
     126@c
    253127@c  get_blf
    254 
    255 @c
    256 
    257 
    258 
    259 @page
    260 
     128@c
     129
     130@page
    261131@subsection get_blf - Get Fixed-Size Memory Block
    262132
    263 
    264 
    265 @subheading CALLING SEQUENCE:
    266 
    267 
    268 
    269 @ifset is-C
    270 
    271 @example
    272 
     133@subheading CALLING SEQUENCE:
     134
     135@ifset is-C
     136@example
    273137ER get_blf(
    274 
    275138  VP *p_blf,
    276 
    277139  ID mpfid
    278 
    279 );
    280 
    281 @end example
    282 
    283 @end ifset
    284 
    285 
    286 
    287 @ifset is-Ada
    288 
    289 @end ifset
    290 
    291 
    292 
    293 @subheading STATUS CODES:
    294 
     140);
     141@end example
     142@end ifset
     143
     144@ifset is-Ada
     145@end ifset
     146
     147@subheading STATUS CODES:
    295148 
    296 
    297 @code{E_OK} - Normal Completion
    298 
    299 
    300 
    301 @code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
    302 
    303  
    304 
    305 @code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
    306 
    307  
    308 
    309 @code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
    310 
    311 a user task.  This is implementation dependent.)
    312 
    313  
    314 
     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 
    315158@code{E_PAR} - Parameter error (tmout is -2 or less)
    316 
    317  
    318 
     159 
    319160@code{E_DLT} - The object being waited for was deleted (the specified memorypool
    320 
    321161was deleted while waiting)
    322 
    323  
    324 
     162 
    325163@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
    326 
    327164waiting)
    328 
    329  
    330 
     165 
    331166@code{E_TMOUT} - Polling failure or timeout exceeded
    332 
    333  
    334 
     167 
    335168@code{E_CTX} - Context error (issued from task-independent portions or a
    336 
    337169task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
    338170
    339 
    340 
    341 @subheading DESCRIPTION:
    342 
    343 
     171@subheading DESCRIPTION:
    344172
    345173A 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.
    346174
    347 
    348 
    349 @subheading NOTES:
    350 
    351 
    352 
    353 
    354 
    355 @c
    356 
     175@subheading NOTES:
     176
     177
     178@c
    357179@c  pget_blf
    358 
    359 @c
    360 
    361 
    362 
    363 @page
    364 
     180@c
     181
     182@page
    365183@subsection pget_blf - Poll and Get Fixed-Size Memory Block
    366184
    367 
    368 
    369 @subheading CALLING SEQUENCE:
    370 
    371 
    372 
    373 @ifset is-C
    374 
    375 @example
    376 
     185@subheading CALLING SEQUENCE:
     186
     187@ifset is-C
     188@example
    377189ER ercd =pget_blf(
    378 
    379190  VP *p_blf,
    380 
    381191  ID mpfid
    382 
    383 );
    384 
    385 @end example
    386 
    387 @end ifset
    388 
    389 
    390 
    391 @ifset is-Ada
    392 
    393 @end ifset
    394 
    395 
    396 
    397 @subheading STATUS CODES:
    398 
    399 
    400 
    401 @code{E_OK} - Normal Completion
    402 
    403  
    404 
    405 @code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
    406 
    407  
    408 
    409 @code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
    410 
    411  
    412 
    413 @code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
    414 
    415 a user task.  This is implementation dependent.)
    416 
    417  
    418 
     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 
    419210@code{E_PAR} - Parameter error (tmout is -2 or less)
    420 
    421  
    422 
     211 
    423212@code{E_DLT} - The object being waited for was deleted (the specified memorypool
    424 
    425213was deleted while waiting)
    426 
    427  
    428 
     214 
    429215@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
    430 
    431216waiting)
    432 
    433  
    434 
     217 
    435218@code{E_TMOUT} - Polling failure or timeout exceeded
    436 
    437  
    438 
     219 
    439220@code{E_CTX} - Context error (issued from task-independent portions or a
    440 
    441221task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
    442222
    443 
    444 
    445 @subheading DESCRIPTION:
    446 
    447 
     223@subheading DESCRIPTION:
    448224
    449225The 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.
    450226
    451 
    452 
    453227  - If there is a free memory block available, processing is the same as
    454 
    455228    get_blf: that is, the requested memory is allocated and the system call
    456 
    457229    completes normally.
    458230
    459 
    460 
    461231  - If there is no free memory block, an E_TMOUT error is returned to
    462 
    463232    indicate polling failed and the system call finishes.  Unlike get_blf,
    464 
    465233    the issuing task does not wait in this case.  Also, the issuing task
    466 
    467234    does not get any memory.
    468235
    469 
    470 
    471 @subheading NOTES:
    472 
    473 
    474 
    475 
    476 
    477 @c
    478 
     236@subheading NOTES:
     237
     238
     239@c
    479240@c  tget_blf
    480 
    481 @c
    482 
    483 
    484 
    485 @page
    486 
     241@c
     242
     243@page
    487244@subsection tget_blf - Get Fixed-Size Memory Block with Timeout
    488245
    489 
    490 
    491 @subheading CALLING SEQUENCE:
    492 
    493 
    494 
    495 @ifset is-C
    496 
    497 @example
    498 
     246@subheading CALLING SEQUENCE:
     247
     248@ifset is-C
     249@example
    499250ER ercd =tget_blf(
    500 
    501251  VP *p_blf,
    502 
    503252  ID mpfid,
    504 
    505253  TMO tmout
    506 
    507 );
    508 
    509 @end example
    510 
    511 @end ifset
    512 
    513 
    514 
    515 @ifset is-Ada
    516 
    517 @end ifset
    518 
    519 
    520 
    521 @subheading STATUS CODES:
    522 
    523 
    524 
    525 @code{E_OK} - Normal Completion
    526 
    527  
    528 
    529 @code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
    530 
    531  
    532 
    533 @code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
    534 
    535  
    536 
    537 @code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
    538 
    539 a user task.  This is implementation dependent.)
    540 
    541  
    542 
     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 
    543272@code{E_PAR} - Parameter error (tmout is -2 or less)
    544 
    545  
    546 
     273 
    547274@code{E_DLT} - The object being waited for was deleted (the specified memorypool
    548 
    549275was deleted while waiting)
    550 
    551  
    552 
     276 
    553277@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
    554 
    555278waiting)
    556 
    557  
    558 
     279 
    559280@code{E_TMOUT} - Polling failure or timeout exceeded
    560 
    561  
    562 
     281 
    563282@code{E_CTX} - Context error (issued from task-independent portions or a
    564 
    565283task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
    566284
    567 
    568 
    569 @subheading DESCRIPTION:
    570 
    571 
     285@subheading DESCRIPTION:
    572286
    573287The 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).
    574288
    575 
    576 
    577 @subheading NOTES:
    578 
    579 
    580 
    581 @c
    582 
     289@subheading NOTES:
     290
     291@c
    583292@c  rel_blf
    584 
    585 @c
    586 
    587 
    588 
    589 @page
    590 
     293@c
     294
     295@page
    591296@subsection rel_blf - Release Fixed-Size Memory Block
    592297
    593 
    594 
    595 @subheading CALLING SEQUENCE:
    596 
    597 
    598 
    599 @ifset is-C
    600 
    601 @example
    602 
     298@subheading CALLING SEQUENCE:
     299
     300@ifset is-C
     301@example
    603302ER rel_blf(
    604 
    605303  ID mpfid,
    606 
    607304  VP blf
    608 
    609 );
    610 
    611 @end example
    612 
    613 @end ifset
    614 
    615 
    616 
    617 @ifset is-Ada
    618 
    619 @end ifset
    620 
    621 
    622 
    623 @subheading STATUS CODES:
    624 
    625 
    626 
    627 @code{E_OK} - Normal Completion
    628 
    629  
    630 
    631 @code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
    632 
    633  
    634 
    635 @code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
    636 
    637  
    638 
    639 @code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
    640 
    641 a user task.  This is implementation dependent.)
    642 
    643  
    644 
     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 
    645323@code{E_PAR} - Parameter error (blf is invalid or an attempt was made to return
    646 
    647324the memory block to the wrong memorypool)
    648325
    649 
    650 
    651 @subheading DESCRIPTION:
    652 
    653 
     326@subheading DESCRIPTION:
    654327
    655328This 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.
    656329
    657 
    658 
    659 @subheading NOTES:
    660 
    661 
     330@subheading NOTES:
    662331
    663332The 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.
    664333
    665 
    666 
    667 @c
    668 
     334@c
    669335@c  ref_mpf
    670 
    671 @c
    672 
    673 
    674 
    675 @page
    676 
     336@c
     337
     338@page
    677339@subsection ref_mpf - Reference Fixed-Size Memorypool Status
    678340
    679 
    680 
    681 @subheading CALLING SEQUENCE:
    682 
    683 
    684 
    685 @ifset is-C
    686 
    687 @example
    688 
     341@subheading CALLING SEQUENCE:
     342
     343@ifset is-C
     344@example
    689345ER ref_mpf(
    690 
    691346  T_RMPF *pk_rmpf,
    692 
    693347  ID mpfid
    694 
    695 );
    696 
    697 @end example
    698 
    699 @end ifset
    700 
    701 
    702 
    703 @ifset is-Ada
    704 
    705 @end ifset
    706 
    707 
    708 
    709 @subheading STATUS CODES:
    710 
    711 
    712 
    713 @code{E_OK} - Normal Completion
    714 
    715 
    716 
    717 @code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
    718 
     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)
    719360 
    720 
    721361@code{E_NOEXS} - Object does not exist \(the memorypool specified by mpfid does
    722 
    723362not exist.)
    724 
    725363                                                                                                                                                 
    726 
    727 @code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
    728 
    729 a user task.  This is implementation dependent.)
    730 
     364@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
     365a user task.  This is implementation dependent.)
    731366 
    732 
    733367@code{E_PAR} - Parameter error (the packet address for the return parameters
    734 
    735368could not be used)
    736369
    737 
    738 
    739 @subheading DESCRIPTION:
    740 
    741 
     370@subheading DESCRIPTION:
    742371
    743372This 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.
    744373
    745 
    746 
    747 @subheading NOTES:
    748 
    749 
     374@subheading NOTES:
    750375
    751376While 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.
    752377
    753 
    754 
    755378Depending on the implementation, additional information besides wtsk and frbcnt (such as memorypool attributes, mpfatr) may also be referred.
    756379
    757 
    758 
  • doc/itron3.0/memorypool.t

    raebc7aa5 r1baa059  
    11@c
    2 
    32@c  This is the chapter from the RTEMS ITRON User's Guide that
    4 
    53@c  documents the services provided by the memory pool
    6 
    74@c  manager.
    8 
    9 @c
    10 
     5@c
    116@c  $Id$
    12 
    13 @c
    14 
    15 
     7@c
    168
    179@chapter Memory Pool Manager
    1810
    19 
    20 
    2111@section Introduction
    2212
    23 
    24 
    2513The
    26 
    2714memory pool manager is ...
    2815
    29 
    30 
    3116The services provided by the memory pool manager are:
    3217
    33 
    34 
    3518@itemize @bullet
    36 
    3719@item @code{cre_mpl} - Create Variable-Size Memorypool
    38 
    3920@item @code{del_mpl} - Delete Variable-Size Memorypool
    40 
    4121@item @code{get_blk} - Get Variable-Size Memory Block
    42 
    4322@item @code{pget_blk} - Poll and Get Variable-Size Memory Block
    44 
    4523@item @code{tget_blk} - Get Variable-Size Memory Block with Timeout
    46 
    4724@item @code{rel_blk} - Release Variable-Size Memory Block
    48 
    4925@item @code{ref_mpl} - Reference Variable-Size Memorypool Status
    50 
    5126@end itemize
    5227
    53 
    54 
    5528@section Background
    5629
    57 
    58 
    5930Memorypool management functions manage memorypools and allocate memory blocks.
    60 
    6131There are two types of memorypool: fixed-size memorypools and variable-size
    62 
    6332memorypools.  Both are considered separate objects and require different
    64 
    6533system calls for manipulation.  While the size of memory blocks allocated
    66 
    6734from fixed-size memorypools are all fixed, blocks of any size may be
    68 
    6935specified when allocating memory blocks from variable-size memorypools.
    7036
    71 
    72 
    7337@section Operations
    7438
    75 
    76 
    7739@section System Calls
    7840
    79 
    80 
    8141This section details the memory pool manager's services.
    82 
    8342A subsection is dedicated to each of this manager's services
    84 
    8543and describes the calling sequence, related constants, usage,
    86 
    8744and status codes.
    8845
    8946
    90 
    91 
    92 
    93 @c
    94 
     47@c
    9548@c  cre_mpl
    96 
    97 @c
    98 
    99 
    100 
    101 @page
    102 
     49@c
     50
     51@page
    10352@subsection cre_mpl - Create Variable-Size Memorypool
    10453
    105 
    106 
    107 @subheading CALLING SEQUENCE:
    108 
    109 
    110 
    111 @ifset is-C
    112 
    113 @example
    114 
     54@subheading CALLING SEQUENCE:
     55
     56@ifset is-C
     57@example
    11558ER cre_mpl(
    116 
    117   ID mplid,
    118 
     59  ID mplid,
    11960  T_CMPL *pk_cmpl
    120 
    121 );
    122 
    123 @end example
    124 
    125 @end ifset
    126 
    127 
    128 
    129 @ifset is-Ada
    130 
    131 @end ifset
    132 
    133 
    134 
    135 @subheading STATUS CODES:
    136 
    137 
    138 
    139 @code{E_OK} - Normal Completion
    140 
    141 
     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
    14271
    14372@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for
    144 
    14573memorypool cannot be allocated)
    14674
    147 
    148 
    149 @code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
    150 
    151 
     75@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
    15276
    15377@code{E_RSATR} - Reserved attribute (mplatr was invalid or could not be used)
    15478
    155 
    156 
    15779@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists)
    15880
    159 
    160 
    161 @code{E_OACV} - Object access violation (A mplid less than -4 was specified from
    162 
    163 a user task.  This is implementation dependent.)
    164 
    165 
     81@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
     82a user task.  This is implementation dependent.)
    16683
    16784@code{E_PAR} - Parameter error (pk_cmpl is invalid or mplsz is negative or
    168 
    16985invalid)
    17086
    171 
    172 
    173 @subheading DESCRIPTION:
    174 
    175 
     87@subheading DESCRIPTION:
    17688
    17789The 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).
    17890
    179 
    180 
    181 @subheading NOTES:
    182 
    183 
     91@subheading NOTES:
    18492
    18593The 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.
    18694
    187 
    188 
    189 @c
    190 
     95@c
    19196@c  del_mpl
    192 
    193 @c
    194 
    195 
    196 
    197 @page
    198 
     97@c
     98
     99@page
    199100@subsection del_mpl - Delete Variable-Size Memorypool
    200101
    201 
    202 
    203 @subheading CALLING SEQUENCE:
    204 
    205 
    206 
    207 @ifset is-C
    208 
    209 @example
    210 
     102@subheading CALLING SEQUENCE:
     103
     104@ifset is-C
     105@example
    211106ER del_mpl(
    212 
    213107  ID mplid
    214 
    215 );
    216 
    217 @end example
    218 
    219 @end ifset
    220 
    221 
    222 
    223 @ifset is-Ada
    224 
    225 @end ifset
    226 
    227 
    228 
    229 @subheading STATUS CODES:
    230 
     108);
     109@end example
     110@end ifset
     111
     112@ifset is-Ada
     113@end ifset
     114
     115@subheading STATUS CODES:
    231116 
    232 
    233 @code{E_OK} - Normal Completion
    234 
    235  
    236 
    237 @code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
    238 
    239  
    240 
    241 @code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
    242 
    243  
    244 
    245 @code{E_OACV} - Object access violation (A mplid less than -4 was specified from
    246 
    247 a user task.  This is implementation dependent.)
    248 
    249 
    250 
    251 @subheading DESCRIPTION:
    252 
    253 
     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:
    254127
    255128This 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.
    256129
    257 
    258 
    259 @subheading NOTES:
    260 
    261 
     130@subheading NOTES:
    262131
    263132When 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.
    264133
    265 
    266 
    267 @c
    268 
     134@c
    269135@c  get_blk
    270 
    271 @c
    272 
    273 
    274 
    275 @page
    276 
     136@c
     137
     138@page
    277139@subsection get_blk - Get Variable-Size Memory Block
    278140
    279 
    280 
    281 @subheading CALLING SEQUENCE:
    282 
    283 
    284 
    285 @ifset is-C
    286 
    287 @example
    288 
     141@subheading CALLING SEQUENCE:
     142
     143@ifset is-C
     144@example
    289145ER get_blk(
    290 
    291146  VP *p_blk,
    292 
    293   ID mplid,
    294 
     147  ID mplid,
    295148  INT blksz
    296 
    297 );
    298 
    299 @end example
    300 
    301 @end ifset
    302 
    303 
    304 
    305 @ifset is-Ada
    306 
    307 @end ifset
    308 
    309 
    310 
    311 @subheading STATUS CODES:
    312 
    313 
    314 
    315 @code{E_OK} - Normal Completion
    316 
    317  
    318 
    319 @code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
    320 
    321  
    322 
    323 @code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
    324 
    325  
    326 
    327 @code{E_OACV} - Object access violation (A mplid less than -4 was specified from
    328 
    329 a user task.  This is implementation dependent.)
    330 
    331  
    332 
     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 
    333167@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
    334 
    335  
    336 
     168 
    337169@code{E_DLT} - The object being waited for was deleted (the specified memorypool
    338 
    339170was deleted while waiting)
    340 
    341  
    342 
     171 
    343172@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
    344 
    345173waiting)
    346 
    347  
    348 
     174 
    349175@code{E_TMOUT} - Polling failure or timeout
    350176
    351 
    352 
    353177@code{E_CTX} - Context error (issued from task-independent portions or a
    354 
    355178task in dispatch disabled state; implementation dependent for
    356 
    357179pget_blk and tget_blk(tmout=TMO_POL))
    358180
    359 
    360 
    361 @subheading DESCRIPTION:
    362 
    363 
     181@subheading DESCRIPTION:
    364182
    365183A 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.
    366184
    367 
    368 
    369185The 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.
    370186
    371 
    372 
    373 @subheading NOTES:
    374 
    375 
     187@subheading NOTES:
    376188
    377189Pget_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.
    378190
    379 
    380 
    381 @c
    382 
     191@c
    383192@c  pget_blk
    384 
    385 @c
    386 
    387 
    388 
    389 @page
    390 
     193@c
     194
     195@page
    391196@subsection pget_blk - Poll and Get Variable-Size Memory Block
    392197
    393 
    394 
    395 @subheading CALLING SEQUENCE:
    396 
    397 
    398 
    399 @ifset is-C
    400 
    401 @example
    402 
     198@subheading CALLING SEQUENCE:
     199
     200@ifset is-C
     201@example
    403202ER ercd =pget_blk(
    404 
    405203  VP *p_blk,
    406 
    407   ID mplid,
    408 
     204  ID mplid,
    409205  INT blksz
    410 
    411 );
    412 
    413 @end example
    414 
    415 @end ifset
    416 
    417 
    418 
    419 @ifset is-Ada
    420 
    421 @end ifset
    422 
    423 
    424 
    425 @subheading STATUS CODES:
    426 
    427 
    428 
    429 @code{E_OK} - Normal Completion
    430 
    431  
    432 
    433 @code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
    434 
    435  
    436 
    437 @code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
    438 
    439  
    440 
    441 @code{E_OACV} - Object access violation (A mplid less than -4 was specified from
    442 
    443 a user task.  This is implementation dependent.)
    444 
    445  
    446 
     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 
    447224@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
    448225
    449 
    450 
    451226@code{E_DLT} - The object being waited for was deleted (the specified memorypool
    452 
    453227was deleted while waiting)
    454 
    455  
    456 
     228 
    457229@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
    458 
    459230waiting)
    460 
    461  
    462 
     231 
    463232@code{E_TMOUT} - Polling failure or timeout
    464 
    465  
    466 
     233 
    467234@code{E_CTX} - Context error (issued from task-independent portions or a
    468 
    469235task in dispatch disabled state; implementation dependent for
    470 
    471236pget_blk and tget_blk(tmout=TMO_POL))
    472237
    473 
    474 
    475 @subheading DESCRIPTION:
    476 
    477 
     238@subheading DESCRIPTION:
    478239
    479240The 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.
    480241
    481 
    482 
    483242  - If there is enough free memory to get the memory block of specified size
    484 
    485243    immediately, processing is the same as get_blk: that is, the
    486 
    487244    requested memory is allocated and the system call completes normally.
    488245
    489 
    490 
    491246  - If there is not enough free memory, an E_TMOUT error is returned to
    492 
    493247    indicate polling failed and the system call finishes.  Unlike get_blk,
    494 
    495248    the issuing task does not wait in this case.  Also, the issuing task
    496 
    497249    does not get any memory.
    498250
    499 
    500 
    501 @subheading NOTES:
    502 
    503 
    504 
    505 @c
    506 
     251@subheading NOTES:
     252
     253@c
    507254@c  tget_blk
    508 
    509 @c
    510 
    511 
    512 
    513 @page
    514 
     255@c
     256
     257@page
    515258@subsection tget_blk - Get Variable-Size Memory Block with Timeout
    516259
    517 
    518 
    519 @subheading CALLING SEQUENCE:
    520 
    521 
    522 
    523 @ifset is-C
    524 
    525 @example
    526 
     260@subheading CALLING SEQUENCE:
     261
     262@ifset is-C
     263@example
    527264ER ercd =tget_blk(
    528 
    529265  VP *p_blk,
    530 
    531   ID mplid,
    532 
     266  ID mplid,
    533267  INT blksz,
    534 
    535268  TMO tmout
    536 
    537 );
    538 
    539 @end example
    540 
    541 @end ifset
    542 
    543 
    544 
    545 @ifset is-Ada
    546 
    547 @end ifset
    548 
    549 
    550 
    551 @subheading STATUS CODES:
    552 
    553 
    554 
    555 @code{E_OK} - Normal Completion
    556 
    557  
    558 
    559 @code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
    560 
    561  
    562 
    563 @code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
    564 
    565  
    566 
    567 @code{E_OACV} - Object access violation (A mplid less than -4 was specified from
    568 
    569 a user task.  This is implementation dependent.)
    570 
    571  
    572 
     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 
    573287@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
    574288
    575 
    576 
    577289@code{E_DLT} - The object being waited for was deleted (the specified memorypool
    578 
    579290was deleted while waiting)
    580 
    581  
    582 
     291 
    583292@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
    584 
    585293waiting)
    586 
    587  
    588 
     294 
    589295@code{E_TMOUT} - Polling failure or timeout
    590 
    591  
    592 
     296 
    593297@code{E_CTX} - Context error (issued from task-independent portions or a
    594 
    595298task in dispatch disabled state; implementation dependent for
    596 
    597299pget_blk and tget_blk(tmout=TMO_POL))
    598300
    599301
    600 
    601 
    602 
    603 @subheading DESCRIPTION:
    604 
    605 
     302@subheading DESCRIPTION:
    606303
    607304The 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).
    608305
    609 
    610 
    611 @subheading NOTES:
    612 
    613 
    614 
    615 @c
    616 
     306@subheading NOTES:
     307
     308@c
    617309@c  rel_blk
    618 
    619 @c
    620 
    621 
    622 
    623 @page
    624 
     310@c
     311
     312@page
    625313@subsection rel_blk - Release Variable-Size Memory Block
    626314
    627 
    628 
    629 @subheading CALLING SEQUENCE:
    630 
    631 
    632 
    633 @ifset is-C
    634 
    635 @example
    636 
     315@subheading CALLING SEQUENCE:
     316
     317@ifset is-C
     318@example
    637319ER rel_blk(
    638 
    639   ID mplid,
    640 
     320  ID mplid,
    641321  VP blk
    642 
    643 );
    644 
    645 @end example
    646 
    647 @end ifset
    648 
    649 
    650 
    651 @ifset is-Ada
    652 
    653 @end ifset
    654 
    655 
    656 
    657 @subheading STATUS CODES:
    658 
     322);
     323@end example
     324@end ifset
     325
     326@ifset is-Ada
     327@end ifset
     328
     329@subheading STATUS CODES:
    659330 
    660 
    661 @code{E_OK} - Normal Completion
    662 
    663  
    664 
    665 @code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
    666 
    667  
    668 
    669 @code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
    670 
    671  
    672 
    673 @code{E_OACV} - Object access violation (A mplid less than -4 was specified from
    674 
     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
    675338            a user task.  This is implementation dependent.)
    676 
    677  
    678 
     339 
    679340@code{E_PAR} - Parameter error (blk is invalid or an attempt was made to return
    680 
    681341the memory block to the wrong memorypool)
    682342
    683 
    684 
    685 @subheading DESCRIPTION:
    686 
    687 
     343@subheading DESCRIPTION:
    688344
    689345This 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.
    690346
    691 
    692 
    693 @subheading NOTES:
    694 
    695 
     347@subheading NOTES:
    696348
    697349When 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.
    698350
    699 
    700 
    701 @c
    702 
     351@c
    703352@c  ref_mpl
    704 
    705 @c
    706 
    707 
    708 
    709 @page
    710 
     353@c
     354
     355@page
    711356@subsection ref_mpl - Reference Variable-Size Memorypool Status
    712357
    713 
    714 
    715 @subheading CALLING SEQUENCE:
    716 
    717 
    718 
    719 @ifset is-C
    720 
    721 @example
    722 
     358@subheading CALLING SEQUENCE:
     359
     360@ifset is-C
     361@example
    723362ER ref_mpl(
    724 
    725363  T_RMPL *pk_rmpl,
    726 
    727364  ID mplid
    728 
    729 );
    730 
    731 @end example
    732 
    733 @end ifset
    734 
    735 
    736 
    737 @ifset is-Ada
    738 
    739 @end ifset
    740 
    741 
    742 
    743 @subheading STATUS CODES:
    744 
     365);
     366@end example
     367@end ifset
     368
     369@ifset is-Ada
     370@end ifset
     371
     372@subheading STATUS CODES:
    745373 
    746 
    747 @code{E_OK} - Normal Completion
    748 
    749  
    750 
    751 @code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
    752 
    753  
    754 
    755 @code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
    756 
    757  
    758 
    759 @code{E_OACV} - Object access violation (A mplid less than -4 was specified from
    760 
     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
    761381a 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.
    762 
    763  
    764 
     382 
    765383@code{E_PAR} - Parameter error (the packet address for the return parameters
    766 
    767384could not be used)
    768385
    769 
    770 
    771 @subheading DESCRIPTION:
    772 
    773 
     386@subheading DESCRIPTION:
    774387
    775388This 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.
    776389
    777 
    778 
    779 @subheading NOTES:
    780 
    781 
     390@subheading NOTES:
    782391
    783392In 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.
    784393
    785 
    786 
Note: See TracChangeset for help on using the changeset viewer.