System Management Functions
System management functions sets and references system states. Functions are provided for rotating task precedence in a queue, getting the ID of the task in RUNNING state, disabling and enabling task dispatching, referencing context and system states, setting low-power mode, and referencing the T-Kernel version.
tk_rot_rdq - Rotate Ready Queue
Description
Rotates the precedence among tasks having the priority specified in tskpri. This system call changes the precedence of tasks in RUN or READY state having the specified priority, so that the task with the highest precedence among those tasks is given the lowest precedence.
By setting tskpri = TPRI_RUN = 0, this system call rotates the precedence of tasks having the priority level of the task currently in RUNNING state. When tk_rot_rdq is called from an ordinary task, it rotates the precedence of tasks having the same priority as the invoking task. When calling from a cyclic handler or other task-independent portion, it is also possible to call tk_rot_rdq (tskpri = TPRI_RUN).
Additional Notes
If there are no tasks in a run state having the specified priority, or only one such task, the system call completes normally with no operation (no error code is returned).
When this system call is issued in dispatch enabled state, specifying as the priority either TPRI_RUN or the current priority of the invoking task, the precedence of the invoking task will be the lowest among tasks of the same priority. This system call can therefore be used to relinquish execution privilege.
In dispatch disabled state, the task with highest precedence among tasks of the same priority is not always the currently executing task. The precedence of the invoking task will therefore not always become the lowest among tasks having the same priority when the above method is used in dispatch disabled state.
Examples of tk_rot_rdq execution are given in Figure 5 and Figure 6. When this system call is issued in the state shown in Figure 5 specifying tskpri = 2, the new precedence order becomes that in Figure 6, and Task C becomes the executing task.
tk_get_tid - Get Task Identifier
Parameter
None.
Error Codes
None.
Description
Gets the ID number of the task currently in RUNNING state. Unless the task-independent portion is executing, the current RUNNING state task will be the invoking task.
If there is no task currently in RUNNING state, 0 is returned.
Additional Notes
The task ID returned by tk_get_tid is identical to runtskid returned by tk_ref_sys.
tk_dis_dsp - Disable Dispatch
Parameter
None.
Description
Disables task dispatching. Dispatch disabled state remains in effect until tk_ena_dsp is called enabling task dispatching. While dispatching is disabled, the invoking task does not change from RUNNING state to READY state or to WAITING state. External interrupts, however, are still enabled, so even in dispatch disabled state an interrupt handler can be started. In dispatch disabled state, the running task can be preempted by an interrupt handler, but not by another task.
The specific operations during dispatch disabled state are as follows.
Even if a system call issued from an interrupt handler or by the task that called tk_dis_dsp results in a task going to READY state with a higher priority than the task that called tk_dis_dsp, that task will not be dispatched. Dispatching of the higher-priority task is delayed until dispatch disabled state ends.
If the task that called tk_dis_dsp issues a system call that may cause the invoking task to be put in WAITING state (e.g., tk_slp_tsk or tk_wai_sem), error code E_CTX is returned.
When system status is referenced by tk_ref_sys, TSS_DDSP is returned in
sysstat.
If tk_dis_dsp is called for a task already in dispatch disabled state, that state continues with no error code returned. No matter how many times tk_dis_dsp is called, calling tk_ena_dsp just one time is enough to enable dispatching again. The sophisticated operation when the pair of system calls tk_dis_dsp and tk_ena_dsp are used in a nested manner must therefore be managed by the user as necessary.
Additional Notes
A task in RUNNING state cannot go to DORMANT state or NON-EXISTENT state while dispatching is disabled. If tk_ext_tsk or tk_exd_tsk is called for a task in RUNNING state while interrupts or dispatching is disabled, error code E_CTX is detected. Since, however, tk_ext_tsk and tk_exd_tsk are system calls that do not return to their original context, such errors are not passed in return parameters by these system calls.
tk_ena_dsp - Enable Dispatch
Parameter
None.
Description
Enables task dispatching. This system call cancels the disabling of dispatching by the tk_dis_dsp system call.
If tk_ena_dsp is called from a task not in dispatch disabled state, the dispatch enabled state continues and no error code is returned.
tk_ref_sys - Reference System Status
Return Parameter
pk_rsys Detail:
Description
Gets the current system execution status, passing in return parameters such information as the dispatch disabled state and whether a task-independent portion is executing.
The following values are returned in sysstat.
sysstat := ( TSS_TSK | [TSS_DDSP] | [TSS_DINT] )
|| ( TSS_QTSK | [TSS_DDSP] | [TSS_DINT] )
|| ( TSS_INDP )
| TSS_TSK | 0 | Task portion is running |
| TSS_DDSP | 1 | Dispatch disabled |
| TSS_DINT | 2 | Interrupts disabled |
| TSS_INDP | 4 | Task-independent portion is running |
| TSS_QTSK | 8 | Quasi-task portion is running |
The ID of the task currently in RUNNING state is returned in runtskid, while schedtskid indicates the ID of the next task scheduled to go to RUNNING state. Normally runtskid = schedtskid, but this is not necessarily true if, for example, a higher-priority task was wakened during dispatch disabled state. If there is no such task, 0 is returned.
It must be possible to invoke this system call from an interrupt handler or time event handler.
Additional Notes
Depending on the kernel implementation, the information returned by tk_ref_sys is not necessarily guaranteed to be accurate at all times.
tk_set_pow - Set Power Mode
Related Service Profile Items
Only when all the service profile items below are set to be effective, this system call can be used.
Description
The following two power-saving functions are supported.
- ● Switching to low-power mode when the system is idle
When there are no tasks to be executed, the system switches to a low-power mode provided in hardware.
Low-power mode is a function for reducing power use during very short intervals, such as from one timer interrupt to the next. This is accomplished, for example, by lowering the CPU clock frequency. It does not require complicated mode-switching in software but is implemented mainly using hardware functionality.
- ● Automatic power-off
When the operator performs no operations for a certain length of time, the system automatically cuts the power and goes to suspended state. If there is a start request (interrupt, etc.) from a peripheral device or if the operator turns on the power, the system resumes from the state when the power was cut.
In the case of a power supply problem such as low battery, the system likewise cuts the power and goes to suspended state.
In suspended state, the power is cut to peripheral devices and circuits as well as to the CPU, but the main memory contents are retained.
tk_set_pow sets the low-power mode.
powmode:= ( TPW_DOSUSPEND || TPW_DISLOWPOW || TPW_ENALOWPOW )
#define TPW_DOSUSPEND 1 Suspended state #define TPW_DISLOWPOW 2 Switching to low-power mode disabled #define TPW_ENALOWPOW 3 Switching to low-power mode enabled (default)
TPW_DOSUSPEND
Execution of all tasks and handlers is stopped, peripheral circuits (timers, interrupt controllers, etc.) are stopped, and the power is cut (suspended). (off_pow is called.)
When power is turned back on, peripheral circuits are restarted, execution of all tasks and handlers is resumed, operations resume from the point before power was cut, and the system call returns.
If for some reason the resume processing fails, normal startup processing (for reset) is performed and the system boots fresh.
TPW_DISLOWPOW
Switching to low-power mode in the dispatcher is disabled.(low_pow is not called.)
TPW_ENALOWPOW
Switching to low-power mode in the dispatcher is enabled (low_pow is called).
The default at system startup is low-power mode enabled (TPW_ENALOWPOW).
Each time TPW_DISLOWPOW is specified, the request count is incremented. Low-power mode is enabled only when TPW_ENALOWPOW is requested for as many times as TPW_DISLOWPOW was requested. The maximum request count is implementation-dependent, but a count of at least 255 times must be possible.
Additional Notes
off_pow and low_pow are μT-Kernel/SM functions. For more details, see the Section called Power Management Functions in the Chapter called μT-Kernel/SM Functions.
μT-Kernel does not detect power supply problems or other factors for suspending the system. Actual suspension requires suspend processing in each of the peripheral devices (device drivers). The system is suspended not by calling tk_set_pow directly but by use of the μT-Kernel/SM suspend function.
tk_ref_ver - Reference Version Information
Return Parameter
pk_rver Detail:
Description
Gets information about the T-Kernel version in use, returning that information in the packet specified in pk_rver. The following information can be obtained.
maker is the maker code assigned to the developer who has implemented the version of μT-Kernel. maker format is described in [Figure 7].
prid is a number indicating the T-Kernel type. The prid field has the format shown in Figure 8.
Assignment of values to prid is left to the vendor who has implemented this version of μT-Kernel. Note, however, that this is the only number distinguishing product types, and that vendors should give careful thought to how they assign these numbers, doing so in a systematic way. In this way, the combination of maker and prid becomes a unique identifier of the kernel version.
The reference source code of μT-Kernel is provided from TRON Forum, and its maker and prid are as follows.
maker = 0x0000 prid = 0x0000
The upper 4 bits of spver give the TRON specification series. The lower 12 bits indicate the T-Kernel specification version implemented. The spver field has the format shown in Figure 9.
If, for example, a product conforms to the μT-Kernel specification Ver 3.01.xx, spver is as follows.
MAGIC = 0x6 (μT-Kernel) SpecVer = 0x301 (Ver 3.01) spver = 0x6301
If a product implements the draft version of μT-Kernel specification, that is,Ver 3.B0.xx draft specification, spver is as follows.
MAGIC = 0x6 (μT-Kernel) SpecVer = 0x3B0 (Ver 3.B0) spver = 0x63B0
- MAGIC:
Type of OS specification
- SpecVer:
The version of the specification that the kernel complies with. This is given as a three-digit packed-format BCD code. In the case of a draft version, the letter A, B, or C may appear in the second digit. In this case the corresponding hexadecimal form of A, B, or C is inserted.
prver is the version number of the T-Kernel implementation. The specific values assigned to prver are left to the T-Kernel implementing vendor to decide.
prno is a return parameter for use in indicating T-Kernel product management information, product number or the like. The specific meaning of values set in prno is left to the T-Kernel implementing vendor to decide.
Additional Notes
The format of the packet and structure members for getting version information is mostly uniform across each version of T-Kernel or μT-Kernel specification.
The value obtained by tk_ref_ver in SpecVer is the first three digits of the specification version number. The numbers after that indicate minor revisions such as those issued to correct misprints and the like, and are not obtained by tk_ref_ver. For the purpose of matching to the specification contents, the first three numbers of the specification version are sufficient.
A kernel implementing a draft version may have A, B, or C as the second number of SpecVer. It must be noted that in such cases the specification order of release may not correspond exactly to higher and lower SpecVer values. For example, specifications may be released in the following order: Ver 2.A1 → Ver 2.A2 → Ver 2.B1 → Ver 2.C1 → Ver 2.00 → Ver 2.01... In this example, when going from Ver 2.Cx to Ver 2.00, SpecVer goes from a higher to a lower value.