M3T-MR30 M16C/60 REJ10J0102-0100Z M16C/20 NC30WA 00000H 0001H 0002H 0004H 0008H - Datasheet Archive

 

Real-time OS for M16C/60,30,20,10 Series Reference Manual Rev. 1.00 September 16, 2003 REJ10J0102-0100Z Active X, Microsoft,

 

M3T-MR30 M3T-MR30 V.3.30 Real-time OS for M16C/60 M16C/60,30,20,10 Series Reference Manual Rev. 1.00 September 16, 2003 REJ10J0102-0100Z REJ10J0102-0100Z Active X, Microsoft, MS-DOS, Visual Basic, Visual C+, Windows and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. Sun, Solaris, Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. or other countries, and are used under license. Linux is a trademark of Linus Torvalds. Turbolinux and its logo are trademarks of Turbolinux, Inc. IBM and AT are registered trademarks of International Business Machines Corporation. Intel and Pentium are registered trademarks of Intel Corporation. Adobe, Acrobat, and Acrobat Reader are trademarks of Adobe Systems Incorporated. All other brand and product names are trademarks, registered trademarks or service marks of their respective holders. Keep safety first in your circuit designs! Renesas Technology Corporation and Renesas Solutions Corporation put the maximum effort into making semiconductor products better and more reliable, but there is always the possibility that trouble may occur with them. Trouble with semiconductors may lead to personal injury, fire or property damage. Remember to give due consideration to safety when making your circuit designs, with appropriate measures such as (i) placement of substitutive, auxiliary circuits, (ii) use of nonflammable material or (iii) prevention against any malfunction or mishap. Notes regarding these materials These materials are intended as a reference to assist our customers in the selection of the Renesas Technology product best suited to the customer's application; they do not convey any license under any intellectual property rights, or any other rights, belonging to Renesas Technology Corporation, Renesas Solutions Corporation or a third party. Renesas Technology Corporation and Renesas Solutions Corporation assume no responsibility for any damage, or infringement of any third-party's rights, originating in the use of any product data, diagrams, charts, programs, algorithms, or circuit application examples contained in these materials. All information contained in these materials, including product data, diagrams, charts, programs and algorithms represents information on products at the time of publication of these materials, and are subject to change by Renesas Technology Corporation and Renesas Solutions Corporation without notice due to product improvements or other reasons. It is therefore recommended that customers contact Renesas Technology Corporation, Renesas Solutions Corporation or an authorized Renesas Technology product distributor for the latest product information before purchasing a product listed herein. The information described here may contain technical inaccuracies or typographical errors. Renesas Technology Corporation and Renesas Solutions Corporation assume no responsibility for any damage, liability, or other loss rising from these inaccuracies or errors. Please also pay attention to information published by Renesas Technology Corporation and Renesas Solutions Corporation by various means, including the Renesas home page (http://www.renesas.com). When using any or all of the information contained in these materials, including product data, diagrams, charts, programs, and algorithms, please be sure to evaluate all information as a total system before making a final decision on the applicability of the information and products. Renesas Technology Corporation and Renesas Solutions Corporation assume no responsibility for any damage, liability or other loss resulting from the information contained herein. Renesas Technology semiconductors are not designed or manufactured for use in a device or system that is used under circumstances in which human life is potentially at stake. Please contact Renesas Technology Corporation, Renesas Solutions Corporation or an authorized Renesas Technology product distributor when considering the use of a product contained herein for any specific purposes, such as apparatus or systems for transportation, vehicular, medical, aerospace, nuclear, or undersea repeater use. The prior written approval of Renesas Technology Corporation and Renesas Solutions Corporation is necessary to reprint or reproduce in whole or in part these materials. If these products or technologies are subject to the Japanese export control restrictions, they must be exported under a license from the Japanese government and cannot be imported into a country other than the approved destination. Any diversion or reexport contrary to the export control laws and regulations of Japan and/or the country of destination is prohibited. Please contact Renesas Technology Corporation or Renesas Solutions Corporation for further details on these materials or the products contained therein. For inquiries about the contents of this document or product, fill in the text file the installer generates in the following directory and email to your local distributor. \SUPPORT\Product-name\SUPPORT.TXT Renesas Tools Homepage http://www.renesas.com/en/tools Preface The MR30 is a real-time operating system1 for the M16C/60 M16C/60 series, M16C/20 M16C/20 series microcomputers. The MR30 conforms to the µITRON Specification.2 This manual describes the function and configuration. Right of Software Use The right of software use conforms to the software license agreement. You can use the MR30 for your product development purposes only, and are not allowed to use it for the other purposes. You should also note that this manual does not guarantee or permit the exercise of the right of software use. Document List The following sets of documents are supplied with the MR30. Release Note Presents a software overview and describes the corrections to the Users Manual and Reference Manual. Users Manual (PDF file) Describes the procedures and precautions to observe when using the MR30 for programming purposes. Reference Manual (PDF file) Describes the MR30 system call procedures and typical usage examples. Before reading the Users Manual, be sure to read the Release Note. Please read the release note before reading this manual. 1 Hereinafter abbreviated "real-time OS" The µITRON Specification is originated by Dr.Ken Sakamura and his laboratory members at the Faculty Science of University of Tokyo. Therefore,Dr.Ken Sakamura holds the copyright on the µITRON Specification. By his consent,the MR30 is produced in compilance with the µITRON Specification. 2 Contents Chapter 1 Interpreting the System Call Reference 1 1.1. Interpreting the System Call Reference 2 1.2. Performance for Individual System Calls 4 1.3. Processing Time for the Scheduler 1.3.1. Processing Time for the Scheduler Activated by a System Call 1.3.2. Processing Time for the Scheduler Activated by an Interrupt Handler 1.3.3. Processing Time for the System Timer 6 6 6 6 1.4. 7 Necessary Stack Size 1.5. Stack Size Calculation Method 1.5.1. User Stack Calculation Method 1.5.2. System Stack Calculation Method 9 11 13 Chapter 2 System Call Reference 1 2.1. Task Management Functions 2.1.1. sta_tsk(Start Task) 2.1.2. ista_tsk(Start Task) 2.1.3. ext_tsk(Exit Task) 2.1.4. ter_tsk(Terminate Task) 2.1.5. dis_dsp(Disable Dispatch) 2.1.6. ena_dsp(Enable Dispatch) 2.1.7. chg_pri(Change Task Priority) 2.1.8. ichg_pri(Change Task Priority) 2.1.9. rot_rdq(Rotate Ready Queue) 2.1.10. irot_rdq(Rotate Ready Queue) 2.1.11. rel_wai(Release Task Wait) 2.1.12. irel_wai(Release Task Wait) 2.1.13. get_tid(Get Self Task ID) 2.1.14. ref_tsk(Refer Task Status) 2 2 5 7 9 11 13 15 17 19 22 24 26 28 30 2.2. Synchronization Functions Attached to Task 2.2.1. sus_tsk(Suspend Task) 2.2.2. isus_tsk(Suspend Task) 2.2.3. rsm_tsk(Resume Task) 2.2.4. irsm_tsk(Resume Task) 2.2.5. slp_tsk(Sleep Task) 2.2.6. tslp_tsk(Sleep Task with Timeout) 2.2.7. wup_tsk(Wakeup Task) 2.2.8. iwup_tsk(Wakeup Task) 2.2.9. can_wup(Cancel Wakeup Task) 33 33 35 37 39 41 43 45 47 49 2.3. Eventflags 2.3.1. set_flg(Set Eventflag) 51 51 2.3.2. iset_flg(Set Eventflag) 2.3.3. clr_flg(Clear Eventflag) 2.3.4. wai_flg(Wait Eventflag) 2.3.5. twai_flg(Wait Eventflag with Timeout) 2.3.6. pol_flg(Poll Eventflag) 2.3.7. ref_flg(Refer Eventflag Status) 53 55 57 60 62 64 2.4. Semaphore 2.4.1. sig_sem(Signal Semaphore) 2.4.2. isig_sem(Signal Semaphore) 2.4.3. wai_sem(Wait on Semaphore) 2.4.4. twai_sem(Wait on Semaphore with Timeout) 2.4.5. preq_sem(Poll and Request Semaphore) 2.4.6. ref_sem(Refer Semaphore Status) 66 66 68 70 72 74 76 2.5. Mailbox 2.5.1. snd_msg(Send Message to Mailbox) 2.5.2. isnd_msg(Send Message to Mailbox) 2.5.3. rcv_msg(Receive Message from Mailbox) 2.5.4. trcv_msg(Receive Message with Timeout) 2.5.5. prcv_msg(Poll and Receive Message) 2.5.6. ref_mbx(Refer Mailbox Status) 78 78 81 83 85 87 89 2.6. Interrupt Management Function 2.6.1. ret_int(Return from Interrupt Handler) 2.6.2. loc_cpu(Lock CPU) 2.6.3. unl_cpu(Unlock CPU) 91 91 93 95 2.7. Memorypool Management Function 2.7.1. pget_blf(Poll and Get Fixed-size Memory Block) 2.7.2. rel_blf(Release Fixed-size Memory Block) 2.7.3. ref_mpf(Refer Fixed-size Memorypool Status) 2.7.4. pget_blk(Poll and Get Variable-size Memory Block) 2.7.5. rel_blk(Release Variable-size Memory Block) 2.7.6. ref_mpl(Refer Variable-size Memorypool Status) 97 97 99 101 103 105 107 2.8. Time Management Function 2.8.1. set_tim(Set Time) 2.8.2. get_tim(Get Time) 2.8.3. dly_tsk(Delay Task) 2.8.4. act_cyc (Activate Cyclic Handler) 2.8.5. ref_cyc(Refer Cyclic Handler Status) 2.8.6. ref_alm(Refer Alarm Handler Status) 109 109 111 113 115 117 119 2.9. System Management Function 2.9.1. get_ver(Get Version Information) 121 121 2.10. Implementation-Dependent System Call 2.10.1. vrst_msg(Reset Message) 2.10.2. vrst_blf(Reset Fixed-Memory Block) 2.10.3. vrst_blk(Reset Variable-Memory Block) 124 124 126 128 Chapter 3 Appendix 131 3.1. List of System calls 132 3.2. List of Error code 134 3.3. Assembly Language Interface 135 3.4. C Language Interface 139 3.5. Data Type 141 3.6. Common Constants and Packet Format of Structure 142 Index 145 Chapter 1 Interpreting the System Call Reference 2 1.1 Interpreting the System Call Reference 1.1. Interpreting the System Call Reference The system call reference is written in the following format: [( System call name )] System call name the function of the system call [( Calling by the assembly language )] .include mr30.inc Calling by the assembly language > Explanation of system call parameters Parameters are written as macro arguments. Argment name Size Explanation The size is indicated by the following symbols: [-] 1-byte data [-] 2-byte data [-] 3-byte data [] 4-byte data The registers that can be used as the arguments of 1- byte data are R0H/R0L and R1H/R1L only. > A value is shown that is set the register after issuing a system call macro. Register name Register content after issuing system call *1 *2 *1 Register name. Written in this column are R0,R1,R2,R3,A0,A1. *2 Indicates the content that is set in each register. Description '-' means that the content is saved if the register is set to be used, and that the content is indeterminate if the register is not set to be used. FLG is such that the values of IPL, U, I, and B before a system call are saved; other flags are indeterminate. The same applies for registers not listed in this table (SB, and FB). Namely, the content is saved if the register is set to be used, or the content is indeterminate if the register is not set to be used. The registers used by each (return) parameter are approximately predetermined as follows: R0 register(16bits) R1 register(16bits) R2 register(16bits) R3 register(16bits) A0 register(16bits) A1 register(16bits) Function code (set in system call macro) and error code wfmode (wai_flg and pol_flg system call wait mode) and lower 16 bits of packet address lower 16 bits of packet address and other parameters upper 16 bits of packet address and other parameters ID number of object 16 bits of packet address [( Calling by the C language )] Calling an MR30 function from the C language > Declaration of argument type 1.1 Interpreting the System Call Reference 3 > Description of the return value resulted from a call Note that the types used in the system call reference are defined in the include file "mr30.h" The definitions are as Appendix 3.5 [( Error codes )] [Error code name] [error code value]: [the meaning of error code] Error code character strings such as E_OK are defined in "mr30.h" by using "#define" and in "mr30.inc"3 by using ".EQU" To determine errors, use these defined character strings. [( Function description )] Detail functional description [( Usage example )] Usage example 3 If an error code value is directly written, the compatibility with the future versions is not assured. 4 1.2 Performance for Individual System Calls 1.2. Performance for Individual System Calls The processing time and the maximum interrupt disable time for individual system calls are given below. The maximum interrupt disable time is with respect to the OS-dependent interrupt (the interrupt that issues a system call). The maximum interrupt disable time with respect to the OSindependent interrupt (the interrupt that doesn't issue a system call) is 2µs The processing time is the result of measurement by use of a 10-MHz operating frequency and a 16-bit bus. It is in µs. stands for the scheduler's processing time. System call sta_tsk ista_tsk ext_tsk ter_tsk dis_dsp ena_dsp chg_pri ichg_pri rot_rdq irot_rdq rel_wai irel_wai get_tid ref_tsk sus_tsk isus_tsk rsm_tsk irsm_tsk slp_tsk wup_tsk iwup_tsk can_wup wai_flg clr_flg pol_flg ref_flg sig_sem Processing time Maximum interrupt disable time 33+ 35 11+ 41+ 7 21+ 28+ 22 20+ 18 48+ 48 13 24 20+ 18 19+ 20 17+ 29+ 30 18 26+ 13 18 13 38+ 36 35 11 44 7 22 31 22 22 18 51 48 13 24 22 18 22 20 20 32 30 18 30 13 18 13 41 System call isig_sem wai_sem preq_sem ref_sem snd_msg isnd_msg rcv_msg prcv_msg ref_mbx loc_cpu unl_cpu set_tim get_tim pget_blf rel_blf ref_mpf pget_blk rel_blk ref_mpl act_cyc ref_cyc ref_alm get_ver vrst_msg vrst_blf vrst_blk Processing time 34 24+ 14 14 39+ 39 25+ 22 18 10 16+ 14 14 38 23 42 95+ more than 50+ 27 14 15 23 17 13 13 139 Maximum interrupt disable time 34 27 14 14 42 39 29 22 18 14 14 38 23 42 17 16 27 14 15 23 17 13 13 11 1.2 Performance for Individual System Calls System call Processing time 5 Maximum interrupt disable time 20+ 26+8 (-1)+ 25+ tslp_tsk 30+8(-1)+ 32+ twai_flg 32+8(-1)+ 15+ twai_sem 28+8(-1)+ 22+ trcv_msg more than 1 28+8(-1)+ : The number of tasks that retrieved the timeout queue. dly_tsk System call 0 more than 1 0 more than 1 0 more than 1 0 more than 1 0 Processing time 29 32 43 39 39 Maximum interrupt disable time 0 15+8+ more than 1 45+37(-1)+ 8+ 0 17+10 iset_flg more than 1 50+39(-1)+11 : The number of tasks that satisfied the wait condition. set_flg 50 48 : The number of tasks that didn't satisfy the wait condition. See Interrupt Handler and Schedular Processing Times on page 6 for details of the ret_int processing time and interrupt inhibit time. 6 1.3 Processing Time for the Scheduler 1.3. Processing Time for the Scheduler 1.3.1. Processing Time for the Scheduler Activated by a System Call The processing time and the interrupt disable time for the scheduler activated by a system call from a task are given below. Processing time 13+1.8(x-1) µs x: Priority Interrupt disable time 14+1.8(x-1) µs x: Priority (Values of 32 and greater are processed as 32) 1.3.2. Processing Time for the Scheduler Activated by an Interrupt Handler The processing time and interrupt disable time for the scheduler activated at the time of returning from an interrupt are given below. Processing time 25+1.8(x-1) µs x: Priority Interrupt disable time 15+1.8(x-1) µs x: Priority (Values of 32 and greater are processed as 32) 1.3.3. Processing Time for the System Timer Processing time Processing time the system timer = 16 + (processing time for system time update + ) (processing time for a cyclic handler + ) (processing time for an alarm handler + ) processing time for timeout rising + processing time for ret_int µs Processing time for the system timer = 1µs Processing time for a cyclic activation handler = 5× n + (6+ hander executiontime) Processing time for an alarm handler = 3+ (12× n + hander executiontime) n: the number of registered handlers Processing time for timeout rising = 11+30(n-1) n: the number of tasks that rise Maximum interrupt disable time 32µs 1.4 Necessary Stack Size 7 1.4. Necessary Stack Size Table 1.1 lists the stack sizes used by system calls that can be issued from tasks. Table 1.1 Stack Sizes Used by System Calls Issued from Tasks (in bytes) System call sta_tsk ext_tsk ter_tsk dis_dsp ena_dsp chg_pri rot_rdq rel_wai sus_tsk rsm_tsk slp_tsk tslp_tsk wup_tsk set_flg wai_flg Stack size user sysetm stack stack 0 3 0 3 0 6 0 0 0 0 0 3 0 0 0 6 0 3 0 3 0 3 0 6 0 6 0 6 0(3*) 3 System call twai_flg sig_sem wai_sem twai_sem snd_msg rcv_msg trcv_msg loc_cpu unl_cpu dly_tsk pget_blk rel_blk vrst_msg vrst_blf vrst_blk Stack Size user sysetm stack stack 0(3*) 6 0 6 0 3 0 6 0 6 0(3*) 3 0(3*) 6 0 0 0 0 0 6 0(3*) 31 0 49 8 0 8 0 37 0 *: Stack sizes used by system call in C programs. Table 1.2 lists the stack sizes (system stack) used by system calls that can be issued from handlers. Table 1.2 Stack Sizes Used by System Calls Issued from Handlers (in bytes) System call ista_tsk ichg_pri irot_rdq irel_wai isus_tsk irsm_tsk Stack Size 13 11 10 16 11 11 System call iwup_tsk iset_flg isig_sem isnd_msg ret_int Stack Size 16 20 16 20 8 8 1.4 Necessary Stack Size Table 1.3 lists the stack sizes (system stack) used by system calls that can be issued from both tasks and handlers. Table 1.3 Stack Sizes Used by System Calls Issued from Tasks and Handlers (in bytes) System call get_tid can_wup clr_flg pol_flg preq_sem prcv_msg pget_blf rel_blf set_tim get_tim Stack Size 8(11*) 8(11*) 8 8(11*) 8 10(15*) 10(15*) 14 8 8 System call act_cyc get_ver ref_tsk ref_flg ref_sem ref_mbx ref_mpf ref_mpl ref_cyc ref_alm *: Stack sizes used by system call in C programs. Stack Size 8 8 10 8 8 8 12 8 8 8 1.5 Stack Size Calculation Method 9 1.5. Stack Size Calculation Method The MR30 provides two kinds of stacks: the system stack and the user stack. The stack size calculation method differ between the stacks. User stack This stack is provided for each task. Therefore, writing an application by using the MR30 requires to allocate the stack area for each stack. System stack This stack is used inside the MR30 or during the execution of the handler. When a task issues an system call, the MR30 switches the user stack to the system stack. (See Figure 1.1) The system stack uses interrupt stack(ISP). Task MR30 system call processing portion User Stack Register save Stack switching System call processing XXX_XXX() XXX_XXX() System Stack (Interrupt Stack) Task Selection Stack switching Register return User Stack Figure 1.1: System Stack and User Stack 10 1.5 Stack Size Calculation Method The system stack and the user stack for each task are allocated by the stack section in memory. SFR System Stack User stack of Task ID No.1 User stack of Task ID No.2 Stack Section User stack of Task ID No.n Figure 1.2: Layout of Stacks 1.5 Stack Size Calculation Method 11 1.5.1. User Stack Calculation Method User stacks must be calculated for each task. The following shows an example for calculating user stacks in cases when an application is written in the C language and when an application is written in the assembly language. When an application is written in the C language Using the stack size calculation utility STK Viewer4, calculate the stack size of each task. The necessary stack size of a task is the sum of the stack size output by STK Viewer plus a context storage area of 20 bytes5 . When an application is written in the assembly language Sections used in user program The necessary stack size of a task is the sum of the stack size used by the task in subroutine call plus the size used to save registers to a stack in that task. Sections used in MR30 The sections used in MR30 refer to a stack size that is used for the system calls issued. MR30 requires that if you issue only the system calls that can be issued from tasks, 4 bytes of area be allocated for storing the PC and FLG registers. Also, if you issue the system calls that can be issued from both tasks and handlers, see the stack sizes listed in Table 1.2 to ensure that the necessary stack area is allocated. Furthermore, when issuing multiple system calls, include the maximum value of the stack sizes used by those system calls as the sections used by MR30 as you calculate the necessary stack size. Therefore, User stack size = Sections used in user program + registers used + Sections used in MR30 Figure 1.3 shows an example for calculating a user stack. In the example below, the registers used by the task are R0, R1, and A0. 4 5 STK Viewer is a utility to calculate the stack size included with Renesas C Compiler NC30WA NC30WA. If written in the C language, this size is fixed. 12 1.5 Stack Size Calculation Method Stack growing direction 3 bytes 10bytes (PC+FLG+size of registers used) jsr sub1 sta_tsk 22bytes (PC+FLG+size of registers used + stack size used by prcv_msg) prcv_msg 25bytes Figure 1.3: Example of User Stack Size Calculation 1.5 Stack Size Calculation Method 13 1.5.2. System Stack Calculation Method The system stack is most often consumed when an interrupt occurs during system call processing followed by the occurrence of multiple interrupts.6 The necessary size (the maximum size) of the system stack can be obtained from the following relation: Necessary size of the system stack = + i( + ) The maximum system stack size among the system calls to be used.7 When sta_tsk, ext_tsk, and dly_tsk are used for example, according to the Table 1.1 ,each of system stack size is the following. System call System Stack Size sta_tsk ext_tsk slp_tsk dly_tsk 3bytes 3bytes 3bytes 6bytes Therefore,the maximum system stack size among the system calls to be used is the 6 bytes of dly_tsk. i The stack size to be used by the interrupt handler.8 The details will be described later. Stack size used by the system clock interrupt handler. This is detailed later. 6 After switchover from user stack to system stack Refer Section 1.4 for the system stack size used for each individual system call. 8 OS-dependent interrupt handler (not including the system clock interrupt handler here) and OS-independent interrupt handler. 7 14 1.5 Stack Size Calculation Method :The maximum system stack size among the system calls to be used. :The :The system stack size to be used by the interrupt handler. :The 1 2 Interrupt Interrupt n The necessary system stack size Figure 1.4:System Stack Calculation Method 1.5 Stack Size Calculation Method 15 [( Stack size i used by interrupt handlers )] The stack size used by an interrupt handler that is invoked during a system call can be calculated by the equation below. The stack size i used by an interrupt handler is shown below. C language Using the stack size calculation utility STK Viewer9, calculate the stack size of each interrupt handler. Assembly language The stack size to be used by OS-dependent interrupt handler = register to be used + user size + stack size to be used by system call The stack size to be used by OS-independent interrupt handler = register to be used + user size User size is the stack size of the area written by user. context(18bytes) 3 bytes Interrupt jsr func 20 bytes iset_flg iset_flg ret_int ret_int 41 bytes context: 18 bytes when written in C language. When written in assembly language, context = size of registers used + 4(PC,FLG) bytes Figure 1.5: Stack size to be used by OS-dependent Interrupt Handler 9 STK Viewer is a utility to calculate the stack size included with Renesas C Compiler NC30WA NC30WA. 16 1.5 Stack Size Calculation Method [( System stack size used by system clock interrupt handler )] When you do not use a system timer, there is no need to add a system stack used by the system clock interrupt handler. The system stack size used by the system clock interrupt handler is whichever larger of the two cases below: 27 + maximum size used by cyclic handler 25 + maximum size used by alarm handler C language Using the stack size calculation utility STK Viewer10, calculate the stack size of each Alarm or Cyclic handler. Assembly language The stack size to be used by Alarm or Cyclic handler = register to be used + user size + stack size to be used by system call If neither cyclic handler nor alarm handler is used, then = 18 bytes When using the interrupt handler and system clock interrupt handler in combination, add the stack sizes used by both. 10 STK Viewer is a utility to calculate the stack size included with Renesas C Compiler NC30WA NC30WA. Chapter 2 System Call Reference 2.1. Task Management Functions 2.1.1. sta_tsk(Start Task) [( System call name )] sta_tsk Starts the task. [( Calling by the C language )] #include ER sta_tsk (tskid, stacd); > ID INT tskid; stacd; The ID No. of the task to be started Task start code > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc sta_tsk tskid, stacd > tskid stacd [-] [-] The ID No. of the task to be started Task start code > Register name R0 R1 R2 A0 Contents after system call issuance Error code -Task start code The ID No. of the task to be started [( Error codes )] E_OK E_OBJ 2 00000H 00000H(-H'0000): 0FFC1H(-H'003f): Normal End Invalid object state 2.1.1 sta_tsk(Start Task) [( Function description )] This system call starts the task indicated by tskid. That is, the specified task is put from the DORMANT state to the READY state or the RUN state. The startup code stacd is 16 bits. In a C language program, stacd is passed to the startup task as an argument. In an assembly language program, stacd is stored in the startup task's R0 register. This system call is valid only when the specified task is idle (DORMANT). Therefore, if a request is issued when the task is not idle (DORMANT), an error E_OBJ is returned to the system call issued task. When this system call is issued, a task is activated by the start address and priority defined in the configuration file.11 If a task is reactivated after being terminated by ter_tsk or ext_tsk, it starts under the following conditions:12 The task starts from the start address set in the configuration file. The wakeup request count is cleared to 0. The priority is the initial priority specified in the configuration file The initial register values except PC, R1(stacd), SB and FLG register are 0(zero). Register Initial register values R0 00H R1 Task start code R2 00H R3 00H A0 00H A1 00H SB _SB_ FB 00H FLG C0H PC Task start address This system call can be issued from only tasks. If you want it to be issued from the interrupt handler, cyclic handler, or alarm handler, you must use a ista_tsk system call. 11 However,the specified task does not always operate immediately.The operation always depends on the state of the ready queue at that time. 12 Namely,the task totally starts from the reset state. 2.1.1 sta_tsk(Start Task) 3 [( Usage example )] > #include #include "id.h" void task() { sta_tsk( ID_task2, stacd ); : } void task2(int msg) { if(msg = 0) : } > .INCLUDE mr30.inc .GLB task,task2 task: sta_tsk #ID_task2, msg : task2: cmp.w #0,R0 : 4 2.1.1 sta_tsk(Start Task) 2.1.2. ista_tsk(Start Task) [( System call name )] ista_tsk Starts the task(for the handler only). [( Calling by the C language )] #include ER ista_tsk (tskid, stacd); > ID INT tskid; stacd; The ID No. of the task to be started Task start code > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc ista_tsk tskid, stacd > tskid stacd [-] [-] The ID No. of the task to be started Task start code > Register name Contents after system call issuance R0 R1 R2 A0 Error code -Task start code The ID No. of the task to be started [( Error codes )] E_OK E_OBJ 00000H 00000H(-H'0000): 0FFC1H(-H'003f): Normal End Invalid object state [( Function description )] Use this system call when you want to use the same function as that of the sta_tsk system call from the interrupt handler, cyclic handler, or alarm handler. 2.1.2 ista_tsk(Start Task) 5 [( Usage example )] > #include #include "id.h" void inthand() { ista_tsk( ID_task2, stacd ); : } void task2(int msg) { if(msg = 0) : } > .INCLUDE mr30.inc .GLB intr intr: ista_tsk #ID_task2, msg : ret_int 6 2.1.2 ista_tsk(Start Task) 2.1.3. ext_tsk(Exit Task) [( System call name )] ext_tsk Ends the own task. [( Calling by the C language )] #include void ext_tsk (); > None > Control is not returned to the task which issued this system call [( Calling by the assembly language )] .include mr30.inc ext_tsk > None > Control is not returned to the task which issued this system call [( Error codes )] Control is not returned to the task which issued this system call [( Function description )] This system call ends the own task; that is, it puts the own task from the RUN state to the DORMANT state. Once a task has been terminated, it does not operate until activated again by the sta_tsk or ista_tsk system call. When a task is activated again in this way, it can be started only from the start address defined in the configuration file. That is, a task terminated by ext_tsk and then activated by sta_tsk operates as if it was reset. When this system call is issued, the semaphore obtained by the own task is not freed. When issuing loc_cpu or dis_dsp, make sure you then issue unl_cpu or ena_dsp before ending the task (issue ext_tsk). This system call can be issued only from tasks. It cannot be issued from the interrupt handler, the cyclic handler, and the alarm handler. 2.1.3 ext_tsk(Exit Task) 7 [( Usage example )] > #include void task(void) { : ext_tsk(); } > .INCLUDE .GLB task: : ext_tsk 8 mr30.inc task 2.1.3 ext_tsk(Exit Task) 2.1.4. ter_tsk(Terminate Task) [( System call name )] ter_tsk Terminates a task forcibly. [( Calling by the C language )] #include ER ter_tsk (tskid); > ID tskid; The ID No. of the task to be forcibly terminated > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc ter_tsk tskid > tskid [-] The ID No. of the task to be forcibly terminated > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the task to be forcibly terminated [( Error codes )] E_OK E_OBJ 00000H 00000H(-H'0000): 0FFC1H(-H'003f): Normal End Invalid object state [( Function description )] The task indicated by tskid is forcibly terminated. This system call cannot specify the own task. To terminate the own task, use the ext_tsk system call. If a specified task is in WAIT state being linked to some waiting queue13 the task is removed from the queue by execution of this system call. However, the semaphores, etc. that have been acquired by the specified task before that are not relinquished. If the task indicated by tskid is in DORMANT state, the system returns an error E_OBJ for the system call. This system call can be issued only from tasks. It cannot be issued from the interrupt handler, the cyclic handler, and the alarm handler. 13 Timeout wait queue, eventflag wait queue, semaphore wait queue, or mailbox wait queue is possible. 2.1.4 ter_tsk(Terminate Task) 9 [( Usage example )] > #include #include "id.h" void task() { : ter_tsk( ID_main ); : ext_tsk(); } > .INCLUDE mr30.inc .GLB task task: : ter_tsk #ID_task2 : .GLB task2 task2: : 10 2.1.4 ter_tsk(Terminate Task) 2.1.5. dis_dsp(Disable Dispatch) [( System call name )] dis_dsp Disable dispatch of the task. [( Calling by the C language )] #include ER dis_dsp (); > None > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc dis_dsp > None > Register name Contents after system call issuance R0 R1 R2 A0 Error code - [( Error codes )] E_OK 00000H 00000H(-H'0000): Normal End [( Function description )] Disables task dispatch. After executing this system call, task dispatch is disabled until the ena_dsp system call is executed. Therefore, even when a task with higher priority than the task that executed dis_dsp by a system call issued from an interrupt handler or a task that executed dis_dsp is placed in READY state, no time is dispatched to that task. Namely, dispatching to tasks with higher priority is delayed until the dispatch disabled condition is terminated. However, since external interrupts are not disabled, an interrupt handler is activated even while dispatch is disabled. If a task already in a dispatch disabled state issues dis_dsp, no error is assumed; the result is only that the dispatch disabled state continues. However, a dispatch disabled state is cleared by issuing only one ena_dsp no matter how many times dis_dsp may have been issued. When issuing loc_cpu or dis_dsp, make sure you then issue unl_cpu or ena_dsp before ending the task (issue ext_tsk). This system call can only be issued from tasks, and cannot be issued from the interrupt handler, cyclic handler, or alarm handler. 2.1.5 dis_dsp(Disable Dispatch) 11 [( Usage example )] > #include #include "id.h" void task() { : dis_dsp(); : } > .INCLUDE .GLB task: : dis_dsp : 12 mr30.inc task 2.1.5 dis_dsp(Disable Dispatch) 2.1.6. ena_dsp(Enable Dispatch) [( System call name )] ena_dsp Permits dispatch of the task. [( Calling by the C language )] #include ER ena_dsp(); > None > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc ena_dsp > None > Register name Contents after system call issuance R0 R1 R2 A0 Error code - [( Error codes )] E_OK 00000H 00000H(-H'0000): Normal End [( Function description )] Enables task dispatch. Namely, it clears a dispatch disabled state set by dis_dsp, thereby activating the scheduler. If a task not in a dispatch disabled state issues ena_dsp, no error assumed; the result is only that the dispatch enabled state continues. This system call can only be issued from tasks, and cannot be issued from the interrupt handler, cyclic handler, or alarm handler. 2.1.6 ena_dsp(Enable Dispatch) 13 [( Usage example )] > #include #include "id.h" void task() { : ena_dsp(); : } > .INCLUDE .GLB task: : ena_dsp : 14 mr30.inc task 2.1.6 ena_dsp(Enable Dispatch) 2.1.7. chg_pri(Change Task Priority) [( System call name )] chg_pri Changes the priority of a task. [( Calling by the C language )] #include ER chg_pri (tskid,tskpri); > ID PRI tskid; tskpri; The ID No. of the task whose priority is changed The priority to be changed > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc chg_pri tskid, tskpri > tskid tskpri [-] [-] The ID No. of the task whose priority is changed The priority to be changed > Register name R0 R1 R2 A0 Contents after system call issuance Error code -The priority to be changed The ID No. of the task whose priority is changed [( Error codes )] E_OK E_OBJ 00000H 00000H(-H'0000): 0FFC1H(-H'003f): 2.1.7 chg_pri(Change Task Priority) Normal End Invalid object state 15 [( Function description )] Changes the priority of the task indicated by tskid to a value indicated by tskpri. Furthermore, the task is rescheduled according to the result of this modification. If this system call is executed for a task linked to the ready queue (including a task in RUN state) or a task being queued in order of priorities, the task is moved to the tail of the queue of the relevant priority. Similarly, if the same priority as the previous one is specified, the task is moved to the tail of the queue of that priority.14 Task priority is higher when its number is lower. Priority 1 is the highest. The minimum value that can be specified for a priority is 1. The maximum value is the one specified in the configuration file. The range of the specifiable priority is 1 to 255. For example, when the following is specified in the configuration file, the range of the specifiable priorities is 1 to 13 15 system{ stack_size priority = 0x100; = 13; }; If you specify tskid = TSK_SELF = 0, it specifies the task itself. This system call cannot be used to change the priority of a task in DORMANT state. There fore, if the task indicated by tskid is in DORMANT state, the system returns an error E_OBJ for the system call. This system can be issued from only tasks. If you want it to be issued from the interrupt handler, cyclic handler, or alarm handler, you must use a ichg_pri system call. [( Usage example )] > #include #include "id.h" void task() { : chg_pri (ID_task2, 2); : } > .INCLUDE mr30.inc .GLB task task: : chg_pri #ID_task2,#2 : 14 Therefore, by issuing this system call to set the same priority as the current one for the task itself, you can in effect relinquish control of execution of the task. 15 Switchover to a task with lower priority calls for greater processing time and greater interrupt disabled time. Therefore, the narrower the priority range, the better. So reduce the priority range to a possible minimum. 16 2.1.7 chg_pri(Change Task Priority) 2.1.8. ichg_pri(Change Task Priority) [( System call name )] ichg_pri Changes the priority of a task (for the handler only). [( Calling by the C language )] #include ER ichg_pri (tskid,tskpri); > ID PRI tskid; tskpri; The ID No. of the task whose priority is changed The priority to be changed > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc ichg_pri tskid, tskpri > tskid tskpri [-] [-] The ID No. of the task whose priority is changed The priority to be changed > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The priority to be changed The ID No. of the task whose priority is changed [( Error codes )] E_OK E_OBJ 00000H 00000H(-H'0000): 0FFC1H(-H'003f): Normal End Invalid object state [( Function description )] This system call is issued from the interrupt handler, the cyclic handler, or the alarm handler to provide the same functions as the chg_pri system call. In this system call, you cannot use tskid = TSK_SELF = 0 to specify the own task. 2.1.8 ichg_pri(Change Task Priority) 17 [( Usage example )] > #include #include "id.h" void inthand() { : ichg_pri(ID_main, 2); : } > .INCLUDE mr30.inc .GLB intr intr: : ichg_pri #ID_task2, 2 : ret_int 18 2.1.8 ichg_pri(Change Task Priority) 2.1.9. rot_rdq(Rotate Ready Queue) [( System call name )] rot_rdq Rotates the ready queue of a task. [( Calling by the C language )] #include ER rot_rdq (tskpri); > PRI tskpri; The priority of the ready queue to be rotated > E_OK is always returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc rot_rdq tskpri > tskpri [-] The priority of the ready queue to be rotated > Register name R0 R1 R2 A0 Contents after system call issuance Error code -The priority of the ready queue to be rotated - [( Error codes )] E_OK 00000H 00000H(-H'0000): 2.1.9 rot_rdq(Rotate Ready Queue) Normal End 19 [( Function description )] This system call rotates the ready queue having the priority specified by tskpri. That is, this system call reconnects the task linked to the head of the ready queue having the specified priority to the end of it in order to switch between the tasks having the same priority. See Figure 2.1. Priority 1 TCB Priority 2 TCB TCB Priority n TCB TCB TCB Reconnect to the end Figure 2.1: Ready Queue Operation by rot_rdq System Call Issuing this system call at a certain interval allows round robin scheduling. Specification tskpri = TPRI_RUN = 0 causes the ready queue with the priority of the own task to be rotated. If this system call is used to specify the priority of the own task, the task is moved to the tail of that ready queue. This system call can be issued only from tasks. The system call which be issued from the interrupt handler, the cyclic handler, or the alarm handler is the irot_rdq. 20 2.1.9 rot_rdq(Rotate Ready Queue) [( Usage example )] > #include void task() { : rot_rdq(2); : } > .INCLUDE mr30.inc .GLB task task: : rot_rdq #2 : 2.1.9 rot_rdq(Rotate Ready Queue) 21 2.1.10. irot_rdq(Rotate Ready Queue) [( System call name )] irot_rdq Rotates the ready queue of a task (for the handler only). [( Calling by the C language )] #include ER irot_rdq (tskpri); > PRI tskpri; The priority of the ready queue to be rotated > E_OK is always returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc irot_rdq tskpri > tskpri [-] The priority of the ready queue to be rotated > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The priority of the ready queue to be rotated - [( Error codes )] E_OK 00000H 00000H(-H'0000): Normal End [( Function description )] This system call is issued from the interrupt handler, the cyclic handler, or the alarm handler to provide the same functions as the rot_rdq system call. If irot_rdq (tskpri = TPRI_RUN) is issued, the ready queue of the priority equal to that the task that was executing when the interrupt handler was invoked is rotated. Issuing this system call allows round robin scheduling. 22 2.1.10 irot_rdq(Rotate Ready Queue) [( Usage example )] In this example, round robin scheduling is implemented by rotating the ready queue having priority 2 at a certain intervals by the cyclic handler. > #include void cyc() { : irot_rdq(2); : } > .INCLUDE mr30.inc .GLB cyc cyc: : irot_rdq #2 : 2.1.10 irot_rdq(Rotate Ready Queue) 23 2.1.11. rel_wai(Release Task Wait) [( System call name )] rel_wai Releases the task WAIT state forcibly. [( Calling by the C language )] #include ER rel_wai (tskid); > ID tskid; The ID No. of the task to be forcibly released from the WAIT state > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc rel_wai tskid > tskid [-] The ID No. of the task to be forcibly released from the WAIT state > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the task to be forcibly released from the WAIT state [( Error codes )] E_OK E_OBJ 00000H 00000H(-H'0000): 0FFC1H(-H'003f): Normal End Invalid object state [( Function description )] This system call unconditionally releases the task specified by tskid from the WAIT state(Except SUSPEND state). Error E_RLWAI is returned to the released task. If the task is linked to some waiting queue, the task is removed from the queue 16 by execution of this system call. If the task is not in WAIT state, the system returns an error E_OBJ to the system call issued task. This system call cannot specify the own task. This system call can be issued only from tasks. The system call which be issued from the interrupt handler, the cyclic handler, or the alarm handler is the irel_wai. 16 Timeout wait queue, eventflag wait queue, semaphore wait queue, or mailbox wait queue is possible. 24 2.1.11 rel_wai(Release Task Wait) [( Usage example )] > #include #include "id.h" void task() { : if( rel_wai( ID_main ) != E_OK ) error("Can't rel_wai main()\n"); : } > .INCLUDE mr30.inc .GLB task task: : rel_wai #ID_main : 2.1.11 rel_wai(Release Task Wait) 25 2.1.12. irel_wai(Release Task Wait) [( System call name )] irel_wai Releases the task WAIT state forcibly (for the handler only). [( Calling by the C language )] #include ER irel_wai (tskid); > ID tskid; The ID No. of the task to be forcibly released from the WAIT state > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc irel_wai tskid > tskid [-] The ID No. of the task to be forcibly released from the WAIT state > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the task to be forcibly released from the WAIT state [( Error codes )] E_OK E_OBJ 00000H 00000H(-H'0000): 0FFC1H(-H'003f): Normal End Invalid object state [( Function description )] This system call is issued from the interrupt handler, the cyclic handler, or the alarm handler to provide the same functions as the rel_wai system call. 26 2.1.12 irel_wai(Release Task Wait) [( Usage example )] > #include #include "id.h" void inthand() { : if( irel_wai( ID_main ) != E_OK ) error("Can't irel_wai task(2)\n"); : } > .INCLUDE mr30.inc .GLB intr intr: : irel_wai #ID_main : ret_int 2.1.12 irel_wai(Release Task Wait) 27 2.1.13. get_tid(Get Self Task ID) [( System call name )] get_tid Gets the ID of the self task [( Calling by the C language )] #include ER get_tid (p_tskid); > p_tskid; ID The variable in which the task ID is stored. (Locate the p_tskid area betweeen 0 and FFFFH.) > The returned function value is always E_OK. The ID No. of the own task is set in the area indicated by p_tskid. [( Calling by the assembly language )] .include mr30.inc get_tid > None > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID of the self task [( Error codes )] E_OK 00000H 00000H(-H'0000): Normal End [( Function description )] Gets the ID No. of the own task. FALSE = 0 is returned if the system call is issued from the interrupt handler, cyclic handler, or alarm handler. 28 2.1.13 get_tid(Get Self Task ID) [( Usage example )] > #include void task() { ID tskid; : get_tid(&tskid); : } > .INCLUDE .GLB task: : get_tid : mr30.inc task 2.1.13 get_tid(Get Self Task ID) 29 2.1.14. ref_tsk(Refer Task Status) [( System call name )] ref_tsk Reference Task Status [( Calling by the C language )] #include ER ref_tsk (pk_rtsk,tskid); > ID T_RTSK tskid; pk_rtsk; The ID No. of the task to Reference Task Packet address to Reference Task. (Locate the pk_rtsk area betweeen 0 and FFFFH.) > An error code is returned as the return value of a function. The structure indicated by pk_rtsk returns the following data. typedef struct t_rtsk { VP exinf; /* Extended information */ PRI tskpri; /* Current task priority level */ UINT tskstat; /* Task status */ UINT tskwait; /* Reason for wait */ ID wid; /* Wait object ID */ } T_RTSK; [( Calling by the assembly language )] .include mr30.inc ref_tsk tskid > taskid pk_rtsk [-] [-] The ID No. of the task to Reference Task Packet address to Reference Task > Register name R0 R1 R2 A0 A1 Contents after system call issuance Error code -The ID No. of the task to Reference Task Packet address to Reference Task The area indicated by pk_rtsk returns the following information. offset +0 exinf Extended information +4 tskpri Current task priority level +6 tskstat Task status +8 tskwait Reason for wait +10 wid Wait object ID [( Error codes )] E_OK 30 00000H 00000H(-H'0000): Normal End 2.1.14 ref_tsk(Refer Task Status) [( Function description )] Refers to the status of the task indicated by tskid then returns the following task information as return values. exinf Returns extended task information in exinf tskpri Returns the task priority level in tskpri tskstat Returns a value corresponding to the status of the specified task in tskstat TTS_RUN TTS_RDY TTS_WAI TTS_SUS TTS_WAS TTS_DMT (0001H 0001H) (0002H 0002H) (0004H 0004H) (0008H 0008H) (000CH 000CH) (0010H 0010H) RUN state READY state WAIT state SUSPEND state WAIT-SUSPEND state DORMANT state tskwait If the target task is in the wait state, the cause of the wait is returned in tskwait. The following shows the values of the respective causes. TTW_SLP TTW_DLY TTW_FLG TTW_SEM TTW_MBX (0001H 0001H) (0002H 0002H) (0010H 0010H) (0020H 0020H) (0040H 0040H) Waiting with slp_tsk or tslp_tsk Waiting with dly_tsk Waiting with wai_flg or twai_flg Waiting with wai_sem or twai_sem Waiting with rcv_msg or trcv_msg wid If the target task is in the wait state, its object ID No. is returned in wid. A task may specify itself by specifying tskid = TSK_SELF = 0. Note, however, an interrupt handler cannot specify itself by specifying tskid = TSK_SELF. If ref_tsk is issued by the interrupt handler targeting the interrupted task the RUN status (TTS_RUN) is returned in tskstat. This system call can be issued from both tasks and handlers. 2.1.14 ref_tsk(Refer Task Status) 31 [( Usage example )] > #include #include "id.h" void task() { T_RTSK rtsk; : ref_tsk( &rtsk, ID_main ); : } > rtsk: .blkb 10 .INCLUDE mr30.inc .GLB task task: : ref_tsk #ID_task2, #rtsk : 32 2.1.14 ref_tsk(Refer Task Status) 2.2. Synchronization Functions Attached to Task 2.2.1. sus_tsk(Suspend Task) [( System call name )] sus_tsk Puts a task in the SUSPEND state. [( Calling by the C language )] #include ER sus_tsk (tskid); > ID tskid; The ID No. of the task to be put in the SUSPEND state > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc sus_tsk tskid > tskid [-] The ID No. of the task to be put in the SUSPEND state > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the task to be put in the SUSPEND state [( Error codes )] E_OK E_QOVR E_OBJ 00000H 00000H(-H'0000): 0FFB7H(-H'0049): 0FFC1H(-H'003f): Normal End Queuing or nest overflow Invalid object state [( Function description )] This system call discontinues the execution of the task specified by tskid and puts it in the SUSPEND state. The SUSPEND state is cleared by issuing the rsm_tsk system call. When the task specified by tskid is in the DORMANT state, error E_OBJ is returned as the system call return value. This system call cannot specify the own task. The SUSPEND request nesting by this system call is not performed. Therefore, when the task specified by tskid is in the SUSPEND state, error E_QOVR is returned as the system call return value This system call can be issued only from tasks. The system call which be issued from the interrupt handler, the cyclic handler, or the alarm handler is the isus_tsk. 2.2.1 sus_tsk(Suspend Task) 33 [( Usage example )] > #include #include "id.h" void task() { : if( sus_tsk( ID_main ) != E_OK ) printf("Can't suspend task main()\n"); : } > .INCLUDE mr30.inc .GLB task task: : sus_tsk #ID_task2 : 34 2.2.1 sus_tsk(Suspend Task) 2.2.2. isus_tsk(Suspend Task) [( System call name )] isus_tsk Puts a task in the SUSPEND state (for the handler only) [( Calling by the C language )] #include ER isus_tsk (tskid); > ID tskid; The ID No. of the task to be put in the SUSPEND state > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc isus_tsk tskid > tskid [-] The ID No. of the task to be put in the SUSPEND state > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the task to be put in the SUSPEND state [( Error codes )] E_OK E_QOVR E_OBJ 00000H 00000H(-H'0000): 0FFB7H(-H'0049): 0FFC1H(-H'003f): Normal End Queuing or nest overflow Invalid object state [( Function description )] This system call is issued from the interrupt handler, the cyclic handler, or the alarm handler to provide the same functions as the sus_tsk system call. Since this is a system call from a handler, it allows you to specify any task ID. Therefore, this system call be used to suspend an interrupted task. 2.2.2 isus_tsk(Suspend Task) 35 [( Usage example )] > #include #include "id.h" void inthand() { : if( isus_tsk( ID_main ) != E_OK ) printf("Can't suspend main()\n"); : } > .INCLUDE mr30.inc .GLB intr intr: : isus_tsk #ID_main : ret_int 36 2.2.2 isus_tsk(Suspend Task) 2.2.3. rsm_tsk(Resume Task) [( System call name )] rsm_tsk Resumes the task in the SUSPEND state. [( Calling by the C language )] #include ER rsm_tsk (tskid); > ID tskid; The ID No. of the task to be taken from the SUSPEND state > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc rsm_tsk tskid > tskid [-] The ID No. of the task to be taken from the SUSPEND state > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the task to be taken from the SUSPEND state [( Error codes )] E_OK E_OBJ 00000H 00000H(-H'0000): 0FFC1H(-H'003f): Normal End Invalid object state [( Function description )] If the task indicated by tskid has been suspended by sus_tsk system call, this system call clears its forced wait state and restarts execution of the task. In this case, the task is linked at the tail of the ready queue. For the request issued when the task is not in forced waiting (SUSPEND) or the DORMANT state, error code E_OBJ is returned to the task which issued the system call. Since this system call is intended for tasks in forced waiting (SUSPEND) or double waiting (WAITSUSPEND) states, it cannot be used to specify the own task. This system call can be issued only from tasks. The system call which be issued from the interrupt handler, the cyclic handler, or the alarm handler is the irsm_tsk. 2.2.3 rsm_tsk(Resume Task) 37 [( Usage example )] > #include #include "id.h" void task() { : if( rsm_tsk( ID_main ) != E_OK ) printf("Can't resume main()\n"); : } > .INCLUDE mr30.inc .GLB task task: : rsm_tsk #ID_task2 : 38 2.2.3 rsm_tsk(Resume Task) 2.2.4. irsm_tsk(Resume Task) [( System call name )] irsm_tsk Resumes the task in the SUSPEND state (for the handler only). [( Calling by the C language )] #include ER irsm_tsk (tskid); > ID tskid; The ID No. of the task to be taken from the SUSPEND state > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc irsm_tsk tskid > tskid [-] The ID No. of the task to be taken from the SUSPEND state > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the task to be taken from the SUSPEND state [( Error codes )] E_OK E_OBJ 00000H 00000H(-H'0000): 0FFC1H(-H'003f): Normal End Invalid object state [( Function description )] This system call is issued from the interrupt handler, the cyclic handler, or the alarm handler to provide the same functions as the rsm_tsk system call. 2.2.4 irsm_tsk(Resume Task) 39 [( Usage example )] > #include #include "id.h" void inthand() { : irsm_tsk( ID_main ); : } > .INCLUDE mr30.inc .GLB intr intr: : irsm_tsk #ID_main : 40 2.2.4 irsm_tsk(Resume Task) 2.2.5. slp_tsk(Sleep Task) [( System call name )] slp_tsk Puts the task in the WAIT state. [( Calling by the C language )] #include ER slp_tsk (); > None > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc slp_tsk > None > Register name R0 R1 R2 A0 Contents after system call issuance Error code - [( Error codes )] E_OK E_RLWAI 00000H 00000H(-H'0000): 0FFAAH(-H'0056): Normal End Wait state forcibly cleared [( Function description )] This system call puts the self task from the RUN state to the WAIT state. The WAIT state is cleared by the system call of the task wakeup issued for this task17 or the system call which forcibly clears the WAIT state. 18 In the former, error code E_OK is returned; in the latter, error code E_RLWAI is returned. When a task put in the WAIT state by slp_tsk is suspended (sus_tsk) by another task, that task is put in the WAIT-SUSPEND state. In this case, the task is still in the SUSPEND state even if the WAIT state is cleared by the system call of task wakeup and the execution of the task is not resumed until the rsm_tsk, irsm_tsk system call is issued. This system call can be issued only from tasks. 17 18 wup_tsk,iwup_tsk System call rel_wai,irel_wai System call 2.2.5 slp_tsk(Sleep Task) 41 [( Usage example )] > #include #include "id.h" void task() { : if( slp_tsk() != E_OK ) error("Forced wakeup\n"); : } > .INCLUDE mr30.inc .GLB task task: : slp_tsk : 42 2.2.5 slp_tsk(Sleep Task) 2.2.6. tslp_tsk(Sleep Task with Timeout) [( System call name )] tslp_tsk Switches the task to the fixed-time wait state [( Calling by the C language )] #include ER tslp_tsk (tmout); > TMO tmout; Timeout value > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc tslp_tsk tmout > tmout [-] Timeout value > Register name R0 R1 R2 R3 Contents after system call issuance Error code -Timeout value [( Error codes )] E_OK E_TMOUT E_RLWAI 00000H 00000H(-H'0000): 0FFABH(-H'0055): 0FFAAH(-H'0056): 2.2.6 tslp_tsk(Sleep Task with Timeout) Normal End Polling failed or timeout Wait state forcibly cleared 43 [( Function description )] Switches the task from the (RUN) status in which it runs for the specified time only to the WAIT state. A wait state invoked by this system call is cancelled in the following cases: When a system call19 to start a task is invoked from another task or interrupt. Error code E_OK is returned. When a system call20 to forcibly cancel the wait state is invoked from another task or interrupt. Error code E_RLWAI is returned. When the time specified in tmout has elapsed. When the tmout is 0 and the value of the wakeup request count count is 0. Error code E_TMOUT is returned. The unit of time specified in tmout is the unit of time of the system clock, specified in the configuration file. tslp_tsk(10); For example, if it is 10ms and the following is written in the program the own task is placed from the execution (RUN) state into a wait (WAIT) state and held in that state for 100 ms. You can specify a timeout (tmout) of -1 to 0x7FFF. Specifying TMO_FEVR = -1 can be used to set the timeout period to forever (no timeout). In this case, tslp_tsk will function exactly the same as slp_tsk causing the issuing task to wait forever for wup_tsk to be issued. This system call can be issued only from tasks. [( Usage example )] > #include #include "id.h" void task() { : if( tslp_tsk( 10 ) != E_TMOUT ) printf("Forced wakeup\n"); : } > .INCLUDE mr30.inc .GLB task task: : tslp_tsk #200 : 19 20 wup_tsk, iwup_tsk System call rel_wai, irel_wai System call 44 2.2.6 tslp_tsk(Sleep Task with Timeout) 2.2.7. wup_tsk(Wakeup Task) [( System call name )] wup_tsk Wakes up the task in the wait state. [( Calling by the C language )] #include ER wup_tsk (tskid); > ID tskid; The ID No. of the task to be waked up > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc wup_tsk tskid > tskid [-] The ID No. of the task to be waked up > Register name R0 R1 R2 A0 Contents after system call issuance Error code -The ID No. of the task to be waked up [( Error codes )] E_OK E_QOVR E_OBJ 00000H 00000H(-H'0000): 0FFB7H(-H'0049): 0FFC1H(-H'003f): 2.2.7 wup_tsk(Wakeup Task) Normal End Queuing or nest overflow Invalid object state 45 [( Function description )] If the task specified by tskid is in a wait (WAIT) state entered by execution of slp_tsk,tslp_tsk this system call clears the task's wait state to place it in an executable (READY) or execution (RUN) state. Also, if the task specified by tskid is in a double-wait (WAIT-SUSPEND) state, the system call only clears the wait state and places the task in a forced wait (SUSPEND) state. For a request issued when the task is in an idle (DORMANT) state, an error E_OBJ is returned to the system call issued task. Note also that this system call cannot specify the own task. If this system call is issued for tasks that are not in a wait (WAIT) state entered by execution of slp_tsk, tslp_tsk or a double-wait (WAIT-SUSPEND) state, wakeup requests are accumulated. More specifically, the wakeup request count in the TCB21 TCB21 of the task is incremented by 122 The maximum value of the wakeup request count is 0x7FFF(32767). If a wakeup request is issued beyond 0x7FFF(32767), the count remains 0x7FFF(32767) and error code E_QOVR is returned to the task which issued this system call. This system call can be issued only from tasks. The system call which be issued from the interrupt handler, the cyclic handler, or the alarm handler is the iwup_tsk. [( Usage example )] > #include #include "id.h" void task() { : if( wup_tsk( ID_main ) != E_OK ) printf("Can't wakeup main()\n"); : } > .INCLUDE mr30.inc .GLB task task: : wup_tsk #ID_task2 21 Task Control Block. This wakeup request count stores the counts of wakeup requests that have not been serviced because the intended task was not in a wait (WAIT) or a double-wait (WAIT-SUSPEND) state when the wup_tsk, iwup_tsk system call was issued to wake it up. If the task is being placed in a wait state by a slp_tsk, tslp_tsk system call when the wakeup request count is more than 1, the wakeup request count is decremented by 1. In this case, the task does not actually enter the wait (WAIT) state. Tasks can only be placed in a wait (WAIT) state by a slp_tsk, tslp_tsk system call when the wakeup request count is 0. 22 46 2.2.7 wup_tsk(Wakeup Task) 2.2.8. iwup_tsk(Wakeup Task) [( System call name )] iwup_tsk Wakes up the task in the wait state (for the handler only). [( Calling by the C language )] #include ER iwup_tsk (tskid); > ID tskid; The ID No. of the task to be waked up > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc iwup_tsk tskid > tskid [-] The ID No. of the task to be waked up > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the task to be waked up [( Error codes )] E_OK E_QOVR E_OBJ 00000H 00000H(-H'0000): 0FFB7H(-H'0049): 0FFC1H(-H'003f): Normal End Queuing or nest overflow Invalid object state [( Function description )] This system call is issued from the interrupt handler, the cyclic handler, or the alarm handler to provide the same functions as the wup_tsk system call. 2.2.8 iwup_tsk(Wakeup Task) 47 [( Usage example )] > #include #include "id.h" void inthand() { if( iwup_tsk( ID_main ) != E_OK ) printf("Can't wakeup main()\n"); : } > .INCLUDE mr30.inc .GLB intr intr: : iwup_tsk #ID_main : ret_int 48 2.2.8 iwup_tsk(Wakeup Task) 2.2.9. can_wup(Cancel Wakeup Task) [( System call name )] can_wup Cancels a task wakeup request. [( Calling by the C language )] #include ER can_wup (p_wupcnt,tskid); > INT *p_wupcnt; ID tskid; The variable to store the count of canceled wakeup. (Locate the p_wupcnt area between 0 and FFFFH) The ID No. of the task whose wakeup request is to be canceled > An error code is returned as the return value of a function. The count of canceled wakeup requests is set to variable wupcnt [( Calling by the assembly language )] .include mr30.inc can_wup tskid > tskid [-] The ID No. of the task whose wakeup request is to be canceled > Register name Contents after system call issuance R0 R1 R2 Error code -The variable to store the count of canceled wakeup The ID No. of the task whose wakeup request is to be canceled A0 [( Error codes )] E_OK E_OBJ 00000H 00000H(-H'0000): 0FFC1H(-H'003f): Normal End Invalid object state [( Function description )] This system call clears the wakeup request count for the task specified by tskid to zero. In other words, because the task to be waked up by the wup_tsk, iwup_tsk system call before issuing the can_wup system call was not in the WAIT or WAIT-SUSPEND state, the can_wup system call clears all the accu- mulated wakeup requests. For the return value of this system call, the wakeup request count before being cleared to zero, namely the canceled wakeup request count, is returned. For the request issued when the task whose wakeup request is to be canceled is in the dormant state, error code E_OBJ is returned to the task which issued this system call. When issued from only the task, this system call can tskid=TSK_SELF=0 as the own task. The return parameter value(*p_wupcnt) is indeterminate in all cases other than E_OK. This system call can be issued from either tasks or handlers. 2.2.9 can_wup(Cancel Wakeup Task) 49 [( Usage example )] > #include void task() { INT wupcnt; : if( can_wup(&wupcnt,ID_main) != E_OK ) printf("Can't cancle wakeup main() \n"); : } > .INCLUDE mr30.inc .GLB task task: : can_wup #ID_task2 : 50 2.2.9 can_wup(Cancel Wakeup Task) 2.3. Eventflags 2.3.1. set_flg(Set Eventflag) [( System call name )] set_flg Sets an eventflag. [( Calling by the C language )] #include ER set_flg (flgid, setptn); > ID UINT flgid; setptn; The ID No. of the eventflag to be set The bit pattern to be set > E_OK is always returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc set_flg flgid, setptn > flgid setptn [-] [-] The ID No. of the eventflag to be set The bit pattern to be set > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The bit pattern to be set The ID No. of the eventflag to be set [( Error codes )] E_OK 00000H 00000H(-H'0000): Normal End [( Function description )] Among the 16-bit eventflags indicated by flgid, this system call sets the bit that is indicated by setptn. Namely, it logical OR's the value of the eventflags indicated by flgid with setptn. If, as a result of the modification of the eventflag value, conditions to stop waiting are met for the task that has been kept waiting for that eventflag by a wai_flg, twai_flg system call, the task is freed from a wait state. Multiple tasks can be kept waiting for the same eventflag. In this case, the multiple tasks can be simultaneously freed from a wait state by one issuance of a set_flg system call. However, if a task in a waiting queue was waiting for the eventflag to be set by a clear specification, all tasks up to that task are freed from the wait state. If all bits in setptn are set to 0, no operation will be performed on the eventflag concerned; but this does not result in an error. This system call can be issued only from tasks. The system call which be issued from the interrupt handler, the cyclic handler, or the alarm handler is the iset_flg system call. [( Usage example )] If the eventflag pattern before issuing this system call was 0xf, the pattern after this system 2.3.1 set_flg(Set Eventflag) 51 call becomes 0xff. > #include #include "id.h" void task(void) { : set_flg( ID_flg,(UINT)0xf0 ); : ext_tsk(); } > .INCLUDE mr30.inc .GLB task task: : set_flg #ID_flg,#0f0H : ext_tsk 52 2.3.1 set_flg(Set Eventflag) 2.3.2. iset_flg(Set Eventflag) [( System call name )] iset_flg Sets an eventflag (for the handler only). [( Calling by the C language )] #include ER iset_flg (flgid, setptn); > ID UINT flgid; setptn; The ID No. of the eventflag to be set The bit pattern to be set > E_OK is always returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc iset_flg flgid, setptn > flgid setptn [-] [-] The ID No. of the eventflag to be set The bit pattern to be set > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The bit pattern to be set The ID No. of the eventflag to be set [( Error codes )] E_OK 00000H 00000H(-H'0000): Normal End [( Function description )] This system call is issued from the interrupt handler, the cyclic handler, or the alarm handler to provide the same functions as the set_flg system call. 2.3.2 iset_flg(Set Eventflag) 53 [( Usage example )] If the eventflag pattern before issuing this system call was 0xf, the pattern after this system call becomes 0xff. > #include #include "id.h" void inthand(void) { : iset_flg( ID_flg, (UINT)0xf0); : } > .INCLUDE .GLB intr: : iset_flg : ret_int 54 mr30.inc intr #ID_flg,#0f0H 2.3.2 iset_flg(Set Eventflag) 2.3.3. clr_flg(Clear Eventflag) [( System call name )] clr_flg Clears an eventflag. [( Calling by the C language )] #include ER clr_flg (flgid, clrptn); > ID UINT flgid; clrptn; The ID No. of the eventflag to be cleared The bit pattern to be cleared > E_OK is always returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc clr_flg flgid, clrptn > flgid clrptn [-] [-] The ID No. of the eventflag to be cleared The bit pattern to be cleared > Register name R0 R1 R2 A0 Contents after system call issuance Error code -The bit pattern to be cleared The ID No. of the eventflag to be cleared [( Error codes )] E_OK 00000H 00000H(-H'0000): Normal End [( Function description )] Among the 16-bit eventflags indicated by flgid, this system call clears the bit whose corresponding clrptn is zero. Namely, it logical AND's the value of the eventflags indicated by flgid with the value of clrptn. If all bits in clrptn are set to 1, no operation will be performed on the eventflag concerned; but this does not result in an error. This system call can be issued from both tasks and handlers. 2.3.3 clr_flg(Clear Eventflag) 55 [( Usage example )] If the eventflag pattern issuing this system call was 0xff, the pattern after this system call becomes 0xf0. > #include #include "id.h" void task(void) { : clr_flg( ID_flg, (UINT)0xfff0 ); : } > .INCLUDE mr30.inc .GLB task task: : clr_flg #ID_flg,#0fff0H : 56 2.3.3 clr_flg(Clear Eventflag) 2.3.4. wai_flg(Wait Eventflag) [( System call name )] wai_flg Waits for an eventflag. [( Calling by the C language )] #include ER wai_flg (p_flgptn, flgid, waiptn, wfmode); > UINT *p_flgptn; ID UINT UINT flgid; waiptn; wfmode; Start address of area to which bit pattern is returned when wait state is cleared (Locate the p_flgptn area between 0 and FFFFH.) The ID No. of the eventflag to waited for The bit pattern to be waited for Wait mode > An error code is returned as the return value of a function. The bit pattern when the wait cleared to the area specified by p_flgptn. [( Calling by the assembly language )] .include mr30.inc wai_flg flgid, waiptn, wfmode > flgid waiptn wfmode [-] [-] [-] The ID No. of the eventflag to waited for The bit pattern to be waited for Wait mode > Register name R0 R1 R2 A0 Contents after system call issuance Error code Wait mode The bit pattern when wait state is cleared The ID No. of the eventflag to waited for [( Error codes )] E_OK E_RLWAI 00000H 00000H(-H'0000): 0FFAAH(-H'0056): 2.3.4 wai_flg(Wait Eventflag) Normal End Wait state forcibly cleared 57 [( Function description )] In eventflags indicated by flgid, this system call waits until the bit specified by waiptn is set according to wait clear conditions indicated by wfmode. Specify the wait bit pattern in waiptn. Note that you cannot specify 0 (zero) in waiptn. If you specify 0, this system call does not perform any processing and no value is returned. However, in the µITRON specifications, error E_PAR is returned, and compatibility with other realtime OS would therefore be compromised. Following specifications are made with wfmode: wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR] TWF_ANDW AND wait TWF_ORW OR wait TWF_CLR Clear specification Namely, these specifications have the following effects: wfmode(wait mode) TWF_ANDW TWF_ANDW+TWF_CLR Effects Waits until all bits specified by waiptn are set. (AND wait) Clears the eventflag all bits to 0 when AND wait clear conditions are met for the bit specified by waiptn and the task is freed from a wait state. TWF_ORW Waits until any bit specified by waiptn is set. (OR wait) TWF_ORW+TWF_CLR Clears the eventflag all bits to 0 when OR wait clear conditions are met for the bit specified by waiptn and the task is freed from a wait state. flgptn is a return parameter that indicates the eventflag value before a wait state is cleared by this system call (in the case of a clear specification, the value of the eventflag before it is cleared). The value returned by flgptn is a value that satisfies wait clear conditions. Multiple tasks can be kept waiting for the same eventflag. In this case, the multiple tasks can be simultaneously freed from a wait state by one issuance of a set_flg system call. However, if it was a task whose wait clear conditions are met in a waiting queue that requested a clear specification, all tasks up to that task are freed from the wait state. The eventflag forms the queue of the tasks which perform the following operations: The order of queuing is FIFO (First In, First Out). If the queue has the task having clear specification, the flag is cleared when that task is cleared of the wait. Whether the tasks that follow the task having clear specification are cleared of wait or not depends on the eventflag already cleared. So, these tasks are not cleared of wait. If the wait state is forcibly cleared by the rel_wai or irel_wai system call issued by another task, error code E_RLWAI is returned. The return parameter value(*p_flgptn) is indeterminate in all cases other than E_OK. This system call can be issued only from tasks. 58 2.3.4 wai_flg(Wait Eventflag) [( Usage example )] In this example, the system call waits until the bit specified by an eventflag whose flag name is flg2 is set. The task for which the specified bit is set is freed from a wait state. Since the wait mode specified here is a clear specification, the eventflag flg2 is cleared to 0 simultaneously when the task is freed from a wait state. > #include #include "id.h" void task() { UINT flgptn; : ) error("Wait Released\n"); > .INCLUDE mr30.inc .GLB task task: : wai_flg #ID_flg2,#0ff0H,(TWF_ANDW+TWF_CLR) : 2.3.4 wai_flg(Wait Eventflag) 59 2.3.5. twai_flg(Wait Eventflag with Timeout) [( System call name )] twai_flg Waits for an eventflag. (With Timeout) [( Calling by the C language )] #include ER twai_flg (p_flgptn, flgid, waiptn, wfmode, tmout); > UINT *p_flptn; ID UINT UINT TMO flgid; waiptn; wfmode; tmout; Start address of area to which bit pattern is returned when wait state is cleared (Locate the p_flgptn area between 0 and FFFFH.) The ID No. of the eventflag to be waited for The bit pattern to be waited for Wait mode Timeout value > An error code is returned as the return value of a function. The bit pattern when the wait cleared to the area specified by p_flgptn. [( Calling by the assembly language )] .include mr30.inc twai_flg flgid, waiptn, wfmode, tmout > flgid waiptn wfmode tmout [-] [-] [-] [-] The ID No. of the eventflag to be waited for The bit pattern to be waited for Wait mode Timeout value > Register name Contents after system call issuance R0 R1 R2 R3 A0 Error code Wait mode The bit pattern when wait state is cleared Timeout value The ID No. of the eventflag to be waited for [( Error codes )] E_OK E_RLWAI E_TMOUT 00000H 00000H(-H'0000): 0FFAAH(-H'0056): 0FFABH(-H'0055): Normal End Wait state forcibly cleared Polling failed or timeout [( Function description )] In eventflags indicated by flgid, this system call waits until the bit specified by waiptn is set according to wait clear condition indicated by wfmode. The task that invoked this system call is queued in two wait queues: the eventflag wait queue and timeout wait queue. When this system call is invoked, the wait state is cancelled in the cases shown below. When the wait state is cancelled, the task that invoked this system call exits from the two wait queues (eventflag wait queue and timeout wait queue) and is connected to the ready queue. When the wait cancellation condition occurs before the tmout time has elapsed. Error code E_OK is returned. 60 2.3.5 twai_flg(Wait Eventflag with Timeout) When the tmout time elapses without the wait cancellation condition being satisfied Error code E_TMOUT is returned. When the wait state is forcibly cancelled by rel_wai or irel_wai system caLls being invoked from another task or handler. Error code E_RLWAI is returned. You can specify a timeout (tmout) of -1 to 0x7FFF. Specifying TMO_FEVR = -1 to twai_flg for tmout indicates that an infinite timeout value be used, resulting in exactly the same processing as wai_flg. If you specify tmout as TMO_POL(=0), it works like pol_flg. See wai_flg system call for details of wfmode. The return parameter value(*p_flgptn) is indeterminate in all cases other than E_OK. This system call can be issued only from tasks. It cannot be issued from the interrupt handler, the cyclic handler, or the alarm handler. [( Usage example )] In this example, that task waits for the bit specified in the flg2 eventflag to be set or wait time tmout to elapse. The wait state is cancelled when the specified bit is set or the wait time has elapsed. > #include #include "id.h" void task() { UINT flgptn; : if( twai_flg(&flgptn, ID_flg2,(UINT)0x0ff0, TWF_ANDW, 5) != E_OK ) error("Wait Released\n"); : } > .INCLUDE mr30.inc .GLB task task: : twai_flg #ID_flg2,#0ff0H,#(TWF_ANDW+TWF_CLR),#5 : 2.3.5 twai_flg(Wait Eventflag with Timeout) 61 2.3.6. pol_flg(Poll Eventflag) [( System call name )] pol_flg Gets an eventflag . (no wait state). [( Calling by the C language )] #include ER pol_flg (p_flgptn, flgid, waiptn, wfmode); > UINT *p_flgptn; ID UINT UINT flgid; waiptn; wfmode; Start address of area to which bit pattern is returned when wait state is cleared (Locate the p_flgptn area between 0 and FFFFH.) The ID No. of the eventflag to check Wait bit pattern Wait mode > Error code is returned as a return value for a numeral. The bit pattern when a wait state is cleared is set in an area indicated by p_flgptn. [( Calling by the assembly language )] .include mr30.inc pol_flg flgid, waiptn, wfmode > flgid waiptn wfmode [-] [-] [-] The ID No. of the eventflag to check Wait bit pattern Wait mode > Register name Contents after system call issuance R0 R1 R2 A0 Error code Wait mode The bit pattern when wait state is cleared The ID No. of the eventflag to check [( Error codes )] E_OK E_TMOUT 00000H 00000H(-H'0000): 0FFABH(-H'0055): Normal End Polling failed or timeout [( Function description )] In eventflags indicated by flgid, this system call checks to see if the wait clear bit pattern indicated by waiptn is set according to wfmode. If the eventflag concerned already satisfies the wait clear conditions indicated by wfmode, the system call performs the same processing as in wai_flg (by clearing the eventflag if a clear specification is requested) and terminates the session normally. If the eventflag concerned does not satisfy the wait clear conditions indicated by wfmode, the system call returns an error E_TMOUT. In this case, the task is not placed in a wait state. Nor is the eventflag cleared even if a clear specification is requested. The return parameter value(*p_flgptn) is indeterminate in all cases other than E_OK. This system call can be issued from both tasks and handlers. 62 2.3.6 pol_flg(Poll Eventflag) [( Usage example )] In this example, the system call examines whether the bit specified by an eventflag whose flag name is flg2 is set. Since a clear specification is requested, the eventflag is cleared to 0 if conditions are met. > #include #include "id.h" void task() { UINT flgptn; : ) printf("Not set EventFlag\n"); : } > .INCLUDE mr30.inc .GLB task task: pol_flg #ID_flg2,#0ff0H,#(TWF_ORW+TWF_CLR) : 2.3.6 pol_flg(Poll Eventflag) 63 2.3.7. ref_flg(Refer Eventflag Status) [( System call name )] ref_flg Reference Eventflag Status. [( Calling by the C language )] #include ER ref_flg (pk_rflg, flgid); > T_RFLG *pk_rflg; ID flgid; Packet address to Reference Eventflag. (Locate the pk_rflg area between 0 and FFFFH) The ID No. of the eventflag to Reference Eventflag > An error code is returned as the return value of a function. The structure indicated by pk_rflg returns the following data. typedef struct t_rflg { VP exinf; /* Extended information */ BOOL_ID wtsk; /* Waiting task information */ UINT flgptn; /* Bit pattern of Eventflag */ } T_RFLG; [( Calling by the assembly language )] .include mr30.inc ref_flg flgid, pk_rflg > flgid [-] pk_rflg [-] The ID No. of the eventflag to Reference Eventflag Packet address to Reference Eventflag > Register name R0 R1 R2 A0 A1 Contents after system call issuance Error code -The ID No. of the eventflag to Reference Eventflag Packet address to Reference Eventflag The area indicated by pk_rflg returns the following information. offset +0 exinf Extended information wtsk Waiting task information +4 flgptn Bit pattern of Eventflag +6 [( Error codes )] E_OK 64 00000H 00000H(-H'0000): Normal End 2.3.7 ref_flg(Refer Eventflag Status) [( Function description )] Refers to the state of the eventflag specified by flgid, and returns returns the following information as return values. exinf Returns extended task information in exinf wtskid wtsk returns the ID No. of the first task (the first task to enter the wait state) in the wait queue. wtsk returns FALSE(0) if there are no tasks waiting in the queue. flgptn flgptn returns the current value of the eventflag. This system call can be issued from both tasks and handlers. [( Usage example )] > #include #include "id.h" void task() { T_RFLG rflg; ref_flg(&rflg, ID_flg ); : } > rflg: .blkb .INCLUDE .GLB task: : ref_flg : 8 mr30.inc task #ID_flg, #rflg 2.3.7 ref_flg(Refer Eventflag Status) 65 2.4. Semaphore 2.4.1. sig_sem(Signal Semaphore) [( System call name )] sig_sem Returns resource to the semaphore [( Calling by the C language )] #include ER sig_sem (semid); > ID semid; The ID No. of the semaphore > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc sig_sem semid > semid [-] The ID No. of the semaphore > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the semaphore [( Error codes )] E_OK E_QOVR 00000H 00000H(-H'0000): 0FFB7H(-H'0049): Normal End Queuing or nest overflow [( Function description )] This system call returns 1 resource to the semaphore specified by semid. When tasks are linked to the queue of that semaphore, the task at the head of the queue is put in the ready state. If no task is linked, the count of that semaphore is incremented by 1.23 The maximum count value of a semaphore is 0x7FFF(32767). If it returns resource (sig_sem or isig_sem system call) is executed beyond 0x7FFF(32767), error code E_QOVR is returned to the task which issued the system call with the semaphore count value left unchanged, namely 0x7FFF(32767). This system call can be issued only from tasks. The system call which be issued from the interrupt handler, the cyclic handler, or the alarm handler is the isig_sem. 23 If this system call causes the count value to exceeds the semaphore initial value defined in the configuration file, no error will occur. 66 2.4.1 sig_sem(Signal Semaphore) [( Usage example )] > #include #include "id.h" void task() { : if( sig_sem( ID_sem ) != E_OK ) error("Overflow\n"); : } > .INCLUDE .GLB task: sig_sem : mr30.inc task #ID_sem 2.4.1 sig_sem(Signal Semaphore) 67 2.4.2. isig_sem(Signal Semaphore) [( System call name )] isig_sem Returns resource to the semaphore (For the handler only) [( Calling by the C language )] #include ER isig_sem (semid); > ID semid; The ID No. of the semaphore > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc isig_sem semid > semid [-] The ID No. of the semaphore > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the semaphore [( Error codes )] E_OK E_QOVR 00000H 00000H(-H'0000): 0FFB7H(-H'0049): Normal End Queuing or nest overflow [( Function description )] This system call is issued from the interrupt handler, the cyclic handler, or the alarm handler to provide the same functions as the sig_sem system call. 68 2.4.2 isig_sem(Signal Semaphore) [( Usage example )] > #include #include "id.h" void inthand() { : if( isig_sem( ID_sem ) != E_OK ) error("Overflow\n"); : } > .INCLUDE .GLB intr: isig_sem : ret_int mr30.inc intr #ID_sem 2.4.2 isig_sem(Signal Semaphore) 69 2.4.3. wai_sem(Wait on Semaphore) [( System call name )] wai_sem Obtains one resource from the semaphore. [( Calling by the C language )] #include ER wai_sem (semid); > ID semid; The ID No. of the semaphore from which the resource is obtained > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc wai_sem semid > semid [-] The ID No. of the semaphore from which the resource is obtained > Register name Contents after system call issuance R0 R1 R2 A0 Error code -The ID No. of the semaphore from which the resource is obtained [( Error codes )] E_OK E_RLWAI 00000H 00000H(-H'0000): 0FFAAH(-H'0056): Normal End Wait state forcibly cleared [( Function description )] This system call obtains 1 resource from the semaphore specified by semid. If the count value of that semaphore is one or more, the count is decremented by 1 and the task which issued the system call continues executing. Conversely, if the semaphore count value is 0, the count value is not modified and the system call issued task is linked to the semaphore queue in order of FIFO.24 If the wait state has been cleared by the rel_wai or irel_wai system call issued by another task, error code E_RLWAI is returned. This system call can be issued only from tasks. It cannot be issued from the interrupt handler, the cyclic handler, or the alarm handler. 24 First-in, first-out. Namely, tasks are freed from a wait state by sig_sem or isig_sem system calls in the order they were placed in a wait state by the wai_sem system call. 70 2.4.3 wai_sem(Wait on Semaphore) [( Usage example )] > #include #include "id.h" void task() { : if( wai_sem( ID_sem ) != E_OK ) printf("Forced wakeup\n"); : } > .INCLUDE .GLB task: wai_sem : mr30.inc task #ID_sem 2.4.3 wai_sem(Wait on Semaphore) 71 2.4.4. twai_sem(Wait on Semaphore with Timeout) [( System call name )] twai_sem Obtains one resource from the semaphore. Timeout) (With [( Calling by the C language )] #include ER twai_sem (semid,tmout); > ID semid; TMO tmout; The ID No. of the semaphore from which the resource Timeout value > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30.inc twai_sem semid, tmout > semid [-] tmout [-] The ID No. of the semaphore from which the resource Timeout value > Register name Contents after system call issuance R0 R1 R2 R3 A0 Error code -Timeout value The ID No. of the semaphore from which the resource [( Error codes )] E_OK E_TMOUT E_RLWAI 00000H 00000H(-H'0000): 0FFABH(-H'0055): 0FFAAH(-H'0056): Normal End Polling failed or timeout Wait state forcibly cleared [( Function description )] This system call obtains 1 resource from the semaphore specified by semid. If the count value of that semaphore is one or more, the count is decremented by 1 and the task which issued the system call continues executing. Conversely, if the semaphore count value is 0, the count value is not modified and the system call issued task is linked to the semaphore queue and timeout wait queue. When this system call is invoked, the wait state is cancelled in the cases shown below. When the wait state is cancelled, the task that invoked this system call exits from the two wait queues (semaphore queue and timeout wait queue) and is connected to the ready queue. When the wait cancellation condition occurs by sig_sem or isig_sem system call being invoked before the tmout time has elapsed. Error code E_OK is returned. 72 2.4.4 twai_sem(Wait on Semaphore with Timeout) When the tmout time elapses without the wait cancellation condition being satisfied Error code E_TMOUT is returned. When the wait state is forcibly cancelled by rel_wai or irel_wai system calls being invoked from another task or handler. Error code E_RLWAI is returned. You can specify a timeout (tmout) of -1 to 0x7FFF. Specifying TMO_FEVR = -1 to twai_sem for tmout indicates that an infinite timeout value be used, resulting in exactly the same processing as wai_sem. If you specify tmout as TMO_POL(=0), it works like preq_sem. This system call can be issued only from tasks. It cannot be issued from the in terrupt handler, the cyclic handler, or the alarm handler. [( Usage example )] > #include #include "id.h" void task() { : if( twai_sem( ID_sem, 10 ) != E_OK ) printf("Forced wakeup\n"); : } > .INCLUDE .GLB task: : twai_sem : mr30.inc task #ID_sem,#10 2.4.4 twai_sem(Wait on Semaphore with Timeout) 73 2.4.5. preq_sem(Poll and Request Semaphore) [( System call name )] preq_sem Obtains one resource from the semaphore. (no wait) [( Calling by the C language )] #include ER preq_sem (semid); > ID semid; The ID No. of the semaphore from which the resource is obtained > An error code is returned as the return value of a function. [( Calling by the assembly language )] .include mr30