CHAPTER 12 SERVICE CALLS
This chapter describes the service calls supported by the RI78V4.
The service calls provided by the RI78V4 are service routines provided for indirectly manipulating the resources (tasks, semaphores, etc.) managed by the RI78V4 from a processing program. The service calls provided by the RI78V4 are listed below by management module.
slp_tsk,
tslp_tsk,
wup_tsk,
iwup_tsk,
can_wup,
ican_wup,
rel_wai,
irel_wai,
sus_tsk,
isus_tsk,
rsm_tsk,
irsm_tsk,
frsm_tsk,
ifrsm_tsk,
dly_tsk
rot_rdq,
irot_rdq,
get_tid,
iget_tid,
loc_cpu,
iloc_cpu,
unl_cpu,
iunl_cpu,
ena_dsp,
dis_dsp,
sns_ctx,
sns_loc,
sns_dsp,
sns_dpn
The method for calling service calls from processing programs coded either in C or assembly language is described below.
By calling using the same method as for normal C functions, service call parameters are handed over to the RI78V4 as arguments and the relevant processing is executed.
#include <kernel.h> /*Standard header file definition*/
#include <kernel_id.h> /*System information header file definition*/
void
func_task ( VP_INT exinf )
{
ER ercd; /*Declares variable*/
ID tskid = ID_tskA; /*Declares and initializes variable*/
ercd = act_tsk ( tskid ); /*Call service call*/
/* ............ */
ext_tsk ( ); /*Call service call*/
}
|
Note To call the service calls provided by the RI78V4 from a processing program, the header files listed below must be coded (include processing).
kernel.h: Standard header file (for C language)
kernel_id.h: System information header file (for C language)
By calling with the CALL instruction after performing the parameter settings according to the assembler's function calling rules, the service call parameters are handed over to the RI78V4 and the relevant processing is executed.
$INCLUDE (kernel.inc) ;Standard header file definition
$INCLUDE (kernel_id.inc) ;System information header file definition
.SECTION .bss, BSS
_ercd:
DS (2) ;Secures area for storing return value
.PUBLIC _func_task
.SECTION .textf, TEXTF
_func_task:
MOV A, #ID_tskA ;Parameter setting
CALL !!_act_tsk ;Call service call
MOVW !LOWW(_ercd), AX ;Return value setting
............
............
CALL !!_ext_tsk ;Call service call
BR !!__kernel_int_exit ;Jump to end of processing
|
Note To call the service calls provided by the RI78V4 from a processing program, the header files listed below must be coded (include processing).
kernel.inc: Standard header file (for assembly language)
kernel_id.inc: System information header file (for assembly language)
12.3 Amount of Stack Used by Service Calls
The RI78V4 saves/restores the values of registers PC, PSW and HL to/from the stack of the processing program that issued the relevant service call (task stack or system stack) during preprocessing/postprocessing of the service call.
The stack of the processing program that issued a service call is used for storing the service call arguments, and the system stack is used as the stack area required for executing internal processing of the service call.
When securing the task stack and system stack areas, the stack amount consumed upon issuance of a service call must therefore be considered.
The following lists the stack sizes required upon issuance of a service call.
snd_dtq, psnd_dtq, ipsnd_dtq, tsnd_dtq, fsnd_dtq, ifsnd_dtq, rcv_dtq, prcv_dtq, prcv_dtq, trcv_dtq, ref_dtq
Table 12-1 Stack Amount Used by Service Call (Unit: Bytes)
|
|
For Service Call Arguments
|
For Internal Processing by Program Issued the Service Call
|
For System Stack Internal Processing
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This section explains the data macros (for data types, current state, or the like) used when issuing a service call provided by the RI78V4.
The following lists the data types of parameters specified when issuing a service call.
Macro definition of the data type is performed by header file <ri_root>\include\os\types.h, which is called from standard header file <ri_root>\include\kernel.h.
|
|
|
|
|
|
|
|
|
|
|
Pointer to an unknown data type
|
|
|
|
|
|
|
|
Pointer to an unknown data type, or a signed 32-bit integer
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Service call operational mode
|
|
|
|
|
|
|
|
Relative time (unit: ticks)
|
Note The ID type definition in the RI78V4 differs from that of the uITRON 4.0 specification.
The following lists the status at the point acquired by issuing a service call (
ref_tsk,
ref_cyc).
Macro definition of the current status is performed by standard header file <ri_root>\include\kernel.h.
The following lists WAITING types acquired by issuing a service call (
ref_tsk).
Macro definition of the WAITING type is performed by standard header file <ri_root>\include\kernel.h.
|
|
|
|
|
|
|
A task enters this state if the counter for the task (registering the number of times the wakeup request has been issued) indicates 0x0 upon the issuance of a slp_tsk or tslp_tsk.
|
|
|
|
A task enters this state upon the issuance of a dly_tsk.
|
|
|
|
A task enters this state if it cannot acquire a resource from the relevant semaphore upon the issuance of a wai_sem or twai_sem.
|
|
|
|
A task enters this state if a relevant eventflag does not satisfy a predetermined condition upon the issuance of a wai_flg or twai_flg.
|
|
|
|
A task enters this state if cannot send a data to the relevant data queue upon the issuance of a snd_dtq or tsnd_dtq.
|
|
|
|
A task enters this state if cannot receive a data from the relevant data queue upon the issuance of a rcv_dtq or trcv_dtq.
|
|
|
|
A task enters this state if cannot receive a message from the relevant mailbox upon the issuance of a rcv_mbx or trcv_mbx.
|
|
|
|
A task enters this state if it cannot acquire a fixed-sized memory block from the relevant fixed-sized memory pool upon the issuance of a get_mpf or tget_mpf.
|
The following lists the values returned from service calls.
Macro definition of the return value is performed by standard header file <ri_root>\include\kernel.h.
|
|
|
|
|
|
|
|
|
|
|
Illegal service call use.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Polling failure or timeout.
|
|
|
|
|
|
|
|
|
12.4.5 Conditional compile macro
The RI78V4 header files are conditionally compiled by the following macro.
Table 12-6 Conditional Compile Macro
The following lists other macros used when issuing a service call.
Macro definition of other macros is performed by standard header file <ri_root>\include\kernel.h.
|
|
|
|
|
|
|
|
|
|
|
Initial priority of the task
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Current priority of the invoking task
|
|
|
|
|
|
|
|
|
This section explains the data structures (task state packet, semaphore state packet, or the like) used when issuing a service call provided by the RI78V4.
The following shows task state packet T_RTSK used when issuing
ref_tsk.
Definition of task state packet T_RTSK is performed by header file <ri_root>\include\os\{packet.h, packet.inc}, which is called from standard header file <ri_root>\include\{kernel.h, kernel.inc}.
typedef struct t_rtsk {
STAT tskstat; /*Task current state*/
PRI tskpri; /*Task current priority*/
PRI tskbpri; /*Reserved for future use*/
STAT tskwait; /*Reason for waiting*/
ID wobjid; /*Object ID number for which the task is waiting*/
TMO lefttmo; /*Reserved for future use*/
UINT actcnt; /*Activation request count*/
UINT wupcnt; /*Wakeup request count*/
UINT suscnt; /*Suspension count*/
} T_RTSK;
|
rtsk_tskstat .EQU 0x00 ;Task current state
rtsk_tskpri .EQU 0x02 ;Task current priority
rtsk_tskbpri .EQU 0x03 ;Reserved for future use
rtsk_tskwait .EQU 0x04 ;Reason for waiting
rtsk_wobjid .EQU 0x06 ;Object ID number for which the task is waiting
rtsk_lefttmo .EQU 0x08 ;Reserved for future use
rtsk_actcnt .EQU 0x0c ;Activation request count
rtsk_wupcnt .EQU 0x0e ;Wakeup request count
rtsk_suscnt .EQU 0x10 ;Suspension count
|
The following shows details on task state packet T_RTSK.
- tskstat, rtsk_tskstat
Stores the current state of the task.
TTS_WAS: WAITING-SUSPENDED state
- tskpri, rtsk_tskpri
Stores the current priority of the task.
- tskbpri, rtsk_tskbpri
System-reserved area.
- tskwait, rtsk_tskwait
Stores the reason for waiting.
TTW_NONE: Has not moved to the WAITING state.
TTW_SLP: A task enters this state if the counter for the task (registering the number of times the wakeup request has been issued) indicates 0x0 upon the issuance of a
slp_tsk or
tslp_tsk.
TTW_DLY:
A task enters this state upon the issuance of a dly_tsk.
TTW_SEM:
A task enters this state if it cannot acquire a resource from the relevant semaphore upon the issuance of a wai_sem or
twai_sem.
TTW_FLG:
A task enters this state if a relevant eventflag does not satisfy a predetermined condition upon the issuance of a wai_flg or
twai_flg.
TTW_SDTQ:
A task enters this state if cannot send a data to the relevant data queue upon the issuance of a snd_dtq or
tsnd_dtq.
TTW_RDTQ:
A task enters this state if cannot receive a data from the relevant data queue upon the issuance of a rcv_dtq or
trcv_dtq.
TTW_MBX:
A task enters this state if cannot receive a message from the relevant mailbox upon the issuance of a rcv_mbx or
trcv_mbx.
TTW_MPF:
A task enters this state if it cannot acquire a fixed-sized memory block from the relevant fixed-sized memory pool upon the issuance of a get_mpf or
tget_mpf.
- wobjid, rtsk_wobjid
Stores the object ID number for which the task is waiting.
- lefttmo, rtsk_lefttmo
System-reserved area.
- actcnt, rtsk_actcnt
Stores the activation request count of the task.
- wupcnt, rtsk_wupcnt
Stores the wakeup request count of the task.
- suscnt, rtsk_suscnt
Stores the suspention count of the task.
12.5.2 Semaphore state packet
The following shows semaphore state packet T_RSEM used when issuing
ref_sem.
Definition of semaphore state packet T_RSEM is performed by header file <ri_root>\include\os\{packet.h, packet.inc}, which is called from standard header file <ri_root>\include\{kernel.h, kernel.inc}.
typedef struct t_rsem {
ID wtskid; /*ID number of the task at the head of the wait queue*/
UINT semcnt; /*Current resource count*/
} T_RSEM;
|
rsem_wtskid .EQU 0x00 ;ID number of the task at the head of the wait queue
rsem_semcnt .EQU 0x02 ;Current resource count
|
The following shows details on semaphore state packet T_RSEM.
- wtskid, rsem_wtskid
Stores information whether a task is queued to the wait queue.
TSK_NONE: No applicable task.
Value: ID number of the task at the head of the wait queue
- semcnt, rsem_semcnt
Stores the current resource count of the semaphore.
12.5.3 Eventflag state packet
The following shows eventflag state packet T_RFLG used when issuing
ref_flg.
Definition of eventflag state packet T_RFLG is performed by header file <ri_root>\include\os\{packet.h, packet.inc}, which is called from standard header file <ri_root>\include\{kernel.h, kernel.inc}.
typedef struct t_rflg {
ID wtskid; /*ID number of the task at the head of the wait queue*/
FLGPTN flgptn; /*Current bit pattern*/
} T_RFLG;
|
rflg_wtskid .EQU 0x00 ;ID number of the task at the head of the wait queue
rflg_flgptn .EQU 0x02 ;Current bit pattern
|
The following shows details on eventflag state packet T_RFLG.
- wtskid, rflg_wtskid
Stores information whether a task is queued to the wait queue.
TSK_NONE: No applicable task.
Value: ID number of the task at the head of the wait queue
- flgptn, rflg_flgptn
Stores the current bit pattern of the eventflag.
12.5.4 Data queue state packet
The following shows data queue state packet T_RDTQ used when issuing
ref_dtq or
iref_dtq.
Definition of data queue state packet T_RDTQ is performed by header file <ri_root>\include\os\{packet.h, packet.inc}, which is called from standard header file <ri_root>\include\{kernel.h, kernel.inc}.
typedef struct t_rdtq {
ID stskid; /*Existence of tasks waiting for data transmission*/
ID rtskid; /*Existence of tasks waiting for data reception*/
UINT sdtqcnt; /*number of data elements in the data queue*/
} T_RDTQ;
|
rdtq_stskid .EQU 0x00 ; Existence of tasks waiting for data transmission
rdtq_rtskid .EQU 0x01 ; Existence of tasks waiting for data reception
rdtq_sdtqcnt .EQU 0x02 ; number of data elements in the data queue
|
The following shows details on data queue state packet T_RDTQ.
- stskid
Stores whether a task is queued to the transmission wait queue of the data queue.
TSK_NONE: No applicable task
Value: ID number of the task at the head of the wait queue
- rtskid
Stores whether a task is queued to the reception wait queue of the data queue.
TSK_NONE: No applicable task
Value: ID number of the task at the head of the wait queue
- sdtqcnt
Stores the number of data elements in data queue.
Definition of message packet T_MSG and T_MSG_PRI is performed by header file <ri_root>\include\types.h, which is called from standard header file <ri_root>\include\kernel.h.
[ Message packet for TA_MFIFO attribute ]
typedef struct t_msg {
struct t_msg __near *msgque; /*Reserved for future use*/
} T_MSG;
|
[ Message packet for TA_MPRI attribute ]
typedef struct t_msg_pri {
struct t_msg __near *msgque; /*Reserved for future use*/
PRI msgpri; /*Message priority*/
} T_MSG_PRI;
|
The following shows details on message packet T_MSG and T_MSG_PRI.
- msgque
System-reserved area.
- msgpri
Stores the priority of the message.
Note 1 In the RI78V4, a message having a smaller priority number is given a higher priority.
Note 2 Values that can be specified for the priority of a message are limited from 1 to 31.
12.5.6 Mailbox state packet
The following shows mailbox state packet T_RMBX used when issuing
ref_mbx.
Definition of mailbox state packet T_RMBX is performed by header file <ri_root>\include\os\{packet.h, packet.inc}, which is called from standard header file <ri_root>\include\{kernel.h, kernel.inc}.
typedef struct t_rmbx {
ID wtskid; /*ID number of the task at the head of the wait
queue*/
T_MSG __near *pk_msg; /*Start address of the message packet at the head
of the message queue*/
} T_RMBX;
|
rmbx_wtskid .EQU 0x00 ;ID number of the task at the head of the wait
;queue
rmbx_pk_msg .EQU 0x02 ;Start address of the message packet at the head
;of the message queue
|
The following shows details on mailbox state packet T_RMBX.
- wtskid, rmbx_wtskid
Stores information whether a task is queued to the wait queue.
TSK_NONE: No applicable task.
Value: ID number of the task at the head of the wait queue
- pk_msg, rmbx_pk_msg
Stores information whether a message is queued to the message queue.
NULL: No applicable message.
Value: Start address of the message packet at the head of the message queue
12.5.7 Fixed-sized memory pool state packet
The following shows fixed-sized memory pool state packet T_RMPF used when issuing
ref_mpf.
Definition of fixed-sized memory pool state packet T_RMPF is performed by header file <ri_root>\include\os\{packet.h, packet.inc}, which is called from standard header file <ri_root>\include\{kernel.h, kernel.inc}.
typedef struct t_rmpf {
ID wtskid; /*ID number of the task at the head of the wait queue*/
UINT fblkcnt; /*Number of free memory blocks*/
} T_RMPF;
|
rmpf_wtskid .EQU 0x00 ;ID number of the task at the head of the wait queue
rmpf_fblkcnt .EQU 0x02 ;Number of free memory blocks
|
The following shows details on fixed-sized memory pool state packet T_RMPF.
- wtskid, rmpf_wtskid
Stores information whether a task is queued to the wait queue.
TSK_NONE: No applicable task.
Value: ID number of the task at the head of the wait queue
- fblkcnt, rmpf_fblkcnt
Stores the number of free memory blocks.
12.5.8 Cyclic handler state packet
The following shows cyclic handler state packet T_RCYC used when issuing
ref_cyc.
Definition of cyclic handler state packet T_RCYC is performed by header file <ri_root>\include\os\{packet.h, packet.inc}, which is called from standard header file <ri_root>\include\{kernel.h, kernel.inc}.
typedef struct t_rcyc {
STAT cycstat; /*Cyclic handler operational state*/
RELTIM lefttim; /*Time left before the next activation*/
} T_RCYC;
|
rcyc_cycstat .EQU 0x00 ;Cyclic handler operational state
rcyc_lefttim .EQU 0x02 ;Time left before the next activation
|
The following shows details on cyclic handler state packet T_RCYC.
- cycstat, rcyc_cycstat
Stores the operational state of the cyclic handler.
TCYC_STP: Operational state
TCYC_STA: Non-operational state
- lefttim, rcyc_lefttim
Stores the time (unit: tick) left before the next activation.
The contents of this member become an undefined value if the target cyclic handler is in the non-operational state (STP state).
12.5.9 Version information packet
The following shows version information packet T_RVER used when issuing
ref_ver.
Definition of version information packet T_RVER is performed by header file <ri_root>\include\os\{packet.h, packet.inc}, which is called from standard header file <ri_root>\include\{kernel.h, kernel.inc}.
typedef struct t_rver {
UH maker; /*Kernel maker's code*/
UH prid; /*Identification number of the kernel*/
UH spver; /*Version number of the ITRON Specification*/
UH prver; /*Version number of the kernel*/
UH prno[4]; /*Management information of the kernel product*/
} T_RVER;
|
verinf_maker .EQU 0x00 ;Kernel maker's code
verinf_prid .EQU 0x02 ;Identification number of the kernel
verinf_spver .EQU 0x04 ;Version number of the ITRON Specification
verinf_prver .EQU 0x06 ;Version number of the kernel
verinf_prno .EQU 0x08 ;Management information of the kernel product
|
The following shows details on version information packet T_RVER.
- maker, verinf_maker
Stores the kernel maker's code.
0x011b: Renesas Electronics Co., Ltd.
- prid, verinf_prid
Stores the identification number of the kernel.
0x0006: Identification number
- spver, verinf_spver
Stores the version number of the ITRON Specification.
0x5403: ITRON4.0 Specification Ver.4.03.00
- prver, verinf_prver
Stores the version number of the kernel.
- prno[0], verinf_prno
Stores the kernel version type.
- prno[1], verinf_prno + 0x2
Stores the memory model of the kernel.
- prno[2], verinf_prno + 0x4
System-reserved area.
- prno[3], verinf_prno + 0x6
System-reserved area.