Renesas M3T-MR100 - page 144

- 130 -

rcv_mbx Receive from mailbox prcv_mbx Receive from mailbox (polling) iprcv_mbx Receive from mailbox (polling, handler only) trcv_mbx Receive from mailbox (with timeout)

[

[[

[

C

C

L

La

an

ng

gu

ua

ag

ge

e

A

AP

PI

I

]

]]

]

ER ercd = rcv_mbx( ID mbxid, T_MSG **ppk_msg );

ER ercd = prcv_mbx( ID mbxid, T_MSG **ppk_msg );

ER ercd = iprcv_mbx( ID mbxid, T_MSG **ppk_msg );

ER ercd = trcv_mbx( ID mbxid, T_MSG **ppk_msg, TMO tmout );

z

z

P

Pa

ar

ra

am

me

et

te

er

rs

s

ID mbxid ID number of the mailbox from which to receive

TMO tmout Timeout value (for trcv_mbx)

T_MSG **ppk_msg Pointer to the start of the area in which received message is

stored

z

z

R

Re

et

tu

ur

rn

n

P

Pa

ar

ra

am

me

et

te

er

rs

s

ER ercd Terminated normally (E_OK) or error code

T_MSG **ppk_msg Pointer to the start of the area in which received message is

stored

[

[[

[

A

As

ss

se

em

mb

bl

ly

y

l

la

an

ng

gu

ua

ag

ge

e

A

AP

PI

I

]

]]

]

.include mr100.inc

rcv_mbx MBXID

prcv_mbx MBXID

iprcv_mbx MBXID

trcv_mbx MBXID, TMO

z

z

P

Pa

ar

ra

am

me

et

te

er

rs

s

MBXID ID number of the mailbox from which to receive

TMO Timeout value (for trcv_mbx)

z

z

R

Re

eg

gi

is

st

te

er

r

c

co

on

nt

te

en

nt

ts

s

a

af

ft

te

er

r

s

se

er

rv

vi

ic

ce

e

c

ca

al

ll

l

i

is

s

i

is

ss

su

ue

ed

d

rcv_mbx,prcv_mbx,iprcv_mbx

Register name Content after service call is issued

R0 Error code

R2 ID number of the mailbox from which to receive

A1 Received message

trcv_mbx

Register name Content after service call is issued

R0 Error code

R2 ID number of the mailbox from which to receive

R6R4 Timeout value

A1 Received message

[

[[

[

E

Er

rr

ro

or

r

c

co

od

de

e

]

]]

]

E_RLWAI Forced release from waiting

E_TMOUT Polling failure or timeout or timed out

Contents

Main Preface C-compiler package for R32C/100 series microcomputers (abbreviated as NC100) Release Note Users Manual (PDF file) Page Contents Page Page Page Page List of Figures Page Page List of Tables Page 1. Users Manual Organization Page 2. General Information 2.1 Objective of MR100 Development Page Page 2.3 MR100 Features 3. Introduction to Kernel 3.1 Concept of Real-time OS 3.1.1 Why Real-time OS is Necessary Page Page 3.1.2 Operating Principles of Kernel Time Page Page Page 3.2 Service Call 3.2.1 Service Call Processing 3.2.2 Processing Procedures for Service Calls from Handlers Page Page Page 3.3 Object 3.3.1 The specification method of the object in a service call 3.4 Task 3.4.1 Task Status Page Page Page 3.4.2 Task Priority and Ready Queue TCB TCBTCB TCBTCB 3.4.3 Task Priority and Waiting Queue taskB taskC 3.4.4 Task Control Block(TCB) Task connection pointer Flag wait mode Flag wait pattern Startup request counter 3.5 System States 3.5.1 Task Context and Non-task Context 1. Interrupt Handler 2. Cyclic Handler 3. Alarm Handler Page 3.5.2 Dispatch Enabled/Disabled States 3.5.3 CPU Locked/Unlocked States 3.5.4 Dispatch Disabled and CPU Locked States 3.6 Regarding Interrupts 3.6.1 Types of Interrupt Handlers High Kernel interrupt handler Non-kernel interrupt handler For service calls that can be issued from only task context. Page 3.7 Stacks 3.7.1 System Stack and User Stack User Stack System Stack 4. Kernel 4.1.1 Module Structure 4.1.2 Module Overview Scheduler Task Management Module Task Synchronization Module Interrupt Management Module Time Management Module Activate Task (act_tsk, iact_tsk) Ter mi na ted Activate Task (sta_tsk, ista_tsk) Terminate Invoking Task (ext_tsk) Terminate Task (ter_tsk) Reference task priority (get_pri, iget_pri) Reference task status (simple version) (ref_tst, iref_tst) Reference task status (ref_tsk, iref_tsk) 4.1.4 Synchronization functions attached to task Put Task to sleep (slp_tsk,tslp_tsk) Wakeup task (wup_tsk, iwup_tsk) Wake up r eque st c oun t 0 0 1 0 0 Wakeup request count 0 0 1 2 1 Suspend task (sus_tsk, isus_tsk) Resume suspended task (rsm_tsk, irsm_tsk) Forcibly resume suspended task (frsm_tsk, ifrsm_tsk) Release task from waiting (rel_wai, irel_wai) Delay task (dly_tsk) 4.1.5 Synchronization and Communication Function (Semaphore) Semaphore Task A Release Semaphore Resource(sig_sem, isig_sem) Acquire Semaphore Resource(wai_sem, twai_sem) Acquire Semaphore Resource(pol_sem, ipol_sem) Reference Semaphore Status (ref_sem, iref_sem) 4.1.6 Synchronization and Communication Function (Eventflag) Set Eventflag (set_flg, iset_flg) Clear Eventflag (clr_flg, iclr_flg) Wait for Eventflag (wai_flg, twai_flg) Wait for Eventflag (polling)(pol_flg, ipol_flg) Reference Eventflag Status (ref_flg, iref_flg) Page 4.1.7 Synchronization and Communication Function (Data Queue) Data Data Data Task B Task A Send to Data Queue(snd_dtq, tsnd_dtq) Send to Data Queue (psnd_dtq, ipsnd_dtq) Forced Send to Data Queue (fsnd_dtq, ifsnd_dtq) Receive from Data Queue (rcv_dtq, trcv_dtq) Receive from Data Queue (prcv_dtq,iprcv_dtq) 4.1.8 Synchronization and Communication Function (Mailbox) T_MSG: Mailbox message header T_MSG_PRI: Mailbox message header with priority included Message Message TaskB TaskA Send to Mailbox (snd_mbx, isnd_mbx) Receive from Mailbox (rcv_mbx, trcv_mbx) Receive from Mailbox (polling) (prcv_mbx, iprcv_mbx) Reference Mailbox Status (ref_mbx, iref_mbx) 4.1.9 Memory pool Management Function(Fixed-size Memory pool) Acquire Fixed-size Memory Block (get_mpf, tget_mpf) Acquire Fixed-size Memory Block (polling) (pget_mpf, ipget_mpf) Release Fixed-size Memory Block (rel_mpf, irel_mpf) Reference Fixed-size Memory Pool Status (ref_mpf, iref_mpf) 4.1.10 Variable-size Memory Pool Management Function Equation for calculating four kinds of block sizes Example of a configuration file Processing speed Memory usage efficiency Rounding Memorypool 224 bytes Ease of configuration Reference Acquire Variable-size Memory Pool Status (ref_mpl, iref_mpl) 4.1.11 Time Management Function Place a task in a finite time wait state by specifying a timeout value Page 4.1.12 Cyclic Handler Function Start Cyclic Handler Operation (sta_cyc, ista_cyc) Stop Cyclic Handler Operation (stp_cyc, istp_cyc) Reference Cyclic Handler Status (ref_cyc, iref_cyc) 4.1.13 Alarm Handler Function Start Alarm Handler Operation (sta_alm, ista_alm) Stop alarm Handler Operation (stp_alm, istp_alm) Reference Alarm Handler Status (ref_alm, iref_alm) Page 4.1.15 Interrupt Management Function Returns from interrupt handler (ret_int) Page Page Page 5. Service call reffernce 5.1 Task Management Function Page act_tsk Activate task iact_tsk Activate task (handler only) Page can_act Cancel task activation request ican_act Cancel task activation request (handler only) Page sta_tsk Activate task with a start code ista_tsk Activate task with a start code (handler only) Page ext_tsk Terminate invoking task Page ter_tsk Terminate task Page chg_pri Change task priority ichg_pri Change task priority(handler only) Page get_pri Reference task priority iget_pri Reference task priority(handler only) Page ref_tsk Reference task status iref_tsk Reference task status (handler only) Page Page Page Page 5.2 Task Dependent Synchronization Function [S]: Standard profile service calls Each sign within " System State " is a following meaning. slp_tsk Put task to sleep tslp_tsk Put task to sleep (with timeout) Page Page wup_tsk Wakeup task iwup_tsk Wakeup task (handler only) Page can_wup Cancel wakeup request ican_wup Cancel wakeup request (handler only) Page rel_wai Release task from waiting irel_wai Release task from waiting (handler only) Page sus_tsk Suspend task isus_tsk Suspend task (handler only) Page Page Page dly_tsk Delay task Page 5.3 Synchronization & Communication Function (Semaphore) [S]: Standard profile service calls Each sign within " System State " is a following meaning. sig_sem Release semaphore resource isig_sem Release semaphore resource (handler only) Page Page Page Page ref_sem Reference semaphore status iref_sem Reference semaphore status (handler only) Page 5.4 Synchronization & Communication Function (Eventflag) [S]: Standard profile service calls Each sign within " System State " is a following meaning. set_flg Set eventflag iset_flg Set eventflag (handler only) Page clr_flg Clear eventflag iclr_flg Clear eventflag (handler only) Page Page Page Page ref_flg Reference eventflag status iref_flg Reference eventflag status (handler only) Page 5.5 Synchronization & Communication Function (Data Queue) [S]: Standard profile service calls Each sign within " System State " is a following meaning. Page Page Page Page Page Page ref_dtq Reference data queue status iref_dtq Reference data queue status (handler only) Page 5.6 Synchronization & Communication Function (Mailbox) [S]: Standard profile service calls Each sign within " System State " is a following meaning. snd_mbx Send to mailbox isnd_mbx Send to mailbox (handler only) Page Page Page Page ref_mbx Reference mailbox status iref_mbx Reference mailbox status (handler only) Page 5.7 Memory Pool Management Function (Fixed-size Memory Pool) [S]: Standard profile service calls Each sign within " System State " is a following meaning. Page Page Page rel_mpf Release fixed-size memory block irel_mpf Release fixed-size memory block (handler only) Page Page Page 5.8 Memory Pool Management Function (Variable-size Memory Pool) [S]: Standard profile service calls Each sign within " System State " is a following meaning. pget_mpl Aquire variable-size memory block (polling) Page rel_mpl Release variable-size memory block Page Page Page 5.9 Time Management Function [S]: Standard profile service calls Each sign within " System State " is a following meaning. set_tim Set system time iset_tim Set system time (handler only) Page get_tim Reference system time iget_tim Reference system time (handler only) Page isig_tim Supply a time tick 5.10 Time Management Function (Cyclic Handler) [S]: Standard profile service calls Each sign within " System State " is a following meaning. sta_cyc Start cyclic handler operation ista_cyc Start cyclic handler operation (handler only) Page stp_cyc Stops cyclic handler operation istp_cyc Stops cyclic handler operation (handler only) ref_cyc Reference cyclic handler status iref_cyc Reference cyclic handler status (handler only) Page 5.11 Time Management Function (Alarm Handler) [S]: Standard profile service calls Each sign within " System State " is a following meaning. sta_alm Start alarm handler operation ista_alm Start alarm handler operation (handler only) Page stp_alm Stop alarm handler operation istp_alm Stop alarm handler operation (handler only) ref_alm Reference alarm handler status iref_alm Reference alarm handler status (handler only) Page 5.12 System Status Management Function [S]: Standard profile service calls Each sign within " System State " is a following meaning. rot_rdq Rotate task precedence irot_rdq Rotate task precedence (handler only) Page Page loc_cpu Lock the CPU iloc_cpu Lock the CPU (handler only) Page unl_cpu Unlock the CPU iunl_cpu Unlock the CPU (handler only) dis_dsp Disable dispatching Page ena_dsp Enables dispatching sns_ctx Reference context sns_loc Reference CPU state sns_dsp Reference dispatching state sns_dpn Reference dispatching pending state 5.13 Interrupt Management Function Table 5.24 List of Interrupt Management Function Service Call [S]: Standard profile service calls Each sign within " System State " is a following meaning. ret_int Returns from an interrupt handler (when written in assembly language) 5.14 System Configuration Management Function Table 5.25 List of System Configuration Management Function Service Call [S]: Standard profile service calls Each sign within " System State " is a following meaning. ref_ver Reference version information iref_ver Reference version information (handler only) Page 5.15 Extended Function (Short Data Queue) Table 5.26 Specifications of the Short Data Queue Function Table 5.27 List of Long Dataqueue Function Service Call [S]: Standard profile service calls Each sign within " System State " is a following meaning. Page Page Page Page Page Page Page Page 5.16 Extended Function (Reset Function) Table 5.28 List of Reset Function Service Call [S]: Standard profile service calls Each sign within " System State " is a following meaning. vrst_dtq Clear data queue area Page vrst_vdtq Clear Short data queue area Page vrst_mbx Clear mailbox area Page vrst_mpf Clear fixed-size memory pool area vrst_mpl Clear variable-size memory pool area 6. Applications Development Procedure Overview 6.1 Overview - 206 - HEW Figure 6.1 MR100 System Generation Detail Flowchart Page - 208 - Figure 6.2 Program Example 6.2.2 Configuration File Preparation - 209 - Figure 6.3 Configuration File Example Execute the make command to generate the system. 6.2.3 Configurator Execution Figure 6.4 Configurator Execution 6.2.4 System generation Figure 6.5 System Generation 6.2.5 Writing ROM 7. Detailed Applications 7.1 Program Coding Procedure in C Language 7.1.1 Task Description Procedure 7.1.2 Writing a Kernel (OS Dependent) Interrupt Handler 7.1.3 Writing Non-kernel Interrupt Handler 7.1.4 Writing Cyclic Handler/Alarm Handler Page 7.2 Program Coding Procedure in Assembly Language 7.2.1 Writing Task 7.2.2 Writing Kernel Interrupt Handler 7.2.3 Writing Non-kernel Interrupt Handler 7.2.4 Writing Cyclic Handler/Alarm Handler Page Page - 219 - 7.3.1 C Language Startup Program (crt0mr.a30) Figure 7.11 shows the C language startup program(crt0mr.a30). - 220 - - 221 - Figure 7.11 C Language Startup Program (crt0mr.a30) - 222 - ; **************************************************************** Page 7.4 Memory Allocation asm_sec.inc c_sec.inc Page Page 8. Using Configurator 8.1 Configuration File Creation Procedure 8.1.1 Configuration File Data Entry Format Comment Statement End of statement 123 123 + 0x23 (23/4 + 3) 100B + 0aH Symbol _TASK1 IDLE3 Function Name main() func() Page Page Page Page Page [( Task definition )] << Format >> 1. Task ID name [( Definition format )] [( Definition range )] [( Default value )] 2. Start address of task [( Definition format )] [( Definition range )] [( Default value )] Page Page Page Page Page Page Page Section name Maximum message size Message buffer transmit wait queue selection Page Page Page Page [( Fixed interrupt vector definition )] Start address Page Page 250 8.1.3 Configuration File Example The following is the configuration file example. Page Page Page Page cfg100 Figure 8.1 The operation of the Configurator 8.2.2 Setting Configurator Environment Default configuration file (default.cfg) 8.2.5 Configurator Error Indications and Remedies Error messages Page Warning messages 9. Sample Program Description 9.1 Overview of Sample Program Table 9.1 Functions in the Sample Program task2 operates in order of the following. 9.2 Program Source Listing 9.3 Configuration File Page 10. Stack Size Calculation Method 10.1 Stack Size Calculation Method XXX_XXX() Page 10.1.1 User Stack Calculation Method User stack size = Sections used in user program + registers used + Sections used in MR100 Stack growing direction Figure 2.3:Example of Use Stack Size Calculation 10.1.2 System Stack Calculation Method Page [( Stack size i used by interrupt handlers )] The stack size to be used by non-kernel interrupt handler = register to be used + user size Figure 10.5: Stack size to be used by Kernel Interrupt Handler(Written in C language) [( System stack size used by system clock interrupt handler )] 10.2 Necessary Stack Size Table 10.1 Stack Sizes Used by Service Calls Issued from Tasks (in bytes) Table 10.2 Stack Sizes Used by Service Calls Issued from Handlers (in by tes) Table 10.3 Stack Sizes Used by Service Calls Issued from T asks and Handlers (in bytes) Page 11. Note 11.1 The Use of INT Instruction Table 11.1 Interrupt Number Assignm ent 11.2 The Use of registers of bank Page Page Page 12. Appendix 12.1 Data Type 12.2 Common Constants and Packet Format of Structure Page 12.3 Assembly Language Interface - 283 - Page Page - 286 - Memorypool Management Functions Time Management Functions - 287 - System Configuration Management Functions Page 2007. Renesas Technology Corp. and Renesas Solutions Corp.,