Memory Pool Management Functions
Memory pool management functions are for managing memory pools and allocating memory blocks by using software.
There are fixed-size memory pools and variable-size memory pools, which are considered separate objects and require separate sets of system calls for their operation. Memory blocks allocated from a fixed-size memory pool are all of one fixed size, whereas memory blocks from a variable-size memory pool can be of various sizes.
Fixed-size Memory Pool
A fixed-size memory pool is an object used for dynamic management of fixed-size memory blocks. Functions are provided for creating and deleting a fixed-size memory pool, getting and returning memory blocks in a fixed-size memory pool, and referencing the status of a fixed-size memory pool. A fixed-size memory pool is an object identified by an ID number. The ID number for the fixed-size memory pool is called a fixed-size memory pool ID.
A fixed-size memory pool has a memory space used as the fixed-size memory pool (called a fixed-size memory pool area or simply memory pool area), and a queue for tasks waiting for memory block allocation. A task wanting to allocate a memory block from a fixed-size memory pool that lacks sufficient available memory space goes to WAITING state for fixed-size memory block until memory blocks are returned to the pool. A task in this state is put in the task queue of the fixed-size memory pool.
 | Additional Notes |
|---|---|
When memory blocks of various sizes are needed from fixed-size memory pools, it is necessary to provide multiple memory pools of different sizes. |
tk_cre_mpf - Create Fixed-size Memory Pool
Parameter
| CONST T_CMBX* |
pk_cmpf
| Packet to Create Memory Pool | Information about the fixed-size memory pool to be created |
pk_cmpf Detail:
| void* |
exinf
| Extended Information | Extended information |
| ATR |
mpfatr
| Memory Pool Attribute | Memory pool attribute |
| SZ |
mpfcnt
| Memory Pool Block Count | Memory pool block count |
| SZ |
blfsz
| Memory Block Size | Fixed-size memory block size (in bytes) |
| UB |
dsname[8]
| DS Object name | DS object name |
| void* |
bufptr
| Buffer Pointer | User buffer pointer |
| (Other implementation-dependent parameters may be added beyond this point.) | |||
Error Code
| E_NOMEM | Insufficient memory (memory for control block or memory pool area cannot be allocated) |
| E_LIMIT | Number of fixed-size memory pools exceeds the system limit |
| E_RSATR | Reserved attribute (mpfatr is invalid or cannot be used) |
| E_PAR | Parameter error (pk_cmpf is illegal, mpfcnt, blfsz is negative or invalid, or bufptr is illegal) |
Related Service Profile Items
| TK_SUPPORT_USERBUF | Support for specifying TA_USERBUF for fixed-size memory pool attribute |
| TK_SUPPORT_AUTOBUF | Automatic buffer allocation is supported (by not specifying TA_USERBUF to fixed-size memory pool attribute) |
| TK_SUPPORT_DISWAI | Support for specifying TA_NODISWAI (reject request to disable wait) to fixed-size memory pool attribute |
| TK_SUPPORT_DSNAME | Support for specifying TA_DSNAME for fixed-size memory pool attribute |
Description
Creates a fixed-size memory pool, assigning to it a fixed-size memory pool ID. This system call allocates a memory space for use as a memory pool based on the information specified in parameters mpfcnt and blfsz, and assigns a control block to the memory pool. A memory block of size blfsz can be allocated from the created memory pool by calling the tk_get_mpf system call.
exinf can be used freely by the user to set miscellaneous information about the created memory pool. The information set in this parameter can be referenced by tk_ref_mpf. If a larger area is needed for indicating user information, or if the information may need to be changed after the message buffer is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The kernel pays no attention to the contents of exinf.
mpfatr indicates system attributes in its lower bits and implementation-dependent attributes in its higher bits. The system attribute part of mpfatr is as follows.
mpfatr := (TA_TFIFO || TA_TPRI) | [TA_DSNAME] | [TA_USERBUF] | [TA_NODISWAI]
| (TA_RNG0 || TA_RNG1 || TA_RNG2 || TA_RNG3)
| TA_TFIFO | Tasks waiting for memory allocation are queued in FIFO order |
| TA_TPRI | Tasks waiting for memory allocation are queued in priority order |
| TA_RNGn | Memory access privilege is set to protection level n |
| TA_DSNAME | Specifies DS object name |
| TA_USERBUF | Support of user-specified memory area as memory pool area |
| TA_NODISWAI | Disabling of wait by tk_dis_wai is prohibited |
#define TA_TFIFO 0x00000000 /* manage queue by FIFO */ #define TA_TPRI 0x00000001 /* manage queue by priority */ #define TA_USERBUF 0x00000020 /* Use user-specified buffer */ #define TA_DSNAME 0x00000040 /* DS object name */ #define TA_NODISWAI 0x00000080 /* reject request to disable wait */ #define TA_RNG0 0x00000000 /* Protection level 0 */ #define TA_RNG1 0x00000100 /* Protection level 1 */ #define TA_RNG2 0x00000200 /* Protection level 2 */ #define TA_RNG3 0x00000300 /* Protection level 3 */
The queuing order of tasks waiting for memory block allocation from a memory pool can be specified in TA_TFIFO or TA_TPRI. If the attribute is TA_TFIFO, tasks are ordered by FIFO, whereas TA_TPRI specifies queuing of tasks in order of their priority setting.
TA_RNGn is specified to limit the protection levels from which memory can be accessed. Only tasks running at the same or higher protection level than the one specified can access the allocated memory. If a task running at a lower protection level attempts an access, a CPU protection fault exception is raised. For example, memory allocated from a memory pool specified as TA_RNG1 can be accessed by tasks running at levels TA_RNG0 or TA_RNG1, but not by tasks running at levels TA_RNG2 or TA_RNG3.
When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used to identify objects by debugger, and it is handled only by T-Kernel/DS API, td_ref_dsname and td_set_dsname. For more details, see the description of td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.
Additional Notes
In the case of a fixed-size memory pool, separate memory pools must be provided for different block sizes. That is, if various memory block sizes are required, memory pools must be created for each block size.
For the sake of portability, the TA_RNGn attribute must be accepted even by a system with a single CPU's operating mode. It is possible, for example, to handle all TA_RNGn as equivalent to TA_RNG0, but error must not be returned.
Porting Guideline
The T-Kernel 2.0 specification does not define TA_USERBUF and its associated notion of bufptr. So if this feature is used, a modification is necessary to port the software to T-Kernel 2.0. However, if mpfcnt and blfsz is properly set already, simply removing TA_USERBUF and bufptr will complete the modification for porting.
tk_del_mpf - Delete Fixed-size Memory Pool
Description
Deletes the fixed-size memory pool specified in mpfid.
No check or notification is made as to whether there are tasks using memory allocated from this memory pool. The system call completes normally even if not all blocks have been returned to the pool.
Issuing this system call releases the memory pool ID number, the control block memory space and the memory pool space itself.
This system call completes normally even if there are tasks waiting for memory block allocation from the deleted memory pool, but error code E_DLT is returned to the tasks in WAITING state.
tk_get_mpf - Get Fixed-size Memory Block
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (mpfid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the fixed-size memory pool specified in mpfid does not exist) |
| E_PAR | Parameter error (tmout ≦ (-2)) |
| E_DLT | The object being waited for was deleted (the memory pool was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Description
Gets a memory block from the fixed-size memory pool specified in mpfid. The start address of the allocated memory block is returned in blf. The size of the allocated memory block is the value specified in the blfsz parameter when the fixed-size memory pool was created.
The allocated memory is not cleared to zero, and the memory block contents are indeterminate.
If a block cannot be allocated from the specified memory pool, the task that issued tk_get_mpf is put in the queue of tasks waiting for memory allocation from that memory pool, and waits until memory can be allocated.
A maximum wait time (timeout) can be set in tmout. The time unit for tmout is the same as that for system time (= 1 ms). If the tmout time elapses before the wait release condition is met (memory space does not become available), the system call terminates, returning timeout error code E_TMOUT.
When TMO_POL＝0 is set in tmout, this means 0 was specified as the timeout value, and E_TMOUT is returned without entering WAITInG state even if memory cannot be allocated.
When TMO_FEVR＝(-1) is set in tmout, this means infinity was specified as the timeout value, and the task continues to wait for memory allocation without timing out.
The queuing order of tasks waiting for memory block allocation is either FIFO or task priority order, depending on the memory pool attribute.
tk_get_mpf_u - Get Fixed-size Memory Block (Microseconds)
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (mpfid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the fixed-size memory pool specified in mpfid does not exist) |
| E_PAR | Parameter error (tmout_u ≦ (-2)) |
| E_DLT | The object being waited for was deleted (the memory pool was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Related Service Profile Items
Only when all the service profile items below are set to be effective, this system call can be used.
Description
This system call takes 64-bit tmout_u in microseconds instead of the parameter tmout of tk_get_mpf.
The specification of this system call is same as that of tk_get_mpf, except that the parameter is replaced with tmout_u. For more details, see the description of tk_get_mpf.
tk_rel_mpf - Release Fixed-size Memory Block
Description
Returns the memory block specified in blf to the fixed-size memory pool specified in mpfid.
Executing tk_rel_mpf may enable memory block acquisition by another task waiting to allocate memory from the memory pool specified in mpfid, releasing the WAITING state of that task.
When a memory block is returned to a fixed-size memory pool, it must be the same fixed-size memory pool from which the block was allocated. If an attempt to return a memory block to a different memory pool is detected, error code E_PAR is returned. Whether this error detection is performed or not is implementation-dependent.
tk_ref_mpf - Reference Fixed-size Memory Pool Status
Return Parameter
pk_rmpf Detail:
Description
References the status of the fixed-size memory pool specified in mpfid, passing in return parameters the current free block count (frbcnt), waiting task ID (wtsk), and extended information (exinf).
wtsk indicates the ID of a task waiting for memory block allocation from this fixed-size memory pool. If multiple tasks are waiting for the fixed-size memory pool, the ID of the task at the head of the queue is returned. If there are no waiting tasks, wtsk = 0 is returned.
If the fixed-size memory pool specified with tk_ref_mpf does not exist, error code E_NOEXS is returned.
At least one of frbcnt = 0 and wtsk = 0 is always true for this system call.
Additional Notes
Whereas frsz returned by tk_ref_mpl gives the total free memory size in bytes, frbcnt returned by tk_ref_mpf gives the number of unused memory blocks.
Variable-size Memory Pool
A variable-size memory pool is an object for dynamically managing memory blocks of any size. Functions are provided for creating and deleting a variable-size memory pool, allocating and returning memory blocks in a variable-size memory pool, and referencing the status of a variable-size memory pool. A variable-size memory pool is an object identified by an ID number. The ID number for the variable-size memory pool is called a variable-size memory pool ID.
A variable-size memory pool has a memory space used as the variable-size memory pool (called a variable-size memory pool area or simply memory pool area), and a queue for tasks waiting for memory block allocation. A task wanting to allocate a memory block from a variable-size memory pool that lacks sufficient available memory space goes to WAITING state for variable-size memory block until memory blocks are returned to the pool. A task in this state is put in the task queue of the variable-size memory pool.
| Additional Notes |
|---|---|
When tasks are waiting for memory block allocation from a variable-size memory pool, they are served in queued order. If, for example, Task A requesting a 400-byte memory block from a variable-size memory pool is queued along with Task B requesting a 100-byte block, in A-B order, then even if 200-byte block of space are free, Task B is made to wait until Task A has acquired the requested memory block. |
tk_cre_mpl - Create Variable-size Memory Pool
Parameter
| CONST T_CMPL* |
pk_cmpl
| Packet to Create Memory Pool | Information about the variable-size memory pool to be created |
pk_cmpl Detail:
| void* |
exinf
| Extended Information | Extended information |
| ATR |
mplatr
| Memory Pool Attribute | Memory pool attribute |
| SZ |
mplsz
| Memory Pool Size | Memory pool size (in bytes) |
| UB |
dsname[8]
| DS Object name | DS object name |
| void* |
bufptr
| Buffer Pointer | User buffer pointer |
| (Other implementation-dependent parameters may be added beyond this point.) | |||
Error Code
| E_NOMEM | Insufficient memory (memory for control block or memory pool area cannot be allocated) |
| E_LIMIT | Number of variable-size memory pools exceeds the system limit |
| E_RSATR | Reserved attribute (mplatr is invalid or cannot be used) |
| E_PAR | Parameter error :(pk_cmpl is invalid, mplsz is negative or invalid, or bufptr is illegal) |
Related Service Profile Items
| TK_SUPPORT_USERBUF | Support for specifying TA_USERBUF for variable-size memory pool attribute |
| TK_SUPPORT_AUTOBUF | Automatic buffer allocation is supported (by not specifying TA_USERBUF to variable-size memory pool attribute) |
| TK_SUPPORT_DISWAI | Support for specifying TA_NODISWAI (reject request to disable wait) to variable-size memory pool attribute |
| TK_SUPPORT_DSNAME | Support for specifying TA_DSNAME for variable-size memory pool attribute |
Description
Creates a variable-size memory pool, assigning to it a variable-size memory pool ID. This system call allocates a memory space for use as a memory pool, based on the information in parameter mplsz, and assigns a control block to the memory pool.
exinf can be used freely by the user to set miscellaneous information about the created memory pool. The information set in this parameter can be referenced by tk_ref_mpl. If a larger area is needed for indicating user information, or if the information may need to be changed after the message buffer is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The kernel pays no attention to the contents of exinf.
mplatr indicates system attributes in its lower bits and implementation-dependent attributes in its higher bits. The system attribute part of mplatr is as follows.
mplatr := (TA_TFIFO || TA_TPRI) | [TA_DSNAME] | [TA_USERBUF] | [TA_NODISWAI]
| (TA_RNG0 || TA_RNG1 || TA_RNG2 || TA_RNG3)
| TA_TFIFO | Tasks waiting for memory allocation are queued in FIFO order |
| TA_TPRI | Tasks waiting for memory allocation are queued in priority order |
| TA_RNGn | Memory access privilege is set to protection level n |
| TA_DSNAME | Specifies DS object name |
| TA_USERBUF | Support of user-specified memory area as memory pool area |
| TA_NODISWAI | Disabling of wait by tk_dis_wai is prohibited |
#define TA_TFIFO 0x00000000 /* manage task queue by FIFO */ #define TA_TPRI 0x00000001 /* manage task queue by priority */ #define TA_USERBUF 0x00000020 /* Use user-specified buffer */ #define TA_DSNAME 0x00000040 /* DS object name */ #define TA_NODISWAI 0x00000080 /* reject request to disable wait */ #define TA_RNG0 0x00000000 /* protection level 0 */ #define TA_RNG1 0x00000100 /* protection level 1 */ #define TA_RNG2 0x00000200 /* protection level 2 */ #define TA_RNG3 0x00000300 /* protection level 3 */
The queuing order of tasks waiting for memory block allocation from a memory pool can be specified in TA_TFIFO or TA_TPRI. If the attribute is TA_TFIFO, tasks are ordered by FIFO, whereas TA_TPRI specifies queuing of tasks in order of their priority setting.
When tasks are queued waiting for memory allocation, memory is allocated in the order of queuing. Even if other tasks in the queue are requesting smaller amounts of memory than the task at the head of the queue, they do not acquire memory blocks before the first task. If, for example, Task A requesting a 400-byte memory block from a variable-size memory pool is queued along with Task B requesting a 100-byte block, in A-B order, then even if 200-byte block of space are freed by tk_rel_mpl of another task, Task B is made to wait until Task A has acquired the requested memory block.
TA_RNGn is specified to limit the protection levels from which memory can be accessed. Only tasks running at the same or higher protection level than the one specified can access the allocated memory. If a task running at a lower protection level attempts an access, a CPU protection fault exception is raised. For example, memory allocated from a memory pool specified as TA_RNG1 can be accessed by tasks running at levels TA_RNG0 or TA_RNG1, but not by tasks running at levels TA_RNG2 or TA_RNG3.
When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used to identify objects by debugger, and it is handled only by T-Kernel/DS API, td_ref_dsname and td_set_dsname. For more details, see the description of td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.
Additional Notes
If the task at the head of the queue waiting for memory allocation has its WAITING state forcibly released, or if a different task becomes the first in the queue as a result of a change in task priority, memory allocation is attempted to that task. If memory can be allocated, the WAITInG state of that task is released. In this way it is possible under some circumstances for memory allocation to take place and task WAITING state to be released even when memory is not released by tk_rel_mpl.
For the sake of portability, the TA_RNGn attribute must be accepted even by a system with a single CPU's operating mode. It is possible, for example, to handle all TA_RNGn as equivalent to TA_RNG0, but error must not be returned.
Rationale for the Specification
The capability of creating multiple variable-size memory pools can be used for memory allocation as needed for error handling or in emergent situations in programming, etc.
Porting Guideline
The T-Kernel 2.0 specification does not define TA_USERBUF and its associated notion of bufptr. So if this feature is used, a modification is necessary to port the software to T-Kernel 2.0. However, if mplsz is properly set already, simply removing TA_USERBUF and bufptr will complete the modification for porting.
tk_del_mpl - Delete Variable-size Memory Pool
Description
Deletes the variable-size memory pool specified in mplid.
No check or notification is made as to whether there are tasks using memory allocated from this memory pool. The system call completes normally even if not all blocks have been returned to the pool.
Issuing this system call releases the memory pool ID number, the control block memory space and the memory pool space itself.
This system call completes normally even if there are tasks waiting for memory block allocation from the deleted memory pool, but error code E_DLT is returned to the tasks in WAITING state.
tk_get_mpl - Get Variable-size Memory Block
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (mplid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the variable-size memory pool specified in mplid does not exist) |
| E_PAR | Parameter error (tmout ≦ (-2)) |
| E_DLT | The object being waited for was deleted (the memory pool was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Description
Gets a memory block of size blksz (bytes) from the variable-size memory pool specified in mplid. The start address of the allocated memory block is returned in blk.
The allocated memory is not cleared to zero, and the memory block contents are indeterminate.
If memory cannot be allocated, the task issuing this system call enters WAITING state.
A maximum wait time (timeout) can be set in tmout. The time unit for tmout is the same as that for system time (= 1 ms). If the tmout time elapses before the wait release condition is met (memory space does not become available), the system call terminates, returning timeout error code E_TMOUT.
When TMO_POL＝0 is set in tmout, this means 0 was specified as the timeout value, and E_TMOUT is returned without entering WAITING state even if memory cannot be allocated.
When TMO_FEVR＝(-1) is set in tmout, this means infinity was specified as the timeout value, and the task continues to wait for memory allocation without timing out.
The queuing order of tasks waiting for memory block allocation is either FIFO or task priority order, depending on the memory pool attribute.
tk_get_mpl_u - Get Variable-size Memory Block (Microseconds)
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (mplid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the variable-size memory pool specified in mplid does not exist) |
| E_PAR | Parameter error (tmout_u ≦ (-2)) |
| E_DLT | The object being waited for was deleted (the memory pool was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Related Service Profile Items
Only when all the service profile items below are set to be effective, this system call can be used.
Description
This system call takes 64-bit tmout_u in microseconds instead of the parameter tmout of tk_get_mpl.
The specification of this system call is same as that of tk_get_mpl, except that the parameter is replaced with tmout_u. For more details, see the description of tk_get_mpl.
tk_rel_mpl - Release Variable-size Memory Block
Description
Returns the memory block specified in blk to the variable-size memory pool specified in mplid.
Executing tk_rel_mpl may enable memory block acquisition by another task waiting to allocate memory from the memory pool specified in mplid, releasing the WAITING state of that task.
When a memory block is returned to a variable-size memory pool, it must be the same variable-size memory pool from which the block was allocated. If an attempt to return a memory block to a different memory pool is detected, error code E_PAR is returned. Whether this error detection is performed or not is implementation-dependent.
Additional Notes
When memory is returned to a variable-size memory pool in which multiple tasks are queued, multiple tasks may be released at the same time depending on the amount of memory returned and their requested memory size. The task precedence among tasks of the same priority after their WAITING state is released in such a case is the order in which they were queued.
tk_ref_mpl - Reference Variable-size Memory Pool Status
Return Parameter
pk_rmpl Detail:
Description
References the status of the variable-size memory pool specified in mplid, passing in return parameters the total size of free space (frsz), the maximum size of memory immediately available (maxsz), the waiting task ID (wtsk), and extended information (exinf).
wtsk indicates the ID of a task waiting for memory block allocation from this variable-size memory pool. If multiple tasks are waiting for the variable-size memory pool, the ID of the task at the head of the queue is returned. If there are no waiting tasks, wtsk = 0 is returned.
If the variable-size memory pool specified with tk_ref_mpl does not exist, error code E_NOEXS is returned.