Everything

CHAPTER 9 SYSTEM STATE MANAGEMENT FUNCTIONS


This chapter describes the system management functions performed by the RI600V4.
9.1 Outline
The RI600V4's system status management function provides functions for referencing the system status such as the context type and CPU lock status, as well as functions for manipulating the system status such as ready queue rotation, scheduler activation, or the like.
Note, refer to "CHAPTER 13 SYSTEM DOWN" for system down (vsys_dwn, ivsys_dwn) and refer to "CHAPTER 16 SYSTEM INITIALIZATION" for starting of the RI600V4 (vsta_knl, ivsta_knl).
9.2 Rotate Task Precedence
Task precedence is rotated by issuing the following service call from the processing program.
- rot_rdq, irot_rdq
This service call re-queues the first task of the ready queue corresponding to the priority specified by parameter tskpri to the end of the queue to change the task execution order explicitly.
The following shows the status transition when this service call is used.
Figure 9-1 Rotate Task Precedence
The following describes an example for coding these service calls.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void cychdr (VP_INT exinf)          /*Cyclic handler*/
 {
     PRI     tskpri = 8;             /*Declares and initializes variable*/
 
     /* ......... */
 
     irot_rdq (tskpri);              /*Rotate task precedence*/
 
     /* ......... */
 
     return;                         /*Terminate cyclic handler*/
 }

Note 1 This service call does not perform queuing of rotation requests. If no task is queued to the ready queue corresponding to the relevant priority, therefore, no processing is performed but it is not handled as an error.
Note 2 Round-robin scheduling can be implemented by issuing this service call via a cyclic handler in a constant cycle.
Note 3 The ready queue is a hash table that uses priority as the key, and tasks that have entered an executable state (READY state or RUNNING state) are queued in FIFO order.
Therefore, the scheduler realizes the RI600V4's scheduling system by executing task detection processing from the highest priority level of the ready queue upon activation, and upon detection of queued tasks, giving the CPU use right to the first task of the proper priority level.
Note 4 When TPRI_SELF is specified as tskpri, the base priority of the invoking task is applied as the target priority of this service call.
As for a task which has locked mutexes, the current priority might be different from the base priority. In this case, even if the task issues this servie call specifying TPRI_SELF as parameter tskpri, the ready queue of the current priority that the invoking task belongs cannot be changed.
9.3 Reference Task ID in the RUNNING State
A RUNNING-state task is referenced by issuing the following service call from the processing program.
- get_tid, iget_tid
These service calls store the ID of a task in the RUNNING state in the area specified by parameter p_tskid.
The following describes an example for coding these service calls.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void inthdr (void)                  /*Interrupt handler*/
 {
     ID      p_tskid;                /*Declares variable*/
 
     /* ......... */
 
     iget_tid (&p_tskid);            /*Reference task ID in the RUNNING state*/
 
     /* ......... */
 
     return;                         /*Terminate interrupt handler*/
 }

Note This service call stores TSK_NONE in the area specified by parameter p_tskid if no tasks that have entered the RUNNING state exist.
9.4 Lock and Unlock the CPU
In the CPU locked state, the task scheduling is prohibited, and kernel interrupts are masked. Therefore, exclusive processing can be achieved for all processing programs except non-kernel interrupt handlers.
The following service calls moves to the CPU locked state.
- loc_cpu, iloc_cpu
These service calls transit the system to the CPU locked state.
The service calls that can be issued in the CPU locked state are limited to the one listed below.
Service Call that can be issued
Function
Terminate invoking task. (This service call transit the system to the CPU unlocked state.)
Lock the CPU.
Unlock the CPU.
Reference CPU state.
Reference dispatching state.
Reference contexts.
Reference dispatch pending state.
System down

The following service calls and ext_tsk release from the CPU locked state.
- unl_cpu, iunl_cpu
These service calls transit the system to the CPU unlocked state.
The following shows a processing flow when using the CPU locked state.
Figure 9-2 Lock the CPU
The following describes an example for coding "lock the CPU" and "unlock the CPU".
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     /* ......... */
 
     loc_cpu ();                     /*Lock the CPU*/
 
     /* ......... */                 /*CPU locked state*/
 
     unl_cpu ();                     /*Unlock the CPU*/
 
     /* ......... */
 }

Note 1 The CPU locked state changed by issuing loc_cpu or iloc_cpu must be cancelled before the processing program that issued this service call ends.
Note 2 The loc_cpu and iloc_cpu do not perform queuing of lock requests. If the system is in the CPU locked state, therefore, no processing is performed but it is not handled as an error.
Note 3 The unl_cpu and iunl_cpu do not perform queuing of unlock requests. If the system is in the CPU unlocked state, therefore, no processing is performed but it is not handled as an error
Note 4 The unl_cpu and iunl_cpu do not cancel the dispatching disabled state that was set by issuing dis_dsp.
Note 5 The base clock interrupt is masked during the CPU locked state. Therefore, time handled by the TIME MANAGEMENT FUNCTIONS may be delayed if the period of the CPU locked state becomes long.
Note 6 For kernel interrupts, refer to "10.1 Interrupt Type".
9.5 Reference CPU Locked State
It may be necessary to refer to current CPU locked state in functions that are called from two or more tasks and handlers. In this case, sns_loc is useful.
- sns_loc
This service call examines whether the system is in the CPU locked state or not. This service call returns TRUE when the system is in the CPU locked state, and return FALSE when the system is in the CPU unlocked state.
The following describes an example for coding this service call.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void CommonFunc ( void );
 void CommonFunc ( void )
 {
     BOOL ercd;                      /*Declares variable*/
 
     /* ......... */
 
     ercd = sns_loc ();              /*Reference CPU state*/
 
     if (ercd == TRUE) {
         /* ......... */             /*CPU locked state*/
     } else if (ercd == FALSE) {
         /* ......... */             /*CPU unlocked state*/
     }
 
     /* ......... */
 }

9.6 Disable and Enable Dispatching
In the dispatching disabled state, the task scheduling is prohibited. Therefore, exclusive processing can be achieved for all tasks.
The following service call moves to the dispatching disabled state. And also when PSW.IPL is changed to other than 0 by using chg_ims, the system shifts to the dispatching disabled state.
- dis_dsp
This service call transits the system to the dispatching disabled state.
The dispatching disabled state is cancelled by the following service call, ext_tsk, and chg_ims that changes PSW.IPL to 0.
- ena_dsp
This service call transits the system to the dispatching enabled state.
The following shows a processing flow when using the dispatching disabled state.
Figure 9-3 Disable Dispatching
The following describes an example for coding this service call.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     /* ......... */
 
     dis_dsp ();                     /*Disable dispatching*/
 
     /* ......... */                 /*Dispatching disabled state*/
 
     ena_dsp ();                     /*Enable dispatching*/
 
     /* ......... */
 }

Note 1 The dispatching disabled state must be cancelled before the task that issued dis_dsp moves to the DORMANT state.
Note 2 The dis_dsp does not perform queuing of lock requests. If the system is in the dispatching disabled state, therefore, no processing is performed but it is not handled as an error.
Note 3 The ena_dsp does not perform queuing of unlock requests. If the system is in the dispatching enabled state, therefore, no processing is performed but it is not handled as an error
Note 4 If a service call (such as wai_sem, wai_flg) that may move the status of the invoking task is issued while the dispatching disabled state, that service call returns E_CTX regardless of whether the required condition is immediately satisfied.
9.7 Reference Dispatching State
It may be necessary to refer to current dispatching disabled state in functions that are called from two or more tasks . In this case, sns_dsp is useful.
- sns_dsp
This service call examines whether the system is in the dispatching disabled state or not. This service call returns TRUE when the system is in the dispatching disabled state, and return FALSE when the system is in the dispatching enabled state.
The following describes an example for coding this service call.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void CommonFunc ( void );
 void CommonFunc ( void )
 {
     BOOL ercd;                      /*Declares variable*/
 
     /* ......... */
 
     ercd = sns_dsp ();              /*Reference dispatching state*/
 
     if (ercd == TRUE) {
         /* ......... */             /*Dispatching disabled state*/
     } else if (ercd == FALSE) {
         /* ......... */             /*Dispatching enabled state*/
     }
 
     /* ......... */
 }

9.8 Reference Context Type
It may be necessary to refer to current context type in functions that are called from two or more tasks and handlers. In this case, sns_ctx is useful.
- sns_ctx
This service call examines the context type of the processing program that issues this service call. This service call returns TRUE when the processing program is non-task context, and return FALSE when the processing program is task context.
The following describes an example for coding this service call.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void CommonFunc ( void );
 void CommonFunc ( void )
 {
     BOOL ercd;                      /*Declares variable*/
 
     /* ......... */
 
     ercd = sns_ctx ( );             /*Reference context type*/
 
     if (ercd == TRUE) {
         /* ......... */             /*Non-task contexts*/
     } else if (ercd == FALSE) {
         /* ......... */             /*Task contexts*/
     }
 
     /* ......... */
 }

9.9 Reference Dispatch Pending State
The state to fill either the following is called dispatch pending state.
- Dispatching disabled state
- CPU locked state
- PSW.IPL > 0, such as handlers
It may be necessary to refer to current dispatch pending state in functions that are called from two or more tasks and handlers. In this case, sns_dpn is useful.
- sns_dpn
This service call examines whether the system is in the dispatch pending state or not. This service call returns TRUE when the system is in the dispatch pending state, and return FALSE when the system is not in the dispatch pending state.
The following describes an example for coding this service call.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void CommonFunc ( void );
 void CommonFunc ( void )
 {
     BOOL ercd;                      /*Declares variable*/
 
     /* ......... */
 
     ercd = sns_dpn ();              /*Reference dispatch pending state*/
 
     if (ercd == TRUE) {
         /* ......... */             /*Dispatch pending state*/
     } else if (ercd == FALSE) {
         /* ......... */             /*Other state*/
     }
 
     /* ......... */
 }