μT-Kernel 3.0 Specification
Prev		Next

μT-Kernel/SM Functions

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

Overall Note and Supplement

	Overall Note and Supplement
	There are two types of API names that are defined in μT-Kernel/SM specification: ones beginning with 'tk_' and others. It is generally assumed that APIs with a name beginning with 'tk_' are implemented using extended SVC (a Subsystem Management Function), and other APIs are implemented as library functions (including in-line functions) or macros of the C language. However, μT-Kernel specification does not define the implementation of these APIs. So the developers are free to adopt different implementation methods. API implemented by libraries and macros may call extended SVCs 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.

There are two types of API names that are defined in μT-Kernel/SM specification: ones beginning with 'tk_' and others. It is generally assumed that APIs with a name beginning with 'tk_' are implemented using extended SVC (a Subsystem Management Function), and other APIs are implemented as library functions (including in-line functions) or macros of the C language. However, μT-Kernel specification does not define the implementation of these APIs. So the developers are free to adopt different implementation methods. API implemented by libraries and macros may call extended SVCs 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.

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 management functions include memory allocation libraries that manage memory through subdividing system memory into smaller blocks.

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

Memory Allocation Library Functions

Memory allocation library provides functions equivalent to malloc/calloc/realloc/free provided by C standard library.

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

Kmalloc - Allocate 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 API can be used.

TK_SUPPORT_MEMLIB Support of memory allocation library

Description

Allocates the 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

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 due to 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 an 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.

Kcalloc - Allocate Memory and Clear

C Language Interface

#include <tk/tkernel.h>

void* Kcalloc(size_t nmemb, size_t size);

Parameter

size_t	`nmemb`	Number of Memory Blocks	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 API 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.

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

Krealloc - Reallocate 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 API can be used.

TK_SUPPORT_MEMLIB Support of memory allocation library

Description

Changes the size of the previously allocated 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 Kmalloc.

Kfree - Release 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 API can be used.

TK_SUPPORT_MEMLIB Support of memory allocation library

Description

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

Prev	Home	Next
Subsystem Management Functions		Device Management Functions