Changeset 91e9ab8 in rtems


Ignore:
Timestamp:
Aug 11, 1999, 9:14:16 PM (22 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
1d4048b2
Parents:
be5df8d
Message:

Final update from Santanu Mitra <smitra@…>, T.N.S. Prasad
<ptelukun@…>, and Wei He <whe@…> on the Fixed
Block and Memory Pool Managers.

Location:
doc/itron3.0
Files:
2 edited

Legend:

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

    rbe5df8d r91e9ab8  
    11@c
     2
    23@c  This is the chapter from the RTEMS ITRON User's Guide that
     4
    35@c  documents the services provided by the fixed block
     6
    47@c  manager.
    5 @c
     8
     9@c
     10
    611@c  $Id$
    7 @c
     12
     13@c
     14
     15
    816
    917@chapter Fixed Block Manager
    1018
     19
     20
    1121@section Introduction
    1222
    13 The
    14 fixed block manager is ...
     23
     24
     25The 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.
     26
     27
    1528
    1629The services provided by the fixed block manager are:
    1730
     31
     32
    1833@itemize @bullet
     34
    1935@item @code{cre_mpf} - Create Fixed-Size Memorypool
     36
    2037@item @code{del_mpf} - Delete Fixed-Size Memorypool
     38
    2139@item @code{get_blf} - Get Fixed-Size Memory Block
     40
    2241@item @code{pget_blf} - Poll and Get Fixed-Size Memory Block
     42
    2343@item @code{tget_blf} - Get Fixed-Size Memory Block with Timeout
     44
    2445@item @code{rel_blf} - Release Fixed-Size Memory Block
     46
    2547@item @code{ref_mpf} - Reference Fixed-Size Memorypool Status
     48
    2649@end itemize
    2750
     51
     52
    2853@section Background
    2954
     55
     56
    3057@section Operations
    3158
     59
     60
    3261@section System Calls
    3362
     63
     64
    3465This section details the fixed block manager's services.
     66
    3567A subsection is dedicated to each of this manager's services
     68
    3669and describes the calling sequence, related constants, usage,
     70
    3771and status codes.
    3872
    3973
    40 @c
     74
     75
     76
     77@c
     78
    4179@c  cre_mpf
    42 @c
     80
     81@c
     82
     83
    4384
    4485@page
     86
    4587@subsection cre_mpf - Create Fixed-Size Memorypool
    4688
     89
     90
    4791@subheading CALLING SEQUENCE:
    4892
     93
     94
    4995@ifset is-C
     96
    5097@example
     98
    5199ER cre_mpf(
     100
    52101  ID mpfid,
     102
    53103  T_CMPF *pk_cmpf
     104
    54105);
     106
    55107@end example
    56 @end ifset
     108
     109@end ifset
     110
     111
    57112
    58113@ifset is-Ada
    59 @end ifset
     114
     115@end ifset
     116
     117
    60118
    61119@subheading STATUS CODES:
    62120
    63 @code{EXXX} -
     121
     122
     123@code{E_OK} - Normal Completion
     124
     125 
     126
     127@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for
     128
     129memorypool cannot be allocated)
     130
     131 
     132
     133@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
     134
     135 
     136
     137@code{E_RSATR} - Reserved attribute (mpfatr was invalid or could not be used)
     138
     139 
     140
     141@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
     147a user task.  This is implementation dependent.)
     148
     149 
     150
     151@code{E_PAR} - Parameter error (pk_cmpf is invalid or mpfsz and/or blfsz is
     152
     153negative or invalid)
     154
     155
    64156
    65157@subheading DESCRIPTION:
    66158
     159
     160
     161This 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).
     162
     163
     164
    67165@subheading NOTES:
    68166
    69167
    70 @c
     168
     169The 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.
     170
     171
     172
     173@c
     174
    71175@c  del_mpf
    72 @c
     176
     177@c
     178
     179
    73180
    74181@page
     182
    75183@subsection del_mpf - Delete Fixed-Size Memorypool
    76184
     185
     186
    77187@subheading CALLING SEQUENCE:
    78188
     189
     190
    79191@ifset is-C
     192
    80193@example
     194
    81195ER del_mpf(
     196
    82197  ID mpfid
     198
    83199);
     200
    84201@end example
    85 @end ifset
     202
     203@end ifset
     204
     205
    86206
    87207@ifset is-Ada
    88 @end ifset
     208
     209@end ifset
     210
     211
    89212
    90213@subheading STATUS CODES:
    91214
    92 @code{EXXX} -
     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
     229@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from a user task.  This is implementation dependent.)
     230
     231
    93232
    94233@subheading DESCRIPTION:
    95234
     235
     236
     237This 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.
     238
     239
     240
    96241@subheading NOTES:
    97242
    98243
    99 @c
     244
     245When 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.
     246
     247
     248
     249
     250
     251@c
     252
    100253@c  get_blf
    101 @c
     254
     255@c
     256
     257
    102258
    103259@page
     260
    104261@subsection get_blf - Get Fixed-Size Memory Block
    105262
     263
     264
    106265@subheading CALLING SEQUENCE:
    107266
     267
     268
    108269@ifset is-C
     270
    109271@example
     272
    110273ER get_blf(
     274
    111275  VP *p_blf,
     276
    112277  ID mpfid
     278
    113279);
     280
    114281@end example
    115 @end ifset
     282
     283@end ifset
     284
     285
    116286
    117287@ifset is-Ada
    118 @end ifset
     288
     289@end ifset
     290
     291
    119292
    120293@subheading STATUS CODES:
    121294
    122 @code{EXXX} -
     295 
     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
     311a user task.  This is implementation dependent.)
     312
     313 
     314
     315@code{E_PAR} - Parameter error (tmout is -2 or less)
     316
     317 
     318
     319@code{E_DLT} - The object being waited for was deleted (the specified memorypool
     320
     321was deleted while waiting)
     322
     323 
     324
     325@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
     326
     327waiting)
     328
     329 
     330
     331@code{E_TMOUT} - Polling failure or timeout exceeded
     332
     333 
     334
     335@code{E_CTX} - Context error (issued from task-independent portions or a
     336
     337task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
     338
     339
    123340
    124341@subheading DESCRIPTION:
    125342
     343
     344
     345A 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.
     346
     347
     348
    126349@subheading NOTES:
    127350
    128351
    129 @c
     352
     353
     354
     355@c
     356
    130357@c  pget_blf
    131 @c
     358
     359@c
     360
     361
    132362
    133363@page
     364
    134365@subsection pget_blf - Poll and Get Fixed-Size Memory Block
    135366
     367
     368
    136369@subheading CALLING SEQUENCE:
    137370
     371
     372
    138373@ifset is-C
     374
    139375@example
     376
    140377ER ercd =pget_blf(
     378
    141379  VP *p_blf,
     380
    142381  ID mpfid
     382
    143383);
     384
    144385@end example
    145 @end ifset
     386
     387@end ifset
     388
     389
    146390
    147391@ifset is-Ada
    148 @end ifset
     392
     393@end ifset
     394
     395
    149396
    150397@subheading STATUS CODES:
    151398
    152 @code{EXXX} -
     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
     415a user task.  This is implementation dependent.)
     416
     417 
     418
     419@code{E_PAR} - Parameter error (tmout is -2 or less)
     420
     421 
     422
     423@code{E_DLT} - The object being waited for was deleted (the specified memorypool
     424
     425was deleted while waiting)
     426
     427 
     428
     429@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
     430
     431waiting)
     432
     433 
     434
     435@code{E_TMOUT} - Polling failure or timeout exceeded
     436
     437 
     438
     439@code{E_CTX} - Context error (issued from task-independent portions or a
     440
     441task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
     442
     443
    153444
    154445@subheading DESCRIPTION:
    155446
     447
     448
     449The 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.
     450
     451
     452
     453  - If there is a free memory block available, processing is the same as
     454
     455    get_blf: that is, the requested memory is allocated and the system call
     456
     457    completes normally.
     458
     459
     460
     461  - If there is no free memory block, an E_TMOUT error is returned to
     462
     463    indicate polling failed and the system call finishes.  Unlike get_blf,
     464
     465    the issuing task does not wait in this case.  Also, the issuing task
     466
     467    does not get any memory.
     468
     469
     470
    156471@subheading NOTES:
    157472
    158473
    159 @c
     474
     475
     476
     477@c
     478
    160479@c  tget_blf
    161 @c
     480
     481@c
     482
     483
    162484
    163485@page
     486
    164487@subsection tget_blf - Get Fixed-Size Memory Block with Timeout
    165488
     489
     490
    166491@subheading CALLING SEQUENCE:
    167492
     493
     494
    168495@ifset is-C
     496
    169497@example
     498
    170499ER ercd =tget_blf(
     500
    171501  VP *p_blf,
     502
    172503  ID mpfid,
     504
    173505  TMO tmout
     506
    174507);
     508
    175509@end example
    176 @end ifset
     510
     511@end ifset
     512
     513
    177514
    178515@ifset is-Ada
    179 @end ifset
     516
     517@end ifset
     518
     519
    180520
    181521@subheading STATUS CODES:
    182522
    183 @code{EXXX} -
     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
     539a user task.  This is implementation dependent.)
     540
     541 
     542
     543@code{E_PAR} - Parameter error (tmout is -2 or less)
     544
     545 
     546
     547@code{E_DLT} - The object being waited for was deleted (the specified memorypool
     548
     549was deleted while waiting)
     550
     551 
     552
     553@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
     554
     555waiting)
     556
     557 
     558
     559@code{E_TMOUT} - Polling failure or timeout exceeded
     560
     561 
     562
     563@code{E_CTX} - Context error (issued from task-independent portions or a
     564
     565task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
     566
     567
    184568
    185569@subheading DESCRIPTION:
    186570
     571
     572
     573The 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).
     574
     575
     576
    187577@subheading NOTES:
    188578
    189579
    190 @c
     580
     581@c
     582
    191583@c  rel_blf
    192 @c
     584
     585@c
     586
     587
    193588
    194589@page
     590
    195591@subsection rel_blf - Release Fixed-Size Memory Block
    196592
     593
     594
    197595@subheading CALLING SEQUENCE:
    198596
     597
     598
    199599@ifset is-C
     600
    200601@example
     602
    201603ER rel_blf(
     604
    202605  ID mpfid,
     606
    203607  VP blf
     608
    204609);
     610
    205611@end example
    206 @end ifset
     612
     613@end ifset
     614
     615
    207616
    208617@ifset is-Ada
    209 @end ifset
     618
     619@end ifset
     620
     621
    210622
    211623@subheading STATUS CODES:
    212624
    213 @code{EXXX} -
     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
     641a user task.  This is implementation dependent.)
     642
     643 
     644
     645@code{E_PAR} - Parameter error (blf is invalid or an attempt was made to return
     646
     647the memory block to the wrong memorypool)
     648
     649
    214650
    215651@subheading DESCRIPTION:
    216652
     653
     654
     655This 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.
     656
     657
     658
    217659@subheading NOTES:
    218660
    219661
    220 @c
     662
     663The 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.
     664
     665
     666
     667@c
     668
    221669@c  ref_mpf
    222 @c
     670
     671@c
     672
     673
    223674
    224675@page
     676
    225677@subsection ref_mpf - Reference Fixed-Size Memorypool Status
    226678
     679
     680
    227681@subheading CALLING SEQUENCE:
    228682
     683
     684
    229685@ifset is-C
     686
    230687@example
     688
    231689ER ref_mpf(
     690
    232691  T_RMPF *pk_rmpf,
     692
    233693  ID mpfid
     694
    234695);
     696
    235697@end example
    236 @end ifset
     698
     699@end ifset
     700
     701
    237702
    238703@ifset is-Ada
    239 @end ifset
     704
     705@end ifset
     706
     707
    240708
    241709@subheading STATUS CODES:
    242710
    243 @code{EXXX} -
     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
     719 
     720
     721@code{E_NOEXS} - Object does not exist \(the memorypool specified by mpfid does
     722
     723not exist.)
     724
     725                                                                                                                                                 
     726
     727@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
     728
     729a user task.  This is implementation dependent.)
     730
     731 
     732
     733@code{E_PAR} - Parameter error (the packet address for the return parameters
     734
     735could not be used)
     736
     737
    244738
    245739@subheading DESCRIPTION:
    246740
     741
     742
     743This 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.
     744
     745
     746
    247747@subheading NOTES:
    248748
     749
     750
     751While 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.
     752
     753
     754
     755Depending on the implementation, additional information besides wtsk and frbcnt (such as memorypool attributes, mpfatr) may also be referred.
     756
     757
     758
  • doc/itron3.0/memorypool.t

    rbe5df8d r91e9ab8  
    11@c
     2
    23@c  This is the chapter from the RTEMS ITRON User's Guide that
     4
    35@c  documents the services provided by the memory pool
     6
    47@c  manager.
    5 @c
     8
     9@c
     10
    611@c  $Id$
    7 @c
     12
     13@c
     14
     15
    816
    917@chapter Memory Pool Manager
    1018
     19
     20
    1121@section Introduction
    1222
     23
     24
    1325The
     26
    1427memory pool manager is ...
    1528
     29
     30
    1631The services provided by the memory pool manager are:
    1732
     33
     34
    1835@itemize @bullet
     36
    1937@item @code{cre_mpl} - Create Variable-Size Memorypool
     38
    2039@item @code{del_mpl} - Delete Variable-Size Memorypool
     40
    2141@item @code{get_blk} - Get Variable-Size Memory Block
     42
    2243@item @code{pget_blk} - Poll and Get Variable-Size Memory Block
     44
    2345@item @code{tget_blk} - Get Variable-Size Memory Block with Timeout
     46
    2447@item @code{rel_blk} - Release Variable-Size Memory Block
     48
    2549@item @code{ref_mpl} - Reference Variable-Size Memorypool Status
     50
    2651@end itemize
    2752
     53
     54
    2855@section Background
    2956
     57
     58
     59Memorypool management functions manage memorypools and allocate memory blocks.
     60
     61There are two types of memorypool: fixed-size memorypools and variable-size
     62
     63memorypools.  Both are considered separate objects and require different
     64
     65system calls for manipulation.  While the size of memory blocks allocated
     66
     67from fixed-size memorypools are all fixed, blocks of any size may be
     68
     69specified when allocating memory blocks from variable-size memorypools.
     70
     71
     72
    3073@section Operations
    3174
     75
     76
    3277@section System Calls
    3378
     79
     80
    3481This section details the memory pool manager's services.
     82
    3583A subsection is dedicated to each of this manager's services
     84
    3685and describes the calling sequence, related constants, usage,
     86
    3787and status codes.
    3888
    3989
    40 @c
     90
     91
     92
     93@c
     94
    4195@c  cre_mpl
    42 @c
     96
     97@c
     98
     99
    43100
    44101@page
     102
    45103@subsection cre_mpl - Create Variable-Size Memorypool
    46104
     105
     106
    47107@subheading CALLING SEQUENCE:
    48108
     109
     110
    49111@ifset is-C
     112
    50113@example
     114
    51115ER cre_mpl(
     116
    52117  ID mplid,
     118
    53119  T_CMPL *pk_cmpl
     120
    54121);
     122
    55123@end example
    56 @end ifset
     124
     125@end ifset
     126
     127
    57128
    58129@ifset is-Ada
    59 @end ifset
     130
     131@end ifset
     132
     133
    60134
    61135@subheading STATUS CODES:
    62136
    63 @code{EXXX} -
     137
     138
     139@code{E_OK} - Normal Completion
     140
     141
     142
     143@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for
     144
     145memorypool cannot be allocated)
     146
     147
     148
     149@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
     150
     151
     152
     153@code{E_RSATR} - Reserved attribute (mplatr was invalid or could not be used)
     154
     155
     156
     157@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists)
     158
     159
     160
     161@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
     162
     163a user task.  This is implementation dependent.)
     164
     165
     166
     167@code{E_PAR} - Parameter error (pk_cmpl is invalid or mplsz is negative or
     168
     169invalid)
     170
     171
    64172
    65173@subheading DESCRIPTION:
    66174
     175
     176
     177The 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).
     178
     179
     180
    67181@subheading NOTES:
    68182
    69183
    70 @c
     184
     185The 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.
     186
     187
     188
     189@c
     190
    71191@c  del_mpl
    72 @c
     192
     193@c
     194
     195
    73196
    74197@page
     198
    75199@subsection del_mpl - Delete Variable-Size Memorypool
    76200
     201
     202
    77203@subheading CALLING SEQUENCE:
    78204
     205
     206
    79207@ifset is-C
     208
    80209@example
     210
    81211ER del_mpl(
     212
    82213  ID mplid
     214
    83215);
     216
    84217@end example
    85 @end ifset
     218
     219@end ifset
     220
     221
    86222
    87223@ifset is-Ada
    88 @end ifset
     224
     225@end ifset
     226
     227
    89228
    90229@subheading STATUS CODES:
    91230
    92 @code{EXXX} -
     231 
     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
     247a user task.  This is implementation dependent.)
     248
     249
    93250
    94251@subheading DESCRIPTION:
    95252
     253
     254
     255This 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.
     256
     257
     258
    96259@subheading NOTES:
    97260
    98261
    99 @c
     262
     263When 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.
     264
     265
     266
     267@c
     268
    100269@c  get_blk
    101 @c
     270
     271@c
     272
     273
    102274
    103275@page
     276
    104277@subsection get_blk - Get Variable-Size Memory Block
    105278
     279
     280
    106281@subheading CALLING SEQUENCE:
    107282
     283
     284
    108285@ifset is-C
     286
    109287@example
     288
    110289ER get_blk(
     290
    111291  VP *p_blk,
     292
    112293  ID mplid,
     294
    113295  INT blksz
     296
    114297);
     298
    115299@end example
    116 @end ifset
     300
     301@end ifset
     302
     303
    117304
    118305@ifset is-Ada
    119 @end ifset
     306
     307@end ifset
     308
     309
    120310
    121311@subheading STATUS CODES:
    122312
    123 @code{EXXX} -
     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
     329a user task.  This is implementation dependent.)
     330
     331 
     332
     333@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
     334
     335 
     336
     337@code{E_DLT} - The object being waited for was deleted (the specified memorypool
     338
     339was deleted while waiting)
     340
     341 
     342
     343@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
     344
     345waiting)
     346
     347 
     348
     349@code{E_TMOUT} - Polling failure or timeout
     350
     351
     352
     353@code{E_CTX} - Context error (issued from task-independent portions or a
     354
     355task in dispatch disabled state; implementation dependent for
     356
     357pget_blk and tget_blk(tmout=TMO_POL))
     358
     359
    124360
    125361@subheading DESCRIPTION:
    126362
     363
     364
     365A 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.
     366
     367
     368
     369The 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.
     370
     371
     372
    127373@subheading NOTES:
    128374
    129375
    130 @c
     376
     377Pget_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.
     378
     379
     380
     381@c
     382
    131383@c  pget_blk
    132 @c
     384
     385@c
     386
     387
    133388
    134389@page
     390
    135391@subsection pget_blk - Poll and Get Variable-Size Memory Block
    136392
     393
     394
    137395@subheading CALLING SEQUENCE:
    138396
     397
     398
    139399@ifset is-C
     400
    140401@example
     402
    141403ER ercd =pget_blk(
     404
    142405  VP *p_blk,
     406
    143407  ID mplid,
     408
    144409  INT blksz
     410
    145411);
     412
    146413@end example
    147 @end ifset
     414
     415@end ifset
     416
     417
    148418
    149419@ifset is-Ada
    150 @end ifset
     420
     421@end ifset
     422
     423
    151424
    152425@subheading STATUS CODES:
    153426
    154 @code{EXXX} -
     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
     443a user task.  This is implementation dependent.)
     444
     445 
     446
     447@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
     448
     449
     450
     451@code{E_DLT} - The object being waited for was deleted (the specified memorypool
     452
     453was deleted while waiting)
     454
     455 
     456
     457@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
     458
     459waiting)
     460
     461 
     462
     463@code{E_TMOUT} - Polling failure or timeout
     464
     465 
     466
     467@code{E_CTX} - Context error (issued from task-independent portions or a
     468
     469task in dispatch disabled state; implementation dependent for
     470
     471pget_blk and tget_blk(tmout=TMO_POL))
     472
     473
    155474
    156475@subheading DESCRIPTION:
    157476
     477
     478
     479The 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.
     480
     481
     482
     483  - If there is enough free memory to get the memory block of specified size
     484
     485    immediately, processing is the same as get_blk: that is, the
     486
     487    requested memory is allocated and the system call completes normally.
     488
     489
     490
     491  - If there is not enough free memory, an E_TMOUT error is returned to
     492
     493    indicate polling failed and the system call finishes.  Unlike get_blk,
     494
     495    the issuing task does not wait in this case.  Also, the issuing task
     496
     497    does not get any memory.
     498
     499
     500
    158501@subheading NOTES:
    159502
    160503
    161 @c
     504
     505@c
     506
    162507@c  tget_blk
    163 @c
     508
     509@c
     510
     511
    164512
    165513@page
     514
    166515@subsection tget_blk - Get Variable-Size Memory Block with Timeout
    167516
     517
     518
    168519@subheading CALLING SEQUENCE:
    169520
     521
     522
    170523@ifset is-C
     524
    171525@example
     526
    172527ER ercd =tget_blk(
     528
    173529  VP *p_blk,
     530
    174531  ID mplid,
     532
    175533  INT blksz,
     534
    176535  TMO tmout
     536
    177537);
     538
    178539@end example
    179 @end ifset
     540
     541@end ifset
     542
     543
    180544
    181545@ifset is-Ada
    182 @end ifset
     546
     547@end ifset
     548
     549
    183550
    184551@subheading STATUS CODES:
    185552
    186 @code{EXXX} -
     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
     569a user task.  This is implementation dependent.)
     570
     571 
     572
     573@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
     574
     575
     576
     577@code{E_DLT} - The object being waited for was deleted (the specified memorypool
     578
     579was deleted while waiting)
     580
     581 
     582
     583@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
     584
     585waiting)
     586
     587 
     588
     589@code{E_TMOUT} - Polling failure or timeout
     590
     591 
     592
     593@code{E_CTX} - Context error (issued from task-independent portions or a
     594
     595task in dispatch disabled state; implementation dependent for
     596
     597pget_blk and tget_blk(tmout=TMO_POL))
     598
     599
     600
     601
    187602
    188603@subheading DESCRIPTION:
    189604
     605
     606
     607The 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).
     608
     609
     610
    190611@subheading NOTES:
    191612
    192613
    193 @c
     614
     615@c
     616
    194617@c  rel_blk
    195 @c
     618
     619@c
     620
     621
    196622
    197623@page
     624
    198625@subsection rel_blk - Release Variable-Size Memory Block
    199626
     627
     628
    200629@subheading CALLING SEQUENCE:
    201630
     631
     632
    202633@ifset is-C
     634
    203635@example
     636
    204637ER rel_blk(
     638
    205639  ID mplid,
     640
    206641  VP blk
     642
    207643);
     644
    208645@end example
    209 @end ifset
     646
     647@end ifset
     648
     649
    210650
    211651@ifset is-Ada
    212 @end ifset
     652
     653@end ifset
     654
     655
    213656
    214657@subheading STATUS CODES:
    215658
    216 @code{EXXX} -
     659 
     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
     675            a user task.  This is implementation dependent.)
     676
     677 
     678
     679@code{E_PAR} - Parameter error (blk is invalid or an attempt was made to return
     680
     681the memory block to the wrong memorypool)
     682
     683
    217684
    218685@subheading DESCRIPTION:
    219686
     687
     688
     689This 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.
     690
     691
     692
    220693@subheading NOTES:
    221694
    222695
    223 @c
     696
     697When 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.
     698
     699
     700
     701@c
     702
    224703@c  ref_mpl
    225 @c
     704
     705@c
     706
     707
    226708
    227709@page
     710
    228711@subsection ref_mpl - Reference Variable-Size Memorypool Status
    229712
     713
     714
    230715@subheading CALLING SEQUENCE:
    231716
     717
     718
    232719@ifset is-C
     720
    233721@example
     722
    234723ER ref_mpl(
     724
    235725  T_RMPL *pk_rmpl,
     726
    236727  ID mplid
     728
    237729);
     730
    238731@end example
    239 @end ifset
     732
     733@end ifset
     734
     735
    240736
    241737@ifset is-Ada
    242 @end ifset
     738
     739@end ifset
     740
     741
    243742
    244743@subheading STATUS CODES:
    245744
    246 @code{EXXX} -
     745 
     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
     761a 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
     765@code{E_PAR} - Parameter error (the packet address for the return parameters
     766
     767could not be used)
     768
     769
    247770
    248771@subheading DESCRIPTION:
    249772
     773
     774
     775This 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.
     776
     777
     778
    250779@subheading NOTES:
    251780
     781
     782
     783In 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.
     784
     785
     786
Note: See TracChangeset for help on using the changeset viewer.