Changeset 1baa059 in rtems for doc/itron3.0/fixedblock.t


Ignore:
Timestamp:
Nov 9, 1999, 4:40:44 PM (20 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
bd0b378
Parents:
aebc7aa5
Message:

Converted from DOS to UNIX filemode.

File:
1 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 
Note: See TracChangeset for help on using the changeset viewer.