Everything

CHAPTER 12 SERVICE CALLS


This chapter describes the service calls supported by the RI78V4.
12.1 Outline
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.
12.2 Call Service Call
The method for calling service calls from processing programs coded either in C or assembly language is described below.
12.2.1 C language
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.
[ C Language ]
 #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)
12.2.2 Assembly 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.
[ Assembly Language ]
 $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.
Table 12-1 Stack Amount Used by Service Call (Unit: Bytes)
Service Call
For Service Call Arguments
For Internal Processing by Program Issued the Service Call
For System Stack Internal Processing
0
10
6
0
10
6
0
10
6
0
10
12
0
10
12
0
10
16
0
10
6
0
10
12
0
10
14
0
10
6
0
10
6
0
10
8
0
10
12
0
10
6
0
10
6
0
10
14
0
10
6
0
10
12
0
10
12
0
10
12
0
10
6
0
10
6
0
10
6
8
10
16
0
10
16
4
10
16
0
10
6
0
10
16
0
10
16
4
10
16
0
10
6
0
10
14
0
10
14
4
10
14
0
10
6
0
10
16
0
10
8
0
10
12
0
10
12
4
10
12
0
10
6
0
10
14
0
10
14
4
10
14
0
10
6
0
10
6
0
10
12
0
10
6
0
10
6
0
10
8
0
10
6
0
10
6
0
10
8
0
10
6
0
10
6
0
10
6
0
10
6
0
10
6
0
10
6
0
10
6

12.4 Data Macros
This section explains the data macros (for data types, current state, or the like) used when issuing a service call provided by the RI78V4.
12.4.1 Data types
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.
Table 12-2 Data Types
Macro
Data Type
Description
UH
unsigned short int
Unsigned 16-bit integer
VP
void __near
Pointer to an unknown data type
UINT
unsigned int
Unsigned 16-bit integer
VP_INT
signed long int
Pointer to an unknown data type, or a signed 32-bit integer
ID Note
unsigned char
Object ID number
BOOL
signed int
Boolean value
STAT
unsigned short int
Object state
ER
signed short int
Return value
ER_UINT
unsigned short int
Unsigned 16-bit integer
PRI
signed char
Priority
FLGPTN
unsigned short int
Bit pattern
MODE
unsigned char
Service call operational mode
TMO
signed long int
Timeout (unit: ticks)
RELTIM
unsigned long int
Relative time (unit: ticks)

Note The ID type definition in the RI78V4 differs from that of the uITRON 4.0 specification.
12.4.2 Current state
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.
Table 12-3 Current State
Macro
Value
Description
TTS_RUN
0x01
RUNNING state
TTS_RDY
0x02
READY state
TTS_WAI
0x04
WAITING state
TTS_SUS
0x08
SUSPENDED state
TTS_WAS
0x0c
WAITING-SUSPENDED state
TTS_DMT
0x10
DORMANT state
TCYC_STP
0x00
Non-operational state
TCYC_STA
0x01
Operational state

12.4.3 WAITING types
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.
Table 12-4 WAITING Types
Macro
Value
Description
TTW_SLP
0x0001
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
0x0002
A task enters this state upon the issuance of a dly_tsk.
TTW_SEM
0x0004
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
0x0008
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
0x0010
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
0x0020
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
0x0040
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
0x2000
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.

12.4.4 Return value
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.
Table 12-5 Return Value
Macro
Value
Description
E_OK
0
Normal completion.
E_ILUSE
-28
Illegal service call use.
E_OBJ
-41
Object state error.
E_QOVR
-43
Queue overflow.
E_RLWAI
-49
Forced release from waiting (accept rel_wai/irel_wai while waiting).
E_TMOUT
-50
Polling failure or timeout.
FALSE
0
False
TRUE
1
True

12.4.5 Conditional compile macro
The RI78V4 header files are conditionally compiled by the following macro.
Table 12-6 Conditional Compile Macro
Classification
Macro
Description
C compiler package
__REL__
The CC-RL is used.

12.4.6 Others
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.
Table 12-7 Others
Macro
Value
Description
TSK_SELF
0
Invoking task
TPRI_INI
0
Initial priority of the task
TMO_FEVR
-1
Waiting forever
TMO_POL
0
Polling
TWF_ANDW
0x00
AND waiting condition
TWF_ORW
0x01
OR waiting condition
TPRI_SELF
0
Current priority of the invoking task
TSK_NONE
0
No applicable task
NULL
0
No applicable message

12.5 Packet Formats
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.
12.5.1 Task state packet
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}.
[ packet.h ]
 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;

[ packet.inc ]
 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_RUN: RUNNING state
TTS_RDY: READY state
TTS_WAI: WAITING state
TTS_SUS: SUSPENDED state
TTS_WAS: WAITING-SUSPENDED state
TTS_DMT: DORMANT 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}.
[ packet.h ]
 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;

[ packet.inc ]
 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}.
[ packet.h ]
 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;

[ packet.inc ]
 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}.
packet.h
 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;

packet.inc
 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.
12.5.5 Message packet
The following shows message packet T_MSG and T_MSG_PRI used when issuing snd_mbx, rcv_mbx, prcv_mbx, or trcv_mbx.
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}.
[ packet.h ]
 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;

[ packet.inc ]
 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}.
[ packet.h ]
 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;

[ packet.inc ]
 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}.
[ packet.h ]
 typedef struct  t_rcyc {
     STAT    cycstat;        /*Cyclic handler operational state*/
     RELTIM  lefttim;        /*Time left before the next activation*/
 } T_RCYC;

[ packet.inc ]
 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}.
[ packet.h ]
 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;

[ packet.inc ]
 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.
0x01xx: Ver.2.xx
- prno[0], verinf_prno
Stores the kernel version type.
0x0: V-version
- prno[1], verinf_prno + 0x2
Stores the memory model of the kernel.
0x2 Medium model
- prno[2], verinf_prno + 0x4
System-reserved area.
- prno[3], verinf_prno + 0x6
System-reserved area.