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.
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
Return Parameter
None.
Error Codes
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 );
Note that you need to add '\0' which indicates the end of the string if you would like to manipulate the string by C language functions.
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.
 | 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. |
CreateLock - Create Fast Lock
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.
DeleteLock - Delete Fast Lock
Return Parameter
None.
Error Codes
None.
Lock - Lock Fast Lock
Return Parameter
None.
Error Codes
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.
Unlock - Unlock Fast Lock
Return Parameter
None.
Error Codes
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.
CreateMLock - Create Fast Multi-lock
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.
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
Description
Deletes a fast multi-lock.
MLock - Lock Fast Multi-lock
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.
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)
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.
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, Microseconds)
Related Service Profile Items
Only when all the service profile items below are set to be effective, this API can be used.
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.
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
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.
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.