μT-Kernel 2.0 Specification
PrevμT-Kernel/SM FunctionsNext

Utility Functions

Utility functions are used commonly from general programs such as applications, middleware, and device drivers on the μT-Kernel.

Utility functions are provided as library functions or C language macros.

NoteDifference from μT-Kernel 1.0
 

New API introduced based on T-Kernel 2.0 specification

Set Object Name

API for setting object name is provided as C language macros. It can be called from a task-independent portion and while task dispatching and interrupts are disabled.

SetOBJNAME - Set Object Name

C Language Interface

#include <tk/tkernel.h>

void SetOBJNAME (void *exinf , CONST UB *name );

Parameter

void* exinf Extended InformationVariable to set as extended information
CONST UB* name Object NameObject name to be set

Return Parameter

None.

Error Code

None.

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESYES

Related Service Profile Items

None.

Description

Interprets the ASCII string of four or less characters specified in name as a single 32-bit data to store it in exinf.

This API is defined as a C language macro and exinf is not a pointer. Write a variable directly.

Additional Notes

This API can assign the ASCII string names (such as task name) to the kernel objects, and the names are stored in the extended information exinf of the kernel objects. It is possible to list the object names set by this API by printing the information in exinf as ASCII string using the debugger, etc. to investigate the state of the kernel objects.

Example 7. Sample Usage of SetOBJNAME

T_CTSK  ctsk;
...
/* Set the object name "TEST" for the task ctsk */
SetOBJNAME(ctsk.exinf, "TEST");
task_id = tk_cre_tsk ( &ctsk );

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

Fast Lock and Multi-lock Libraries

Fast lock and multi-lock libraries are for performing exclusion control faster between multiple tasks in the device drivers or subsystems. In order to perform the exclusion control, while semaphore or mutex can be used, fast lock is implemented as the μT-Kernel/SM library functions that processes the lock acquisition operation with specially higher speed when the task is not queued.

Fast lock and multi-lock libraries are for performing exclusion control quicker than semaphore and mutexes between multiple tasks in the device drivers or subsystems. Fast multi-lock is one object built by combining independent binary semaphores for mutual exclusion control. The number of binary semaphores is the number of the bits in UINT data type, and each binary semaphore is distinguished by the number from 0 to (bit width of UINT) - 1.

For example, when exclusion control is performed at ten locations, one fast multi-lock can be created and then the binary semaphores with lock numbers from 0 to 9 can be used to perform exclusion control while ten fast locks can be used. While using ten fast locks bring faster result, the total required resources is lower when the fast multi-lock is used.

NoteAdditional Notes
 

Fast lock function is implemented by using counters that show the lock states and a semaphore. Fast multi-lock function is implemented by using a counter that shows the lock states and event flags. When the invoking task is not queued at the lock acquisition, it performs faster than the usual semaphores or event flags because only counter operation is performed. On the other hand, when the invoking task is queued at lock acquisition, it is not necessarily faster than the usual semaphores or event flags because it uses usual semaphores and event flags to manage transitions to waiting state or queues. Fast lock and multi-lock are effective when possibility of being queued is low due to mutual exclusion control.

NoteDifference from T-Kernel 2.0
 

In order to achieve efficient implementation on 16-bit CPU, the number of binary semaphores in a fast multi-lock has been reduced from 32 to one that will fit into the bit width of UINT data type.

NoteDifference from μT-Kernel 1.0
 

New API introduced based on T-Kernel 2.0 specification

CreateLock - Create Fast Lock

C Language Interface

#include <tk/tkernel.h>

ER ercd = CreateLock (FastLock *lock , CONST UB *name );

Parameter

FastLock* lock Control Block of FastLockControl block of fast lock
CONST UB* name Name of FastLockName of fast lock

Return Parameter

ER ercd Error CodeError code

Error Codes

E_OK Normal completion
E_NOMEM Insufficient memory (memory for control block cannot be allocated)
E_LIMIT Number of fast locks exceeds the system limit

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

None.

Description

Creates a fast lock.

lock is a structure to control a fast lock. name is the name of the fast lock and can be NULL.

Fast lock is a binary semaphore used for mutual exclusion control and is implemented to be operated as fast as possible.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

DeleteLock - Delete Fast Lock

C Language Interface

#include <tk/tkernel.h>

void DeleteLock (FastLock *lock );

Parameter

FastLock* lock Control Block of FastLockControl block of fast lock

Return Parameter

None.

Error Codes

None.

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

None.

Description

Deletes a fast lock.

Error detection is omitted for faster operation.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

Lock - Lock Fast Lock

C Language Interface

#include <tk/tkernel.h>

void Lock (FastLock *lock );

Parameter

FastLock* lock Control Block of FastLockControl block of fast lock

Return Parameter

None.

Error Codes

None.

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

None.

Description

Locks a fast lock.

If the lock is already locked, the invoking task goes to the waiting state and is put in the task queue until it is unlocked. Tasks are queued in the priority order.

Error detection is omitted for faster operation.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

Unlock - Unlock Fast Lock

C Language Interface

#include <tk/tkernel.h>

void Unlock (FastLock *lock );

Parameter

FastLock* lock Control Block of FastLockControl block of fast lock

Return Parameter

None.

Error Codes

None.

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

None.

Description

Unlocks a fast lock.

If there are tasks waiting for the fast lock, the first task in the task queue newly acquires the lock.

Error detection is omitted for faster operation.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

CreateMLock - Create Fast Multi-lock

C Language Interface

#include <tk/tkernel.h>

ER ercd = CreateMLock (FastMLock *lock , CONST UB *name );

Parameter

FastMLock* lock Control Block of FastMLockControl block of fast multi-lock
CONST UB* name Name of FastMLockName of fast multi-lock

Return Parameter

ER ercd Error CodeError code

Error Codes

E_OK Normal completion
E_NOMEM Insufficient memory (memory for control block cannot be allocated)
E_LIMIT Number of fast multi-locks exceeds the system limit

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

None.

Description

Creates a fast multi-lock.

lock is a structure to control a fast multi-lock. name is the name of the fast multi-lock and can be NULL.

Fast multi-lock is one object built by combining independent binary semaphores for mutual exclusion control, and is implemented for very fast execution. The number of binary semaphores is the number of the bits in UINT data type, and each binary semaphore is distinguished by the number from 0 to (bit width of UINT data type) - 1. For example, if UINT is 16 bits, a number from 0 to 15 can be used as lock number.

Difference from T-Kernel 2.0

In order to achieve efficient implementation on 16-bit CPU, the number of binary semaphores in a fast-lock has been reduced from 32 to one that will fit into the bit width of UINT data type.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

Porting Guideline

Be warned that the number of available lock numbers is now dependent on the bit width of UINT data type. For example, the number of binary semaphores can take the value from 0 to 15 in 16-bit environment.

DeleteMLock - Delete Fast Multi-lock

C Language Interface

#include <tk/tkernel.h>

ER ercd = DeleteMLock (FastMLock *lock );

Parameter

FastMLock* lock Control Block of FastMLockControl block of fast multi-lock

Return Parameter

ER ercd Error CodeError code

Error Codes

E_OK Normal completion
E_PAR Parameter error

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

None.

Description

Deletes a fast multi-lock.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

MLock - Lock Fast Multi-lock

C Language Interface

#include <tk/tkernel.h>

ER ercd = MLock (FastMLock *lock , INT no );

Parameter

FastMLock* lock Control Block of FastMLockControl block of fast multi-lock
INT no Lock NumberLock number

Return Parameter

ER ercd Error CodeError code

Error Codes

E_OK Normal completion
E_PAR Parameter error
E_DLT Waiting object was deleted
E_RLWAI Waiting state was forcibly released
E_CTX Context error

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

None.

Description

Locks a fast multi-lock.

no is the lock number and is from 0 to (the bit width of UINT data type) - 1. For example, if UINT is 16 bits, a number from 0 to 15 can be used as lock number.

If the lock is already locked with the same lock number, the invoking task goes to the waiting state and is put in the task queue until it is unlocked with the same lock number. Tasks are queued in the priority order.

Difference from T-Kernel 2.0

In order to achieve efficient implementation on 16-bit CPU, the number of binary semaphores in a fast-lock has been reduced from 32 to one that will fit into the bit width of UINT data type.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

Porting Guideline

Be warned that the number of available lock numbers is now dependent on the bit width of UINT data type. For example, the number of binary semaphores can take the value from 0 to 15 in 16-bit environment.

MLockTmo - Lock Fast Multi-lock (with Timeout)

C Language Interface

#include <tk/tkernel.h>

ER ercd = MLockTmo (FastMLock *lock , INT no , TMO tmout );

Parameter

FastMLock* lock Control Block of FastMLockControl block of fast multi-lock
INT no Lock NumberLock number
TMO tmout TimeoutTimeout (ms)

Return Parameter

ER ercd Error CodeError code

Error Codes

E_OK Normal completion
E_PAR Parameter error
E_DLT Waiting object was deleted
E_RLWAI Waiting state was forcibly released
E_TMOUT Timeout
E_CTX Context error

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

None.

Description

Locks a fast multi-lock with timeout.

This API is identical to MLock(), except that it can specify the timeout interval in tmout. If the lock cannot be acquired before the timeout interval specified in tmout has elapsed, E_TMOUT is returned.

Difference from T-Kernel 2.0

In order to achieve efficient implementation on 16-bit CPU, the number of binary semaphores in a fast-lock has been reduced from 32 to one that will fit into the bit width of UINT data type.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

Porting Guideline

Be warned that the number of available lock numbers is now dependent on the bit width of UINT data type. For example, the number of binary semaphores can take the value from 0 to 15 in 16-bit environment.

MLockTmo_u - Lock Fast Multi-lock (with Timeout, in Microseconds)

C Language Interface

#include <tk/tkernel.h>

ER ercd = MLockTmo_u (FastMLock *lock , INT no , TMO_U tmout_u );

Parameter

FastMLock* lock Control Block of FastMLockControl block of fast multi-lock
INT no Lock NumberLock number
TMO_U tmout_u TimeoutTimeout (in microseconds)

Return Parameter

ER ercd Error CodeError code

Error Codes

E_OK Normal completion
E_PAR Parameter error
E_DLT Waiting object was deleted
E_RLWAI Waiting state was forcibly released
E_TMOUT Timeout
E_CTX Context error

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

Locks a fast multi-lock with timeout in microseconds.

This API is identical to MLockTmo(), except that the timeout interval is specified with a 64-bit value in microseconds.

Difference from T-Kernel 2.0

In order to achieve efficient implementation on 16-bit CPU, the number of binary semaphores in a fast-lock has been reduced from 32 to one that will fit into the bit width of UINT data type.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

Porting Guideline

Be warned that the number of available lock numbers is now dependent on the bit width of UINT data type. For example, the number of binary semaphores can take the value from 0 to 15 in 16-bit environment.

MUnlock - Unlock Fast Multi-lock

C Language Interface

#include <tk/tkernel.h>

ER ercd = MUnlock (FastMLock *lock , INT no );

Parameter

FastMLock* lock Control Block of FastMLockControl block of fast multi-lock
INT no Lock NumberLock number

Return Parameter

ER ercd Error CodeError code

Error Codes

E_OK Normal completion

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Related Service Profile Items

None.

Description

Unlocks a fast multi-lock.

no is the lock number and is from 0 to (the bit width of UINT data type) - 1. For example, if UINT is 16 bits, a number from 0 to 15 can be used as lock number.

If there are tasks in the waiting state for the same lock number, the first task in the task queue newly acquires the lock.

Difference from T-Kernel 2.0

In order to achieve efficient implementation on 16-bit CPU, the number of binary semaphores in a fast-lock has been reduced from 32 to one that will fit into the bit width of UINT data type.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

Porting Guideline

Be warned that the number of available lock numbers is now dependent on the bit width of UINT data type. For example, the number of binary semaphores can take the value from 0 to 15 in 16-bit environment.

PrevHomeNext
Physical Timer FunctionsUpSubsystem and Device Driver Starting