T-Kernel/SM Functions

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

NoteOverall Note and Supplement
 

  • There are two types of API names that are defined in T-Kernel/SM specification: one beginning with tk_ and others. As a general rule, APIs with a name beginning with tk_ are implemented in extended SVC, and other APIs are implemented as library functions (including in-line functions) or macros of the C language. APIs that are defined in T-Kernel/SM, however, are not called as "system call." The word "system call" refers to APIs that are defined in T-Kernel/OS or T-Kernel/DS.

  • Some libraries and macros call some extended SVC or system calls indirectly.

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

System Memory Management Functions

The system memory management functions are for managing 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 extended SVCs for system memory operation that allocate and release 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 in applications, subsystems, and device drivers. Use inside T-Kernel does not have to go through extended SVC; this choice is implementation-dependent.

System Memory Allocation

System memory allocation functions provide extended SVCs 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 , INT nblk , UINT attr );

Parameter

void** addr Pointer to Memory Start AddressPointer to the area to return the start address of the allocated memory
INT nblk Number of BlockNumber of memory blocks to be allocated
UINT attr AttributeAttribute for memory to be allocated

Return Parameter

ER ercd Error CodeError code
void* addr Memory Start AddressStart 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 portionQuasi-task portionTask-independent portion
YESYESNO

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.

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 AddressStart address of memory to be released

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_PAR Parameter error (invalid addr)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

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

If the address specified in addr is invalid, the error code E_PAR is returned. Specifically, when addr points at the space out of the memory range managed by T-Kernel or when the memory already released by tk_rel_smb() is released again, the error code E_PAR is returned. However, due to implementation constraints, an error may not be detected even if addr is invalid. In that case, the subsequent correct behavior is not guaranteed. The caller must guarantee the validity of addr.

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 informationPointer to the area to return the system memory information

Return Parameter

ER ercd Error CodeError code

pk_rsmb Detail:

INT blksz Block SizeBlock size (in bytes)
INT total Total Block CountTotal block count
INT free Free Block CountRemaining 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 portionQuasi-task portionTask-independent portion
YESYESNO

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.

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 SizeMemory size to be allocated (in bytes)

Return Parameter

void* addr Memory Start AddressStart address of the allocated memory

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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.

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 BlockNumber of memory blocks to be allocated
size_t size SizeMemory block size to be allocated (in bytes)

Return Parameter

void* addr Memory Start AddressStart address of the allocated memory

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

Vrealloc - Reallocate Nonresident Memory

C Language Interface

#include <tk/tkernel.h>

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

Parameter

void* ptr Pointer to MemoryMemory address to be reallocated
size_t size SizeReallocated memory size (in bytes)

Return Parameter

void* addr Memory Start AddressStart address of the reallocated memory

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

Vfree - Release Nonresident Memory

C Language Interface

#include <tk/tkernel.h>

void Vfree (void *ptr );

Parameter

void* ptr Pointer to MemoryStart address of memory to be released

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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.

Kmalloc - Allocate Resident Memory

C Language Interface

#include <tk/tkernel.h>

void* Kmalloc (size_t size );

Parameter

size_t size SizeMemory size to be allocated (in bytes)

Return Parameter

void* addr Memory Start AddressStart address of the allocated memory

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

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 BlockNumber of memory blocks to be allocated
size_t size SizeMemory block size to be allocated (in bytes)

Return Parameter

void* addr Memory Start AddressStart address of the allocated memory

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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 a resident 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 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().

Krealloc - Reallocate Resident Memory

C Language Interface

#include <tk/tkernel.h>

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

Parameter

void* ptr Pointer to MemoryMemory address to be reallocated
size_t size SizeReallocated memory size (in bytes)

Return Parameter

void* addr Memory Start AddressStart address of the reallocated memory

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

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 Kfree().

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

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

Kfree - Release Resident Memory

C Language Interface

#include <tk/tkernel.h>

void Kfree (void *ptr );

Parameter

void* ptr Pointer to MemoryStart address of memory to be released

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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.