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
 

These functions were added in T-Kernel 2.0.

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

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESYES

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 be used to set a name (task name, etc.) for an individual object in T-Kernel as an ASCII string in the extended information exinf. When displaying the state of an object in the debugger, the object name set by this API can be shown by displaying the value in exinf as an ASCII string.

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

This API was added in T-Kernel 2.0.

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.

Among the fast lock and multi-lock libraries, the fast lock is a binary semaphore for mutual exclusion control faster than semaphores or mutexes. Fast multi-lock is one object built by combining 32 independent binary semaphores for mutual exclusion control each of which is distinguished by a lock number from 0 to 31.

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 1.0
 

These libraries were added in T-Kernel 2.0.

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

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

This API was added in T-Kernel 2.0.

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

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

Deletes a fast lock.

Error detection is omitted for faster operation.

Difference from T-Kernel 1.0

This API was added in T-Kernel 2.0.

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

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

This API was added in T-Kernel 2.0.

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

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

This API was added in T-Kernel 2.0.

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

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 a list of 32 independent binary semaphores used for mutual exclusion control and is implemented to be operated as fast as possible. Each of the 32 binary semaphores is specified by a lock number from 0 to 31.

Difference from T-Kernel 1.0

This API was added in T-Kernel 2.0.

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

Description

Deletes a fast multi-lock.

Difference from T-Kernel 1.0

This API was added in T-Kernel 2.0.

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

Description

Locks a fast multi-lock.

no is a lock number from 0 to 31.

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 1.0

This API was added in T-Kernel 2.0.

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

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 1.0

This API was added in T-Kernel 2.0.

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

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 1.0

This API was added in T-Kernel 2.0.

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

Description

Unlocks a fast multi-lock.

no is a lock number from 0 to 31.

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 1.0

This API was added in T-Kernel 2.0.