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.

The memory managed by the memory pool management functions is all in system space. There is no T-Kernel function for managing task space memory.

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.

NoteAdditional 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

C Language Interface

#include <tk/tkernel.h>

ID mpfid = tk_cre_mpf (CONST T_CMPF *pk_cmpf );

Parameter

CONST T_CMBX* pk_cmpf Packet to Create Memory PoolInformation about the fixed-size memory pool to be created

pk_cmpf Detail:

void* exinf Extended InformationExtended information
ATR mpfatr Memory Pool AttributeMemory pool attribute
SZ mpfcnt Memory Pool Block CountMemory pool block count
SZ blfsz Memory Block SizeFixed-size memory block size (in bytes)
UB dsname[8] DS Object nameDS object name
void* bufptr Buffer PointerUser buffer pointer
(Other implementation-dependent parameters may be added beyond this point.)

Return Parameter

ID mpfid Memory Pool IDFixed-size memory pool ID
orError CodeError code

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)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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.

mbxatr:= (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.

The created memory pool is in resident memory in system space. There is no T-Kernel function for creating a memory pool in task space.

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 without an MMU. It is possible, for example, to handle all TA_RNGn as equivalent to TA_RNG0, but error must not be returned.

Difference from T-Kernel 2.0

The specification of TA_USERBUF and bufptr have been added.

The data type of mpfcnt and blksz has been changed from INT to SZ.

Difference from μT-Kernel 1.0

The data type of mpfcnt and blksz has been changed from W to SZ.

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_del_mpf (ID mpfid );

Parameter

ID mpfid Memory Pool IDFixed-size memory pool ID

Return Parameter

ER ercd Error CodeError code

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)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_get_mpf (ID mpfid , void **p_blf , TMO tmout );

Parameter

ID mpfid Memory Pool IDFixed-size memory pool ID
void** p_blf Pointer to Block Start AddressPointer to the area to return the block start address blf
TMO tmout TimeoutTimeout (ms)

Return Parameter

ER ercd Error CodeError code
void* blf Block Start AddressMemory block start address

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)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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. 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.

Only positive values can be set in tmout. The time unit for tmout (time unit) is the same as that for system time (= 1 ms).

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)

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_get_mpf_u (ID mpfid , void **p_blf , TMO_U tmout_u );

Parameter

ID mpfid Memory Pool IDFixed-size memory pool ID
void** p_blf Pointer to Block Start AddressPointer to the area to return the block start address blf
TMO_U tmout_u TimeoutTimeout (in microseconds)

Return Parameter

ER ercd Error CodeError code
void* blf Block Start AddressMemory block start address

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)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_USEC Support instructions that can handle time in microsecond resolutions

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.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

tk_rel_mpf - Release Fixed-size Memory Block

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_rel_mpf (ID mpfid , void *blf );

Parameter

ID mpfid Memory Pool IDFixed-size memory pool ID
void* blf Block Start AddressMemory block start address

Return Parameter

ER ercd Error CodeError code

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 (blf is invalid, or block returned to wrong memory pool)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ref_mpf (ID mpfid , T_RMPF *pk_rmpf );

Parameter

ID mpfid Memory Pool IDFixed-size memory pool ID
T_RMPF* pk_rmpf Packet to Return Memory Pool StatusPointer to the area to return the memory pool status

Return Parameter

ER ercd Error CodeError code

pk_rmpf Detail:

void* exinf Extended InformationExtended information
ID wtsk Wait Task InformationWaiting task ID
SZ frbcnt Free Block CountFree block count
(Other implementation-dependent parameters may be added beyond this point.)

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 (invalid pk_rmpf)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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.

Difference from T-Kernel 2.0

The data type of member, frbcnt, of T_RMPF has been changed from INT to SZ.

Difference from μT-Kernel 1.0

The data type of member, frbcnt, of T_RMPF has been changed from W to SZ.

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.

NoteAdditional 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

C Language Interface

#include <tk/tkernel.h>

ID mplid = tk_cre_mpl (CONST T_CMPL *pk_cmpl );

Parameter

CONST T_CMPL* pk_cmpl Packet to Create Memory PoolInformation about the variable-size memory pool to be created

pk_cmpl Detail:

void* exinf Extended InformationExtended information
ATR mplatr Memory Pool AttributeMemory pool attribute
SZ mplsz Memory Pool SizeMemory pool size (in bytes)
UB dsname[8] DS Object nameDS object name
void* bufptr Buffer PointerUser buffer pointer
(Other implementation-dependent parameters may be added beyond this point.)

Return Parameter

ID mplid Memory Pool IDVariable-size memory pool ID
orError CodeError code

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)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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.

The created memory pool is in resident memory in system space. There is no T-Kernel function for creating a memory pool in task space.

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 without an MMU. 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.

Difference from T-Kernel 2.0

The specification of TA_USERBUF and bufptr have been added.

The data type of mplsz has been changed from INT to SZ.

Difference from μT-Kernel 1.0

The data type of mplsz has been changed from W to SZ.

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_del_mpl (ID mplid );

Parameter

ID mplid Memory Pool IDVariable-size memory pool ID

Return Parameter

ER ercd Error CodeError code

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)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_get_mpl (ID mplid , SZ blksz , void **p_blk , TMO tmout );

Parameter

ID mplid Memory Pool IDVariable-size memory pool ID
SZ blksz Memory Block SizeMemory block size (in bytes)
void** p_blk Pointer to Block Start AddressPointer to the area to return the block start address blk
TMO tmout TimeoutTimeout (ms)

Return Parameter

ER ercd Error CodeError code
void* blk Block Start AddressMemory block start address

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)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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. 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.

Only positive values can be set in tmout. The time unit for tmout (time unit) is the same as that for system time (= 1 ms).

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.

Difference from T-Kernel 2.0

The data type of blksz has been changed from INT to SZ.

Difference from μT-Kernel 1.0

The data type of blksz has been changed from W to SZ.

tk_get_mpl_u - Get Variable-size Memory Block (Microseconds)

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_get_mpl_u (ID mplid , SZ blksz , void **p_blk , TMO_U tmout_u );

Parameter

ID mplid Memory Pool IDVariable-size memory pool ID
SZ blksz Memory Block SizeMemory block size (in bytes)
void** p_blk Pointer to Block Start AddressPointer to the area to return the block start address blk
TMO_U tmout_u TimeoutTimeout (in microseconds)

Return Parameter

ER ercd Error CodeError code
void* blk Block Start AddressMemory block start address

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)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_USEC Support instructions that can handle time in microsecond resolutions

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.

Difference from T-Kernel 2.0

The data type of blksz has been changed from INT to SZ.

Difference from μT-Kernel 1.0

The data type of blksz has been changed from W to SZ.

tk_rel_mpl - Release Variable-size Memory Block

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_rel_mpl (ID mplid , void *blk );

Parameter

ID mplid Memory Pool IDVariable-size memory pool ID
void* blk Block Start AddressMemory block start address

Return Parameter

ER ercd Error CodeError code

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 (blk is invalid, or block returned to wrong memory pool)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ref_mpl (ID mplid , T_RMPL *pk_rmpl );

Parameter

ID mplid Memory Pool IDVariable-size memory pool ID
T_RMPL* pk_rmpl Packet to Return Memory Pool StatusPointer to the area to return the memory pool status

Return Parameter

ER ercd Error CodeError code

pk_rmpl Detail:

void* exinf Extended InformationExtended information
ID wtsk Wait Task InformationWaiting task ID
SZ frsz Free Memory SizeFree memory size (in bytes)
SZ maxsz Max Memory SizeMaximum memory space size (in bytes)
(Other implementation-dependent parameters may be added beyond this point.)

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 (invalid pk_rmpl)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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.

Difference from T-Kernel 2.0

The data type of member, frsz and maxsz, of T_RMPL has been changed from INT to SZ.

Difference from μT-Kernel 1.0

The data type of members, frsz and maxsz, of T_RMPL has been changed from W to SZ.