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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_rot_rdq (PRI tskpri );

Parameter

PRI tskpri Task PriorityTask priority

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_PAR Parameter error (tskpri is invalid)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESYES

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 10 and Figure 11. [1] When this system call is issued in the state shown in Figure 10 specifying tskpri = 2, the new precedence order becomes that in Figure 11, and Task C becomes the executing task.

Figure 10. Precedence Before Issuing tk_rot_rdq

Figure 11. Precedence After Issuing tk_rot_rdq (tskpri = 2)

tk_get_tid - Get Task Identifier

C Language Interface

#include <tk/tkernel.h>

ID tskid = tk_get_tid ( void );

Return Parameter

ID tskid Task IDID of the task in RUNNING state

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESYES

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_dis_dsp ( void );

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_CTX Context error (issued from task-independent portion)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ena_dsp ( void );

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_CTX Context error (issued from task-independent portion)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ref_sys (T_RSYS *pk_rsys );

Parameter

T_RSYS* pk_rsys Packet to Refer System StatusPointer to the area to return the system status

Return Parameter

ER ercd Error CodeError code

pk_rsys Detail:

UINT sysstat System StateSystem States
ID runtskid Running Task IDID of the task currently in RUNNING state
ID schedtskid Scheduled Task IDID of the task scheduled to run next
(Other implementation-dependent parameters may be added beyond this point.)

Error Code

E_OK Normal completion
E_PAR Parameter error (invalid pk_rsys)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESYES

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 1Dispatch disabled
TSS_DINT 2Interrupts disabled
TSS_INDP 4Task-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.

Difference from T-Kernel 2.0

The data type of member, sysstat, of T_RSYS has been changed from INT to UINT.

tk_set_pow - Set Power Mode

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_set_pow (UINT powmode );

Parameter

UINT powmode Power ModeLow-power mode

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_PAR Parameter error (value that cannot be used in powmode )
E_QOVR Low-power mode disable count overflow
E_OBJ TPW_ENALOWPOW was requested with low-power mode disable count at 0

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_LOWPOWER Support Power Management Functions

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ref_ver (T_RVER *pk_rver );

Parameter

T_RVER* pk_rver Packet to Return Version InformationPointer to the area to return the version information

Return Parameter

ER ercd Error CodeError code

pk_rver Detail:

UH maker Maker CodeT-Kernel maker code
UH prid Product IDT-Kernel identification number
UH spver Specification VersionSpecification version
UH prver Product VersionT-Kernel version
UH prno[4] Product NumberT-Kernel products management information

Error Code

E_OK Normal completion
E_PAR Parameter error (invalid pk_rver)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

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 12].

Figure 12. maker Format

prid is a number indicating the T-Kernel type. The prid field has the format shown in Figure 13.

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 original version of μT-Kernel is provided from T-Engine Forum, and its maker and prid are as follows.

maker   = 0x0000
prid    = 0x0000

Figure 13. prid Format

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

If, for example, a product conforms to the μT-Kernel specification Ver 2.01.xx, spver is as follows.

MAGIC   = 0x6           (μT-Kernel)
SpecVer = 0x201         (Ver 2.01)
spver   = 0x6201

If a product implements the draft version of μT-Kernel specification, that is,Ver 2.B0.xx draft specification, spver is as follows.

MAGIC   = 0x6           (μT-Kernel)
SpecVer = 0x2B0         (Ver 2.B0)
spver   = 0x62B0

Figure 14. spver Format

MAGIC:

Type of OS specification

0x0TRON common (TAD, etc.)
0x1reserved
0x2reserved
0x3reserved
0x4reserved
0x5reserved
0x6μT-Kernel
0x7T-Kernel

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 the various T-Kernel specifications.

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.

Notes

[1]

Task C executes next.