μT-Kernel 2.0 Specification
Prev		Next

μT-Kernel/SM Functions

This chapter describes details of the functions provided by μT-Kernel System Manager (μT-Kernel/SM).

Overall Note and Supplement

	Overall Note and Supplement
	Error codes such as E_PAR, E_MACV, and E_NOMEM that can be returned in many situations are not described here always unless there is some special reason for doing so. Except where otherwise noted, extended SVC and libraries of μT-Kernel/SM cannot be called from a task-independent portion and while dispatching and interrupts are disabled. There may be some limitations, however, imposed by particular implementations (E_CTX). Extended SVC and libraries of μT-Kernel/SM cannot be invoked from a lower protection level than that at which T-Kernel/OS system calls can be invoked (lower than `TSVCLimit` )(E_OACV). Extended SVC and libraries of μT-Kernel/SM are reentrant except when a special explanation is given. Note that some functions perform mutual exclusion internally. Detection of error codes E_PAR, E_MACV, and E_CTX is implementation-dependent; these may not always be detected as error. For this reason, the service calls must not be invoked in such a way that these errors might occur.

Error codes such as E_PAR, E_MACV, and E_NOMEM that can be returned in many situations are not described here always unless there is some special reason for doing so.
Except where otherwise noted, extended SVC and libraries of μT-Kernel/SM cannot be called from a task-independent portion and while dispatching and interrupts are disabled. There may be some limitations, however, imposed by particular implementations (E_CTX).
Extended SVC and libraries of μT-Kernel/SM cannot be invoked from a lower protection level than that at which T-Kernel/OS system calls can be invoked (lower than TSVCLimit )(E_OACV).
Extended SVC and libraries of μT-Kernel/SM are reentrant except when a special explanation is given. Note that some functions perform mutual exclusion internally.
Detection of error codes E_PAR, E_MACV, and E_CTX is implementation-dependent; these may not always be detected as error. For this reason, the service calls must not be invoked in such a way that these errors might occur.

	Difference from T-Kernel 2.0
	Generally speaking, T-Kernel 2.0 calls for the implementation where APIs with the name tk_〜 is implemented as extended SVC, and other APIs are implemented as library or macro calls in principle. But μT-Kernel 2.0 does not standardize implementation method.

System Memory Management Functions

The system memory management functions manage all the memory (system memory) allocated dynamically by μT-Kernel. This includes memory used internally by μT-Kernel as well as task stacks, message buffers, and memory pools.

System memory is managed in memory block units. A block size is usually a page size defined in MMU, and assumed to be approximately 4 KB in the current implementation. A system that does not use an MMU can set any desired block size, but approximately same size as the MMU page size is recommended. Block size can be retrieved by calling tk_ref_smb.

System memory is allocated in the system space. μT-Kernel does not manage task space memory.

System memory management functions consist of the API for system memory operations that allocates and releases memory from the system memory, and the memory allocation libraries that manage memory through subdividing system memory obtained in blocks into smaller ones.

The system memory management functions are for use not only within μT-Kernel but also used by applications, subsystems, and device drivers.

System Memory Allocation

System memory allocation functions provide functions for allocating and releasing memory from the system memory and referring to the system memory information.

tk_get_smb - Allocate System Memory

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_get_smb (void **addr , SZ nblk , UINT attr );

Parameter

void**	`addr`	Pointer to Memory Start Address	Pointer to the area to return the start address of the allocated memory
SZ	`nblk`	Number of Block	Number of memory blocks to be allocated
UINT	`attr`	Attribute	Attribute for memory to be allocated

Return Parameter

ER	`ercd`	Error Code	Error code
void*	`addr`	Memory Start Address	Start address of the allocated memory

Error Code

E_OK	Normal completion
E_PAR	Parameter error ((`nblk`≦0) or `attr` is invalid)
E_NOMEM	Insufficient memory (system memory is insufficient)
E_MACV	Memory access privilege error (unable to write to `attr`)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

TK_VIRTUAL_MEMORY Memory block allocated with TA_NORESIDENT specification is non-resident.

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

TK_SUPPORT_SYSMEMBLK Support for system memory allocation

Description

Allocates a contiguous memory area having the size of the number of memory blocks specified in nblk, and having the attributes specified in attr. The start address of the allocated memory space is returned in addr.

The following attributes can be specified in attr:

attr := (TA_RNG0 || TA_RNG1 || TA_RNG2 || TA_RNG3) | [TA_NORESIDENT]

`TA_RNG0`	Specify the protect level 0 memory
`TA_RNG1`	Specify the protect level 1 memory
`TA_RNG2`	Specify the protect level 2 memory
`TA_RNG3`	Specify the protect level 3 memory
`TA_NORESIDENT`	Specify nonresident memory

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.

When TA_NORESIDENT is specified, the allocated memory becomes nonresident. In a system without MMU, the actual behavior is the same as the resident memory even if the nonresident memory attribute is specified, but an error is not returned.

If a negative value is specified in nblk or an unavailable attribute is specified in attr, the error code E_PAR is returned. When the write access to the memory (the area to return the start address of the allocated memory) pointed by addr is not allowed, the error code E_MACV is returned.

If the contiguous memory space for the number of blocks specified in nblk cannot be allocated, the error code E_NOMEM is returned. In this case, NULL is returned in the memory pointed by addr.

Additional Notes

In a system without MMU, the implementation cannot detect the access privilege error exception even if an access violates the memory protection level, which allows the access as normal. In consideration of program portability and expandability, it is recommended that the appropriate protection level for the protection levels of accessing tasks is specified for the memory to be allocated.

Difference from T-Kernel 2.0

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

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

tk_rel_smb - Release System Memory

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_rel_smb (void *addr );

Parameter

void* addr Memory Start Address Start address of memory to be released

Return Parameter

ER ercd Error Code Error code

Error Code

E_OK	Normal completion
E_PAR	Parameter error (invalid `addr`)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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_SYSMEMBLK Support for system memory allocation

Description

Releases the resident memory specified in addr. addr must be the address retrieved by tk_get_smb().

If the address specified by addr is deemed an illegal value, E_PAR is returned as error code. Specifically, E_PAR is returned when addr points at outside the memory area managed by μT-Kernel, or when trying to free a memory area already freed by tk_rel_smb(). Note, however, due to the restriction of implementations, there are cases when an error cannot be detected when addr is illegal, and in such cases, the correct behavior of the system as a whole is not guaranteed. Hence the validity of addr must be guaranteed by the caller.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

tk_ref_smb - Reference System Memory Block

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ref_smb (T_RSMB *pk_rsmb );

Parameter

T_RSMB* pk_rsmb Packet to Return System Memory Block information Pointer to the area to return the system memory information

Return Parameter

ER ercd Error Code Error code

pk_rsmb Detail:

SZ	`blksz`	Block Size	Block size (in bytes)
SZ	`total`	Total Block Count	Total block count
SZ	`free`	Free Block Count	Remaining free block count
(Other implementation-dependent parameters may be added beyond this point.)

Error Code

E_OK	Normal completion
E_MACV	Memory access privilege error (unable to write to `pk_rsmb`)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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_SYSMEMBLK Support for system memory allocation

Description

Gets information about system memory.

A system with the virtual memory can use a memory larger than the physical memory by allocating the nonresident memory. For this reason, total number of blocks or the number of remaining free blocks may not be uniquely determined. In such cases, the contents of total and free are implementation-dependent, but preferably they should be values such that free ÷ total gives a useful estimate of the remaining memory capacity.

Difference from T-Kernel 2.0

The data type of members, blksz and total and free, of T_RSMB has been changed from INT to SZ.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

Memory Allocation Library Functions

Memory allocation library is used to efficiently use memory by subdividing system memory obtained in blocks by tk_get_smb() into smaller ones.

System memory returned by tk_get_smb() is managed inside the memory allocation library, and the memory of the size requested from an application is allocated from that memory. If the free memory managed by the memory allocation library is smaller than the one requested from an application, additional memory is allocated by calling tk_get_smb() again.

On the other hand, when memory is returned from an application, if the entire memory block containing the returned memory becomes free (unallocated), that memory block is released by calling tk_rel_smb(). The strict timing, however, of allocating or releasing memory block is implementation-dependent.

Memory allocation library provides functions equivalent to malloc/calloc/realloc/free provided by C standard library. If a target memory is nonresident memory, its API has a name beginning with the letter V, and if a target memory is resident memory, its API has a name beginning with the letter K.

These memories are all allocated as memory with a protection level specified in TSVCLimit.

Vmalloc - Allocate Nonresident Memory

C Language Interface

#include <tk/tkernel.h>

void* Vmalloc (size_t size );

Parameter

size_t size Size Memory size to be allocated (in bytes)

Return Parameter

void* addr Memory Start Address Start address of the allocated memory

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

TK_VIRTUAL_MEMORY Allocated memory is non-resident.

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

TK_SUPPORT_MEMLIB Support of memory allocation library

Description

Allocates the nonresident memory size bytes and returns the start address of the allocated memory in addr.

When the specified size of memory cannot be allocated or 0 is specified in size, NULL is returned in addr.

APIs in the memory allocation library, including Vmalloc, cannot be called from a task-independent portion and while dispatch or interrupt is disabled. Such a call may lead to an undefined behavior including possible system failure, and the caller is responsible for guaranteeing the state on the call.

Additional Notes

Any value can be specified in size. Note that a larger memory size than the number of bytes specified in size may be allocated internally for allocating the management space, aligning the allocated memory address, or other reasons. For example, when the implementation specifies that the least allocatable memory size is 16 bytes and the alignment is 8-byte unit, 16-byte memory is allocated internally even if a value less than 16 bytes is specified in size. Similarly, 24-byte memory is allocated even if 20 bytes is specified in size.

Therefore, when comparing the entire system memory size used by the memory allocation library with the total memory size allocated by individual APIs in the memory allocation library, the former value may be larger.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

Vcalloc - Allocate Nonresident Memory

C Language Interface

#include <tk/tkernel.h>

void* Vcalloc (size_t nmemb , size_t size );

Parameter

size_t	`nmemb`	Number of Memory Block	Number of memory blocks to be allocated
size_t	`size`	Size	Memory block size to be allocated (in bytes)

Return Parameter

void* addr Memory Start Address Start address of the allocated memory

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

TK_VIRTUAL_MEMORY Allocated memory is non-resident.

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

TK_SUPPORT_MEMLIB Support of memory allocation library

Description

Allocates the specified number (nmemb) of contiguous memory blocks of the specified bytes (size), clears them with 0, then returns the start address of them in addr. This memory allocation operation is identical to allocating one memory block of the number of size * nmemb bytes. The allocated memory is nonresident memory.

When the specified number of memory blocks cannot be allocated or 0 is specified in nmemb or size, NULL is returned in addr.

APIs in the memory allocation library, including Vcalloc, cannot be called from a task-independent portion and while dispatch or interrupt is disabled. Such a call may lead to an undefined behavior including possible system failure, and the caller is responsible for guaranteeing the state on the call.

Additional Notes

A larger memory size than the number of size * nmemb bytes may be allocated internally. For more details, see the additional note for Vmalloc().

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

Vrealloc - Reallocate Nonresident Memory

C Language Interface

#include <tk/tkernel.h>

void* Vrealloc (void *ptr , size_t size );

Parameter

void*	`ptr`	Pointer to Memory	Memory address to be reallocated
size_t	`size`	Size	Reallocated memory size (in bytes)

Return Parameter

void* addr Memory Start Address Start address of the reallocated memory

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

TK_VIRTUAL_MEMORY Allocated memory is non-resident.

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

TK_SUPPORT_MEMLIB Support of memory allocation library

Description

Changes the size of the previously allocated nonresident memory specified in ptr to the size specified in size. At that time, reallocates the memory and returns the start address of the reallocated memory in addr.

Generally, addr results in different value from ptr because the memory start address is moved by reallocating the memory with resizing. The content of the reallocated memory is retained. To do so, the memory content is copied during the Vrealloc processing. The memory that becomes free by reallocation will be released.

The start address of the memory allocated previously by Vmalloc, Vcalloc, or Vrealloc must be specified in ptr. The caller must guarantee the validity of ptr.

If NULL is specified in ptr, only the new memory allocation is performed. This operation is identical to Vmalloc().

When the specified size of memory cannot be reallocated or 0 is specified in size, NULL is returned in addr. In this case, the memory specified by ptr is only released if a value other than NULL is specified in ptr. This operation is identical to Vfree().

APIs in the memory allocation library, including Vrealloc, cannot be called from a task-independent portion and while dispatch or interrupt is disabled. Such a call may lead to an undefined behavior including possible system failure, and the caller is responsible for guaranteeing the state on the call.

Additional Notes

The memory address returned in addr may be the same as ptr in some cases, for example, when the memory size becomes smaller than before by reallocation or when the reallocation is performed without moving the memory start address because an unallocated memory area was around the memory specified in ptr.

A larger memory size than the number of bytes specified in size may be allocated internally. For more details, see the additional note for Vmalloc().

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

Vfree - Release Nonresident Memory

C Language Interface

#include <tk/tkernel.h>

void Vfree (void *ptr );

Parameter

void* ptr Pointer to Memory Start address of memory to be released

Return Parameter

None.

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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_MEMLIB Support of memory allocation library

Description

Releases the nonresident memory specified in ptr.

The start address of the memory allocated previously by Vmalloc, Vcalloc, or Vrealloc must be specified in ptr. The caller must guarantee the validity of ptr.

APIs in the memory allocation libraries, including Vfree, cannot be called from a task-independent portion and while dispatch or interrupt is disabled. Such a call may lead to an undefined behavior including possible system failure, and the caller is responsible for guaranteeing the state on the call.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

Kmalloc - Allocate Resident Memory

C Language Interface

#include <tk/tkernel.h>

void* Kmalloc (size_t size );

Parameter

size_t size Size Memory size to be allocated (in bytes)

Return Parameter

void* addr Memory Start Address Start address of the allocated memory

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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_MEMLIB Support of memory allocation library

Description

Allocates the resident memory of bytes specified in size and returns the start address of the allocated memory in addr.

When the specified size of memory cannot be allocated or 0 is specified in size, NULL is returned in addr.

APIs in the memory allocation library, including Kmalloc, cannot be called from a task-independent portion and while dispatch or interrupt is disabled. Such a call may lead to an undefined behavior including possible system failure, and the caller is responsible for guaranteeing the state on the call.

Additional Notes

A larger memory size than the number of bytes specified in size may be allocated internally. For more details, see the additional note for Vmalloc().

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

Kcalloc - Allocate Resident Memory

C Language Interface

#include <tk/tkernel.h>

void* Kcalloc (size_t nmemb , size_t size );

Parameter

size_t	`nmemb`	Number of Memory Block	Number of memory blocks to be allocated
size_t	`size`	Size	Memory block size to be allocated (in bytes)

Return Parameter

void* addr Memory Start Address Start address of the allocated memory

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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_MEMLIB Support of memory allocation library

Description

When the specified number of memory blocks cannot be allocated or 0 is specified in nmemb or size, NULL is returned in addr.

APIs in the memory allocation libraries, including Kcalloc, cannot be called from a task-independent portion and while dispatch or interrupt is disabled. Such a call may lead to an undefined behavior including possible system failure, and the caller is responsible for guaranteeing the state on the call.

Additional Notes

A larger memory size than the number of size * nmemb bytes may be allocated internally. For more details, see the additional note for Vmalloc().

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

Krealloc - Reallocate Resident Memory

C Language Interface

#include <tk/tkernel.h>

void* Krealloc (void *ptr , size_t size );

Parameter

void*	`ptr`	Pointer to Memory	Memory address to be reallocated
size_t	`size`	Size	Reallocated memory size (in bytes)

Return Parameter

void* addr Memory Start Address Start address of the reallocated memory

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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_MEMLIB Support of memory allocation library

Description

Changes the size of the previously allocated resident memory specified in ptr to the size specified in size. At that time, reallocates the memory and returns the start address of the reallocated memory in addr.

Generally, addr results in different value from ptr because the memory start address is moved by reallocating the memory with resizing. The content of the reallocated memory is retained. To do so, the memory content is copied during the Krealloc processing. The memory that becomes free by reallocation will be released.

The start address of the memory allocated previously by Kmalloc, Kcalloc, or Krealloc must be specified in ptr. The caller must guarantee the validity of ptr.

If NULL is specified in ptr, only the new memory allocation is performed. This operation is identical to Kmalloc().

APIs in the memory allocation library, including Krealloc, cannot be called from a task-independent portion and while dispatch or interrupt is disabled. Such a call may lead to an undefined behavior including possible system failure, and the caller is responsible for guaranteeing the state on the call.

Additional Notes

A larger memory size than the number of bytes specified in size may be allocated internally. For more details, see the additional note for Vmalloc().

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

Kfree - Release Resident Memory

C Language Interface

#include <tk/tkernel.h>

void Kfree (void *ptr );

Parameter

void* ptr Pointer to Memory Start address of memory to be released

Return Parameter

None.

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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_MEMLIB Support of memory allocation library

Description

Releases the resident memory specified in ptr.

The start address of the memory allocated previously by Kmalloc, Kcalloc, or Krealloc must be specified in ptr. The caller must guarantee the validity of ptr.

APIs in the memory allocation library, including Kfree, cannot be called from a task-independent portion and while dispatch or interrupt is disabled. Such a call may lead to an undefined behavior including possible system failure, and the caller is responsible for guaranteeing the state on the call.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

Prev	Home	Next
Subsystem Management Functions		Address Space Management Functions