Changeset 1baa059 in rtems
- Timestamp:
- 11/09/99 16:40:44 (24 years ago)
- Branches:
- 4.10, 4.11, 4.8, 4.9, 5, master
- Children:
- bd0b378
- Parents:
- aebc7aa5
- Location:
- doc/itron3.0
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
doc/itron3.0/fixedblock.t
raebc7aa5 r1baa059 1 1 @c 2 3 2 @c This is the chapter from the RTEMS ITRON User's Guide that 4 5 3 @c documents the services provided by the fixed block 6 7 4 @c manager. 8 9 @c 10 5 @c 11 6 @c $Id$ 12 13 @c 14 15 7 @c 16 8 17 9 @chapter Fixed Block Manager 18 10 19 20 21 11 @section Introduction 22 12 23 24 25 13 The 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 14 27 28 29 15 The services provided by the fixed block manager are: 30 16 31 32 33 17 @itemize @bullet 34 35 18 @item @code{cre_mpf} - Create Fixed-Size Memorypool 36 37 19 @item @code{del_mpf} - Delete Fixed-Size Memorypool 38 39 20 @item @code{get_blf} - Get Fixed-Size Memory Block 40 41 21 @item @code{pget_blf} - Poll and Get Fixed-Size Memory Block 42 43 22 @item @code{tget_blf} - Get Fixed-Size Memory Block with Timeout 44 45 23 @item @code{rel_blf} - Release Fixed-Size Memory Block 46 47 24 @item @code{ref_mpf} - Reference Fixed-Size Memorypool Status 48 49 25 @end itemize 50 26 51 52 53 27 @section Background 54 28 55 56 57 29 @section Operations 58 30 59 60 61 31 @section System Calls 62 32 63 64 65 33 This section details the fixed block manager's services. 66 67 34 A subsection is dedicated to each of this manager's services 68 69 35 and describes the calling sequence, related constants, usage, 70 71 36 and status codes. 72 37 73 38 74 75 76 77 @c 78 39 @c 79 40 @c cre_mpf 80 81 @c 82 83 84 85 @page 86 41 @c 42 43 @page 87 44 @subsection cre_mpf - Create Fixed-Size Memorypool 88 45 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 99 50 ER cre_mpf( 100 101 51 ID mpfid, 102 103 52 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 127 64 @code{E_NOMEM} - Insufficient memory (Memory for control block and/or for 128 129 65 memorypool 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 137 69 @code{E_RSATR} - Reserved attribute (mpfatr was invalid or could not be used) 138 139 140 70 141 71 @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 74 a user task. This is implementation dependent.) 75 151 76 @code{E_PAR} - Parameter error (pk_cmpf is invalid or mpfsz and/or blfsz is 152 153 77 negative or invalid) 154 78 155 156 157 @subheading DESCRIPTION: 158 159 79 @subheading DESCRIPTION: 160 80 161 81 This 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 82 163 164 165 @subheading NOTES: 166 167 83 @subheading NOTES: 168 84 169 85 The 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 86 171 172 173 @c 174 87 @c 175 88 @c del_mpf 176 177 @c 178 179 180 181 @page 182 89 @c 90 91 @page 183 92 @subsection del_mpf - Delete Fixed-Size Memorypool 184 93 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 195 98 ER del_mpf( 196 197 99 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 229 115 @code{E_OACV} - Object access violation (A mpfid less than -4 was specified from a user task. This is implementation dependent.) 230 116 231 232 233 @subheading DESCRIPTION: 234 235 117 @subheading DESCRIPTION: 236 118 237 119 This 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 120 239 240 241 @subheading NOTES: 242 243 121 @subheading NOTES: 244 122 245 123 When 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 124 247 125 248 249 250 251 @c 252 126 @c 253 127 @c get_blf 254 255 @c 256 257 258 259 @page 260 128 @c 129 130 @page 261 131 @subsection get_blf - Get Fixed-Size Memory Block 262 132 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 273 137 ER get_blf( 274 275 138 VP *p_blf, 276 277 139 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: 295 148 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 156 a user task. This is implementation dependent.) 157 315 158 @code{E_PAR} - Parameter error (tmout is -2 or less) 316 317 318 159 319 160 @code{E_DLT} - The object being waited for was deleted (the specified memorypool 320 321 161 was deleted while waiting) 322 323 324 162 325 163 @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while 326 327 164 waiting) 328 329 330 165 331 166 @code{E_TMOUT} - Polling failure or timeout exceeded 332 333 334 167 335 168 @code{E_CTX} - Context error (issued from task-independent portions or a 336 337 169 task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL)) 338 170 339 340 341 @subheading DESCRIPTION: 342 343 171 @subheading DESCRIPTION: 344 172 345 173 A 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 174 347 348 349 @subheading NOTES: 350 351 352 353 354 355 @c 356 175 @subheading NOTES: 176 177 178 @c 357 179 @c pget_blf 358 359 @c 360 361 362 363 @page 364 180 @c 181 182 @page 365 183 @subsection pget_blf - Poll and Get Fixed-Size Memory Block 366 184 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 377 189 ER ercd =pget_blf( 378 379 190 VP *p_blf, 380 381 191 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 208 a user task. This is implementation dependent.) 209 419 210 @code{E_PAR} - Parameter error (tmout is -2 or less) 420 421 422 211 423 212 @code{E_DLT} - The object being waited for was deleted (the specified memorypool 424 425 213 was deleted while waiting) 426 427 428 214 429 215 @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while 430 431 216 waiting) 432 433 434 217 435 218 @code{E_TMOUT} - Polling failure or timeout exceeded 436 437 438 219 439 220 @code{E_CTX} - Context error (issued from task-independent portions or a 440 441 221 task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL)) 442 222 443 444 445 @subheading DESCRIPTION: 446 447 223 @subheading DESCRIPTION: 448 224 449 225 The 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 226 451 452 453 227 - If there is a free memory block available, processing is the same as 454 455 228 get_blf: that is, the requested memory is allocated and the system call 456 457 229 completes normally. 458 230 459 460 461 231 - If there is no free memory block, an E_TMOUT error is returned to 462 463 232 indicate polling failed and the system call finishes. Unlike get_blf, 464 465 233 the issuing task does not wait in this case. Also, the issuing task 466 467 234 does not get any memory. 468 235 469 470 471 @subheading NOTES: 472 473 474 475 476 477 @c 478 236 @subheading NOTES: 237 238 239 @c 479 240 @c tget_blf 480 481 @c 482 483 484 485 @page 486 241 @c 242 243 @page 487 244 @subsection tget_blf - Get Fixed-Size Memory Block with Timeout 488 245 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 499 250 ER ercd =tget_blf( 500 501 251 VP *p_blf, 502 503 252 ID mpfid, 504 505 253 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 270 a user task. This is implementation dependent.) 271 543 272 @code{E_PAR} - Parameter error (tmout is -2 or less) 544 545 546 273 547 274 @code{E_DLT} - The object being waited for was deleted (the specified memorypool 548 549 275 was deleted while waiting) 550 551 552 276 553 277 @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while 554 555 278 waiting) 556 557 558 279 559 280 @code{E_TMOUT} - Polling failure or timeout exceeded 560 561 562 281 563 282 @code{E_CTX} - Context error (issued from task-independent portions or a 564 565 283 task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL)) 566 284 567 568 569 @subheading DESCRIPTION: 570 571 285 @subheading DESCRIPTION: 572 286 573 287 The 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 288 575 576 577 @subheading NOTES: 578 579 580 581 @c 582 289 @subheading NOTES: 290 291 @c 583 292 @c rel_blf 584 585 @c 586 587 588 589 @page 590 293 @c 294 295 @page 591 296 @subsection rel_blf - Release Fixed-Size Memory Block 592 297 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 603 302 ER rel_blf( 604 605 303 ID mpfid, 606 607 304 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 321 a user task. This is implementation dependent.) 322 645 323 @code{E_PAR} - Parameter error (blf is invalid or an attempt was made to return 646 647 324 the memory block to the wrong memorypool) 648 325 649 650 651 @subheading DESCRIPTION: 652 653 326 @subheading DESCRIPTION: 654 327 655 328 This 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 329 657 658 659 @subheading NOTES: 660 661 330 @subheading NOTES: 662 331 663 332 The 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 333 665 666 667 @c 668 334 @c 669 335 @c ref_mpf 670 671 @c 672 673 674 675 @page 676 336 @c 337 338 @page 677 339 @subsection ref_mpf - Reference Fixed-Size Memorypool Status 678 340 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 689 345 ER ref_mpf( 690 691 346 T_RMPF *pk_rmpf, 692 693 347 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) 719 360 720 721 361 @code{E_NOEXS} - Object does not exist \(the memorypool specified by mpfid does 722 723 362 not exist.) 724 725 363 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 365 a user task. This is implementation dependent.) 731 366 732 733 367 @code{E_PAR} - Parameter error (the packet address for the return parameters 734 735 368 could not be used) 736 369 737 738 739 @subheading DESCRIPTION: 740 741 370 @subheading DESCRIPTION: 742 371 743 372 This 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 373 745 746 747 @subheading NOTES: 748 749 374 @subheading NOTES: 750 375 751 376 While 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 377 753 754 755 378 Depending on the implementation, additional information besides wtsk and frbcnt (such as memorypool attributes, mpfatr) may also be referred. 756 379 757 758 -
doc/itron3.0/memorypool.t
raebc7aa5 r1baa059 1 1 @c 2 3 2 @c This is the chapter from the RTEMS ITRON User's Guide that 4 5 3 @c documents the services provided by the memory pool 6 7 4 @c manager. 8 9 @c 10 5 @c 11 6 @c $Id$ 12 13 @c 14 15 7 @c 16 8 17 9 @chapter Memory Pool Manager 18 10 19 20 21 11 @section Introduction 22 12 23 24 25 13 The 26 27 14 memory pool manager is ... 28 15 29 30 31 16 The services provided by the memory pool manager are: 32 17 33 34 35 18 @itemize @bullet 36 37 19 @item @code{cre_mpl} - Create Variable-Size Memorypool 38 39 20 @item @code{del_mpl} - Delete Variable-Size Memorypool 40 41 21 @item @code{get_blk} - Get Variable-Size Memory Block 42 43 22 @item @code{pget_blk} - Poll and Get Variable-Size Memory Block 44 45 23 @item @code{tget_blk} - Get Variable-Size Memory Block with Timeout 46 47 24 @item @code{rel_blk} - Release Variable-Size Memory Block 48 49 25 @item @code{ref_mpl} - Reference Variable-Size Memorypool Status 50 51 26 @end itemize 52 27 53 54 55 28 @section Background 56 29 57 58 59 30 Memorypool management functions manage memorypools and allocate memory blocks. 60 61 31 There are two types of memorypool: fixed-size memorypools and variable-size 62 63 32 memorypools. Both are considered separate objects and require different 64 65 33 system calls for manipulation. While the size of memory blocks allocated 66 67 34 from fixed-size memorypools are all fixed, blocks of any size may be 68 69 35 specified when allocating memory blocks from variable-size memorypools. 70 36 71 72 73 37 @section Operations 74 38 75 76 77 39 @section System Calls 78 40 79 80 81 41 This section details the memory pool manager's services. 82 83 42 A subsection is dedicated to each of this manager's services 84 85 43 and describes the calling sequence, related constants, usage, 86 87 44 and status codes. 88 45 89 46 90 91 92 93 @c 94 47 @c 95 48 @c cre_mpl 96 97 @c 98 99 100 101 @page 102 49 @c 50 51 @page 103 52 @subsection cre_mpl - Create Variable-Size Memorypool 104 53 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 115 58 ER cre_mpl( 116 117 ID mplid, 118 59 ID mplid, 119 60 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 142 71 143 72 @code{E_NOMEM} - Insufficient memory (Memory for control block and/or for 144 145 73 memorypool cannot be allocated) 146 74 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) 152 76 153 77 @code{E_RSATR} - Reserved attribute (mplatr was invalid or could not be used) 154 78 155 156 157 79 @code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists) 158 80 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 82 a user task. This is implementation dependent.) 166 83 167 84 @code{E_PAR} - Parameter error (pk_cmpl is invalid or mplsz is negative or 168 169 85 invalid) 170 86 171 172 173 @subheading DESCRIPTION: 174 175 87 @subheading DESCRIPTION: 176 88 177 89 The 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 90 179 180 181 @subheading NOTES: 182 183 91 @subheading NOTES: 184 92 185 93 The 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 94 187 188 189 @c 190 95 @c 191 96 @c del_mpl 192 193 @c 194 195 196 197 @page 198 97 @c 98 99 @page 199 100 @subsection del_mpl - Delete Variable-Size Memorypool 200 101 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 211 106 ER del_mpl( 212 213 107 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: 231 116 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 124 a user task. This is implementation dependent.) 125 126 @subheading DESCRIPTION: 254 127 255 128 This 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 129 257 258 259 @subheading NOTES: 260 261 130 @subheading NOTES: 262 131 263 132 When 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 133 265 266 267 @c 268 134 @c 269 135 @c get_blk 270 271 @c 272 273 274 275 @page 276 136 @c 137 138 @page 277 139 @subsection get_blk - Get Variable-Size Memory Block 278 140 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 289 145 ER get_blk( 290 291 146 VP *p_blk, 292 293 ID mplid, 294 147 ID mplid, 295 148 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 165 a user task. This is implementation dependent.) 166 333 167 @code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid) 334 335 336 168 337 169 @code{E_DLT} - The object being waited for was deleted (the specified memorypool 338 339 170 was deleted while waiting) 340 341 342 171 343 172 @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while 344 345 173 waiting) 346 347 348 174 349 175 @code{E_TMOUT} - Polling failure or timeout 350 176 351 352 353 177 @code{E_CTX} - Context error (issued from task-independent portions or a 354 355 178 task in dispatch disabled state; implementation dependent for 356 357 179 pget_blk and tget_blk(tmout=TMO_POL)) 358 180 359 360 361 @subheading DESCRIPTION: 362 363 181 @subheading DESCRIPTION: 364 182 365 183 A 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 184 367 368 369 185 The 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 186 371 372 373 @subheading NOTES: 374 375 187 @subheading NOTES: 376 188 377 189 Pget_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 190 379 380 381 @c 382 191 @c 383 192 @c pget_blk 384 385 @c 386 387 388 389 @page 390 193 @c 194 195 @page 391 196 @subsection pget_blk - Poll and Get Variable-Size Memory Block 392 197 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 403 202 ER ercd =pget_blk( 404 405 203 VP *p_blk, 406 407 ID mplid, 408 204 ID mplid, 409 205 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 222 a user task. This is implementation dependent.) 223 447 224 @code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid) 448 225 449 450 451 226 @code{E_DLT} - The object being waited for was deleted (the specified memorypool 452 453 227 was deleted while waiting) 454 455 456 228 457 229 @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while 458 459 230 waiting) 460 461 462 231 463 232 @code{E_TMOUT} - Polling failure or timeout 464 465 466 233 467 234 @code{E_CTX} - Context error (issued from task-independent portions or a 468 469 235 task in dispatch disabled state; implementation dependent for 470 471 236 pget_blk and tget_blk(tmout=TMO_POL)) 472 237 473 474 475 @subheading DESCRIPTION: 476 477 238 @subheading DESCRIPTION: 478 239 479 240 The 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 241 481 482 483 242 - If there is enough free memory to get the memory block of specified size 484 485 243 immediately, processing is the same as get_blk: that is, the 486 487 244 requested memory is allocated and the system call completes normally. 488 245 489 490 491 246 - If there is not enough free memory, an E_TMOUT error is returned to 492 493 247 indicate polling failed and the system call finishes. Unlike get_blk, 494 495 248 the issuing task does not wait in this case. Also, the issuing task 496 497 249 does not get any memory. 498 250 499 500 501 @subheading NOTES: 502 503 504 505 @c 506 251 @subheading NOTES: 252 253 @c 507 254 @c tget_blk 508 509 @c 510 511 512 513 @page 514 255 @c 256 257 @page 515 258 @subsection tget_blk - Get Variable-Size Memory Block with Timeout 516 259 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 527 264 ER ercd =tget_blk( 528 529 265 VP *p_blk, 530 531 ID mplid, 532 266 ID mplid, 533 267 INT blksz, 534 535 268 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 285 a user task. This is implementation dependent.) 286 573 287 @code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid) 574 288 575 576 577 289 @code{E_DLT} - The object being waited for was deleted (the specified memorypool 578 579 290 was deleted while waiting) 580 581 582 291 583 292 @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while 584 585 293 waiting) 586 587 588 294 589 295 @code{E_TMOUT} - Polling failure or timeout 590 591 592 296 593 297 @code{E_CTX} - Context error (issued from task-independent portions or a 594 595 298 task in dispatch disabled state; implementation dependent for 596 597 299 pget_blk and tget_blk(tmout=TMO_POL)) 598 300 599 301 600 601 602 603 @subheading DESCRIPTION: 604 605 302 @subheading DESCRIPTION: 606 303 607 304 The 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 305 609 610 611 @subheading NOTES: 612 613 614 615 @c 616 306 @subheading NOTES: 307 308 @c 617 309 @c rel_blk 618 619 @c 620 621 622 623 @page 624 310 @c 311 312 @page 625 313 @subsection rel_blk - Release Variable-Size Memory Block 626 314 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 637 319 ER rel_blk( 638 639 ID mplid, 640 320 ID mplid, 641 321 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: 659 330 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 675 338 a user task. This is implementation dependent.) 676 677 678 339 679 340 @code{E_PAR} - Parameter error (blk is invalid or an attempt was made to return 680 681 341 the memory block to the wrong memorypool) 682 342 683 684 685 @subheading DESCRIPTION: 686 687 343 @subheading DESCRIPTION: 688 344 689 345 This 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 346 691 692 693 @subheading NOTES: 694 695 347 @subheading NOTES: 696 348 697 349 When 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 350 699 700 701 @c 702 351 @c 703 352 @c ref_mpl 704 705 @c 706 707 708 709 @page 710 353 @c 354 355 @page 711 356 @subsection ref_mpl - Reference Variable-Size Memorypool Status 712 357 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 723 362 ER ref_mpl( 724 725 363 T_RMPL *pk_rmpl, 726 727 364 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: 745 373 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 761 381 a 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 765 383 @code{E_PAR} - Parameter error (the packet address for the return parameters 766 767 384 could not be used) 768 385 769 770 771 @subheading DESCRIPTION: 772 773 386 @subheading DESCRIPTION: 774 387 775 388 This 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 389 777 778 779 @subheading NOTES: 780 781 390 @subheading NOTES: 782 391 783 392 In 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 393 785 786
Note: See TracChangeset
for help on using the changeset viewer.