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.
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.
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).
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.  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.
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.
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.
When system status is referenced by tk_ref_sys, TSS_DDSP is returned in
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.
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.
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 := ( TSS_TSK | [TSS_DDSP] | [TSS_DINT] ) || ( TSS_QTSK | [TSS_DDSP] | [TSS_DINT] ) || ( TSS_INDP )
|TSS_TSK||0||Task portion is running|
|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
schedtskid indicates the ID of the next task scheduled to go to RUNNING state. Normally
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.
The following two power-saving functions are supported.
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.
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)
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.
Switching to low-power mode in the dispatcher is disabled.(low_pow is not called.)
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.
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.
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 of the T-Kernel implementing vendor. The
maker field has the format shown in Figure 12.
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 up to the vendor implementing 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 that way the combination of
maker code and
prid becomes a unique identifier of the T-Kernel type.
The original version of T-Kernel is provided from T-Engine Forum, and its
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 14.
If, for example, a product conforms to the T-Kernel specification Ver 2.01.xx,
spver is as follows.
MAGIC = 0x7 (T-Kernel) SpecVer = 0x201 (Ver 2.01) spver = 0x7201
If a product implements the T-Kernel specification draft version Ver 2.B0.xx,
spver is as follows.
MAGIC = 0x7 (T-Kernel) SpecVer = 0x2B0 (Ver 2.B0) spver = 0x72B0
Type of OS specification
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.
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.
Task C executes next.