T-Kernel 2.0 Specification
Prev	T-Kernel/SM Functions	Next

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.

	Difference 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 Information	Variable to set as extended information
CONST UB*	`name`	Object Name	Object name to be set

Valid Context

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

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.

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.

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

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

	Difference 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 FastLock	Control block of fast lock
CONST UB*	`name`	Name of FastLock	Name of fast lock

Return Parameter

ER ercd Error Code Error 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 portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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 FastLock Control block of fast lock

Return Parameter

None

Error Codes

None

Valid Context

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

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 FastLock Control block of fast lock

Return Parameter

None

Error Codes

None

Valid Context

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

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 FastLock Control block of fast lock

Return Parameter

None

Error Codes

None

Valid Context

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

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 FastMLock	Control block of fast multi-lock
CONST UB*	`name`	Name of FastMLock	Name of fast multi-lock

Return Parameter

ER ercd Error Code Error 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 portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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 FastMLock Control block of fast multi-lock

Return Parameter

ER ercd Error Code Error code

Error Codes

E_OK	Normal completion
E_PAR	Parameter error

Valid Context

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

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 FastMLock	Control block of fast multi-lock
INT	`no`	Lock Number	Lock number

Return Parameter

ER ercd Error Code Error 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 portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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 FastMLock	Control block of fast multi-lock
INT	`no`	Lock Number	Lock number
TMO	`tmout`	Timeout	Timeout (ms)

Return Parameter

ER ercd Error Code Error 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 portion	Quasi-task portion	Task-independent portion
YES	YES	NO

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 FastMLock	Control block of fast multi-lock
INT	`no`	Lock Number	Lock number
TMO_U	`tmout_u`	Timeout	Timeout (in microseconds)

Return Parameter

ER ercd Error Code Error 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 portion	Quasi-task portion	Task-independent portion
YES	YES	NO

#include <tk/tkernel.h>

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

Parameter

FastMLock*	`lock`	Control Block of FastMLock	Control block of fast multi-lock
INT	`no`	Lock Number	Lock number

Return Parameter

ER ercd Error Code Error code

Error Codes

E_OK	Normal completion

Valid Context

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

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.

Prev	Home	Next
Physical Timer Functions	Up	Subsystem and Device Driver Starting