µitron 2.01 specifications compliant softune realos… · use this manual as a reference when...

FUJITSU SEMICONDUCTORCONTROLLER MANUAL CM42-00324-2E

F2MC-16L/16LX/16/16H/16FµITRON 2.01 SPECIFICATIONS COMPLIANT

SOFTUNE REALOS/907KERNEL MANUAL

FUJITSU LIMITED

F2MC-16L/16LX/16/16H/16FµITRON 2.01 SPECIFICATIONS COMPLIANT

SOFTUNE REALOS/907KERNEL MANUAL

i

PREFACE

� Purpose of This Manual

Thank you for purchasing Softune REALOS/907.

Softune REALOS/907 is a real-time operating system that runs on Fujitsu's F2MC-16L/16LX/16/16H/16F 16-bit microprocessors. The specifications of the Softune REALOS/907 kernel conform with the µITRON 2.01 specifications. Because Softune REALOS/907 supports both 1-word eventflag functions and 1-bit eventflag functions, either type of eventflag function can be selected. In order to clearly indicate bit lengths, the following terminology is used in this manual:

µITRON 2.01 Specifications Softune REALOS/907 Manual

1-word eventflag → 16-bit eventflag

1-bit eventflag → 1-bit eventflag

This manual describes the functions provided by Softune REALOS/907 and how to use them.

Use this manual as a reference when creating application systems and user programs.

Note that Softune REALOS/907 is sometimes referred to as REALOS 907 in this manual.

Essential information for the creation of Softune REALOS/907 systems is provided in the "Softune REALOS Configurator Manual." Use this Kernel Manual in conjunction with the Configurator Manual when creating Softune REALOS/907 systems.

• "TRON" is an abbreviation for "The Real-time Operating system Nucleus."

• "ITRON" is an abbreviation for "Industrial TRON."

• "µITRON" is an abbreviation for "Micro Industrial TRON."

� Trademarks

SOFTUNE is a trademark of FUJITSU LIMITED.

REALOS (REALtime Operating System) is a trademark of FUJITSU LIMITED.

The names of products and systems appearing in this manual are trademarks or registered trademarks of their respective companies.

ii

� Target Audience of This Manual

This manual is written as a reference covering Softune REALOS/907 modules and system calls, and is intended for engineers who are actually using Softune REALOS/907 to develop products.

� Organization of This Manual

This manual consists of four chapters and an appendix, as listed below.

Chapter 1 Notes on UseThis chapter contains notes concerning the development of application systems based onSoftune REALOS/907.

Chapter 2 ModulesThis chapter describes the function and operation of each module, and provides examples forprogram creation.

Chapter 3 Creating Application ProgramsThis chapter explains how to create application programs for Softune REALOS/907.

Chapter 4 System CallsThis chapter describes Softune REALOS/907 system calls in a reference format.

AppendixThe Appendix includes lists of system calls, error codes, function codes, C interface datatypes, and C interface parameters, as well as the C compiler expanded specifications.

iii

2002 FUJITSU LIMITED Printed in Japan

• The contents of this document are subject to change without notice. Customers are advised to consultwith FUJITSU sales representatives before ordering.

• The information and circuit diagrams in this document are presented as examples of semiconductordevice applications, and are not intended to be incorporated in devices for actual use. Also, FUJITSU isunable to assume responsibility for infringement of any patent rights or other rights of third partiesarising from the use of this information or circuit diagrams.

• The products described in this document are designed, developed and manufactured as contemplatedfor general use, including without limitation, ordinary industrial use, general office use, personal use, andhousehold use, but are not designed, developed and manufactured as contemplated (1) for useaccompanying fatal risks or dangers that, unless extremely high safety is secured, could have a seriouseffect to the public, and could lead directly to death, personal injury, severe physical damage or otherloss (i.e., nuclear reaction control in nuclear facility, aircraft flight control, air traffic control, masstransport control, medical life support system, missile launch control in weapon system), or (2) for userequiring extremely high reliability (i.e., submersible repeater and artificial satellite). Please note that Fujitsu will not be liable against you and/or any third party for any claims or damagesarising in connection with above-mentioned uses of the products.

• Any semiconductor devices have an inherent chance of failure. You must protect against injury, damageor loss from such failures by incorporating safety design measures into your facility and equipment suchas redundancy, fire protection, and prevention of over-current levels and other abnormal operatingconditions.

• If any products described in this document represent goods or technologies subject to certainrestrictions on export under the Foreign Exchange and Foreign Trade Law of Japan, the priorauthorization by Japanese government will be required for export of those products from Japan.

iv

Softune REALOS/907 MANUAL SET

The REALOS/907 manual set consists of four volumes listed below. A first-time user of REALOS/907 should first read the F2MC-16L/16LX/16/16H/16F User's Guide.

F2MC-16l/16LX/16/16H/16F Softune REALOS/907User's Guide

This manual contains the following items: application system creation procedure and precautionary information on system use.

F2MC-16l/16LX/16/16H/16F Softune REALOS/907Kernel Manual

FR/F2MC Family Softune REALOS/FR/907/896Configurator Manual

This manual contains information required to create user programs.

This manual explains the REALOS Configurator functions and how to use them.

FR-V/FR/F2MC Family Softune REALOSAnalyzer Manual

This manual explains the REALOS Analyzer functions and how to use them.Softune REALOS/896 is not supported.

v

READING THIS MANUAL

� Product Name

In this manual and this product, product name is designated as follows:

SOFTUNE is designated as Softune.

� Format for Representing Parameters

Parameters for which multiple values can be specified are shown using the following format:

• (x || y || z): Select one of either "x", "y", or "z".

• (x | y), (x or y): Specify "x" and "y" simultaneously.(When specified simultaneously, the logical sum of "x" and "y" is taken.)

• [x]: "x" may be specified, or may be omitted.

Note: These restrictions apply to "cyhact" and "wfmode".

� Meanings of Symbols

Note: Indicates information that requires special attention. Be sure to read such notes.

vii

CONTENTS

CHAPTER 1 Notes on Use..................................................................................................11.1 Notes on Programming............................................................................................................................21.2 Notes on Using the Debugger Macro ......................................................................................................41.3 Notes on Hardware..................................................................................................................................5

CHAPTER 2 Modules ..........................................................................................................72.1 Fields of Application for Softune REALOS/907 .......................................................................................82.2 Organization of Softune REALOS/907 ....................................................................................................92.3 Softune REALOS/907 Functions ...........................................................................................................102.4 Application Programs.............................................................................................................................12

2.4.1 Task Processing ...............................................................................................................................142.4.2 Task Scheduling and Execution Sequence ......................................................................................162.4.3 Task Dispatching ..............................................................................................................................172.4.4 Task Management Information.........................................................................................................182.4.5 Task States.......................................................................................................................................202.4.6 Processing by the Initialization Handler............................................................................................222.4.7 Processing by the Interrupt Handler .................................................................................................232.4.8 Processing by the Timer Handler .....................................................................................................242.4.9 Processing by the Exception Handler...............................................................................................25

2.5 Task Management Functions ................................................................................................................262.5.1 Task Creation ...................................................................................................................................282.5.2 Task Starting and Termination .........................................................................................................322.5.3 Changing Task Priority Levels..........................................................................................................342.5.4 Task Ready Queue Rotation ............................................................................................................352.5.5 Task Status Referencing ..................................................................................................................36

2.6 Task-Dependent Synchronization Functions.........................................................................................382.6.1 Placing Tasks into the WAIT State and Waking Up those Tasks .....................................................402.6.2 Placing Tasks into the SUSPEND State and Resuming those Tasks ..............................................42

2.7 Synchronization and Communication Functions....................................................................................442.7.1 Creation of Synchronization/Communication Objects ......................................................................462.7.2 Resource Management Using Semaphores.....................................................................................482.7.3 Event Notification Using Eventflags..................................................................................................502.7.4 Communications Using Mailboxes ...................................................................................................542.7.5 Referencing the Status of Synchronization/Communication Objects ...............................................56

2.8 MemoryPool Management Functions....................................................................................................582.8.1 MemoryPool Creation.......................................................................................................................602.8.2 Getting and Releasing Memory Blocks ............................................................................................622.8.3 Referencing the MemoryPool Status................................................................................................64

2.9 Interrupt Management Functions...........................................................................................................662.9.1 Interrupt Handler Definition...............................................................................................................682.9.2 Interrupt Processing Execution Control ............................................................................................69

2.10 Time Management Functions ................................................................................................................702.10.1 Setting and Reading the System Clock ............................................................................................742.10.2 Time-out Processing.........................................................................................................................75

viii

2.10.3 Definition of Cyclic Handlers............................................................................................................ 762.10.4 Cyclic Handler Control ..................................................................................................................... 782.10.5 Referencing the Status of a Cyclic Handler ..................................................................................... 792.10.6 Definition of Alarm Handlers ............................................................................................................ 802.10.7 Referencing the Status of an Alarm Handler ................................................................................... 81

2.11 System Management Function (Getting the Version Number) ............................................................. 822.12 Exception Management Functions........................................................................................................ 83

2.12.1 Exception Handler Processing......................................................................................................... 842.12.2 Exception Handler Definition ........................................................................................................... 86

CHAPTER 3 Creating Application Programs ................................................................. 873.1 Program Types ..................................................................................................................................... 883.2 Issuing System Calls............................................................................................................................. 90

3.2.1 Issuing System Calls in C ................................................................................................................ 923.2.2 Issuing System Calls in Assembly Language .................................................................................. 94

3.3 Task Creation........................................................................................................................................ 953.3.1 Describing a Task Program in C...................................................................................................... 963.3.2 Describing a Task Program in Assembly Language........................................................................ 98

3.4 Initialization Handler Creation............................................................................................................. 1003.4.1 Describing the Initialization Handler Program in C ........................................................................ 1013.4.2 Describing the Initialization Handler Program in Assembly Language .......................................... 102

3.5 Interrupt Handler Creation .................................................................................................................. 1043.5.1 Describing the Interrupt Handler Program in C.............................................................................. 1053.5.2 Describing the Interrupt Handler Program in Assembly Language................................................ 106

3.6 Timer Handler Creation....................................................................................................................... 1083.6.1 Describing a Timer Handler Program in C..................................................................................... 1093.6.2 Describing a Timer Handler Program in Assembly Language....................................................... 110

3.7 Exception Handler Creation................................................................................................................ 1123.7.1 Describing an Exception Handler Program in C ............................................................................ 1143.7.2 Describing an Exception Handler Program in Assembly Language .............................................. 116

3.8 System Clock Handler ........................................................................................................................ 1203.9 System Clock Handler Interface ......................................................................................................... 122

CHAPTER 4 System Calls.............................................................................................. 1254.1 List of System Calls ............................................................................................................................ 1264.2 System Call Descriptions.................................................................................................................... 128

4.2.1 Parameters .................................................................................................................................... 1304.2.2 Parameters that Require Caution .................................................................................................. 1324.2.3 Time-out Specification Restrictions ............................................................................................... 134

4.3 Task Management Function System Calls ......................................................................................... 1354.3.1 sta_tsk (Start Task)........................................................................................................................ 1364.3.2 ext_tsk (Exit Task) ......................................................................................................................... 1384.3.3 ter_tsk (Terminate Task)................................................................................................................ 1404.3.4 chg_pri (Change Task Priority) ...................................................................................................... 1424.3.5 rot_rdq (Rotate Ready Queue) ...................................................................................................... 1444.3.6 get_tid (Get Task Identifier) ........................................................................................................... 1464.3.7 tsk_sts (Get Task Status) .............................................................................................................. 148

4.4 Task-Dependent Synchronization Function System Calls .................................................................. 150

ix

4.4.1 sus_tsk (Suspend Task) .................................................................................................................1524.4.2 rsm_tsk (Resume Task) .................................................................................................................1544.4.3 frsm_tsk (Force Resume Task) ......................................................................................................1564.4.4 slp_tsk (Sleep Task) .......................................................................................................................1584.4.5 wai_tsk (Wait for Wakeup Task).....................................................................................................1604.4.6 wup_tsk (Wakeup Task) .................................................................................................................1624.4.7 can_wup (Cancel Wakeup Task)....................................................................................................164

4.5 Synchronization/Communication Function System Calls ....................................................................1664.5.1 sig_sem (Signal Semaphore) .........................................................................................................1684.5.2 wai_sem (Wait on Semaphore) ......................................................................................................1704.5.3 preq_sem (Poll and Request Semaphore) .....................................................................................1724.5.4 sem_sts (Get Semaphore Status) ..................................................................................................1744.5.5 set_flg (Set Eventflag) ....................................................................................................................1764.5.6 clr_flg (Clear Eventflag) ..................................................................................................................1784.5.7 wai_flg (Wait Eventflag)/cwai_flg (Wait and Clear Eventflag).........................................................1804.5.8 pol_flg (Poll Eventflag)/cpol_flg (Poll and Clear Eventflag) ............................................................1824.5.9 flg_sts (Get Eventflag Status).........................................................................................................1844.5.10 set_flg (Set Eventflag) ....................................................................................................................1884.5.11 clr_flg (Clear Eventflag) ..................................................................................................................1904.5.12 wai_flg (Wait Eventflag)..................................................................................................................1924.5.13 pol_flg (Poll Eventflag)....................................................................................................................1964.5.14 flg_sts (Get Eventflag Status).........................................................................................................2004.5.15 snd_msg (Send Message to Mailbox) ............................................................................................2024.5.16 rcv_msg (Receive Message from Mailbox) ....................................................................................2064.5.17 prcv_msg (Poll and Receive Message from Mailbox) ....................................................................2084.5.18 mbx_sts (Get Mailbox Status) ........................................................................................................210

4.6 MemoryPool Management Function System Calls..............................................................................2144.6.1 get_blk (Get Memory Block) ...........................................................................................................2164.6.2 pget_blk (Poll and Get Memory Block) ...........................................................................................2204.6.3 rel_blk (Release Memory Block).....................................................................................................2224.6.4 mpl_sts (Get MemoryPool Status)..................................................................................................224

4.7 Interrupt Management Function System Calls.....................................................................................2274.7.1 ret_int (Return from Interrupt Handler) ...........................................................................................2284.7.2 ret_wup (Return and Wakeup Task)...............................................................................................2304.7.3 chg_ilv (Change Interrupt Level) ....................................................................................................2324.7.4 ilv_sts (Get Interrupt Level Status) .................................................................................................234

4.8 Time Management Function System Calls ..........................................................................................2364.8.1 set_tim (Set Time) ..........................................................................................................................2384.8.2 get_tim (Get Time)..........................................................................................................................2404.8.3 def_cyc (Define Cyclic Handler) .....................................................................................................2424.8.4 act_cyc (Active Cyclic Handler) ......................................................................................................2464.8.5 cyh_sts (Get Cyclic Handler Status)...............................................................................................2484.8.6 def_alm (Define Alarm Handler) .....................................................................................................2504.8.7 alh_sts (Get Alarm Handler Status)................................................................................................2544.8.8 ret_tmr (Return from Timer Handler) ..............................................................................................256

4.9 System Management Function System Call........................................................................................2584.9.1 get_ver (Get Version No.)...............................................................................................................260

x

APPENDIX ........................................................................................................................... 263Appendix A System Call List .................................................................................................................... 265

A.1 Assembler Interface....................................................................................................................... 266A.2 C Interface ..................................................................................................................................... 273

Appendix B Error Code List ..................................................................................................................... 277Appendix C Function Code List................................................................................................................ 278Appendix D C Language Interface Data Type List ................................................................................... 282Appendix E C Language Interface Parameter Name List ........................................................................ 287Appendix F C Compiler Extended Specifications .................................................................................... 288

INDEX.................................................................................................................................. 291

CHAPTER 1 Notes on Use

This chapter contains notes concerning the use of Softune REALOS/907.

1.1 Notes on Programming

1.2 Notes on Using the Debugger Macro

1.3 Notes on Hardware

1



This section provides notes concerning programming for Softune REALOS/907.

� Notes on Programming

Note:

• "ext_tsk" must not be issued from the task-independent section of a program.

If "ext_tsk" is issued from the task-independent section, an error is generated and an infinite loop develops when control returns to the task independent section.

• "ret_int" must not be issued from the task section of a program.

If "ret_int" is issued from the task section, it may not be possible to return to the original context.

• When terminating a task, issue "ext_tsk".

Tasks are not terminated by "ret_int" or by return instructions (such as "retp" or "ret" instructions in assembly language, or the "return" statement in C). If one of these return instructions is executed in a location where "ext_tsk" should have been issued, the program will cease to run normally.

• The following registers and areas in memory cannot be overwritten directly by a user program:

Dedicated registers (PS, SSB, SSP, USB, and USP), the memory register bank used by the kernel (addresses 190H to 19fH among the general-purpose registers), the delayed interrupt register, the interrupt control register, the interrupt vector table, and the OS control data area.

These registers and areas are controlled by the kernel.

• The user does not need to create the interrupt vector table and the OS initialization data as programs. The Configurator generates a program for these when the system is set up.

• System calls cannot be issued immediately after a reset before OS entry routine is initiated. After initialization of the OS is completed, the initialization handler is the first program that can issue system calls.

• The system calls that can be issued by the initialization handler are limited to those that can be issued from the task-independent section. In the initialization handler program, system calls must be specified so that they do not use the memory register bank that the kernel uses.

• In the message communications method used in the mailbox, messages are transmitted and received by passing pointers, so transmissions and receptions must correspond with one another on a one-to-one basis.

• In the message communications method used in the mailbox, a message that has been transmitted uses its message header area, so the header area of a message that has been sent may not be overwritten.

2


Notes:

• Memorypool return addresses do not undergo rigorous error checking. Therefore, when getting a memorypool, the address must be saved until it is returned. System operation is not guaranteed if the address used to get the memorypool differs from the address that was returned.

• Obtaining and returning memory blocks must be done on a one-to-one correspondence with a memorypool. If a memory block that has not been obtained is returned, memory control operations thereafter will not be correct.

• The following label names, symbol names that start with the following label names, etc., are reserved by the OS. These label names cannot be used in user programs.

"r97_", "_r97_" (used by programs)

"R97_", "_R97_" (used by programs)

"R_", "r_" (used by debugger macro)

• The system stack is used by the OS and by interrupt programs (handlers).

• Except when shared, a separate task stack must be established for each task.

• It is necessary to preserve the contents of each task stack area, except when the task is in the DORMANT state. A task’s stack area may not be manipulated or used by another task.

• After the OS is initialized, all tasks are in the DORMANT state. To put a task into the READY state, it is necessary to initiate the task (by issuing the system call "sta_tsk") in the initialization handler or the interrupt handler.

• Designations "scdef.h" and "scdef.inc" used in this manual signifies the following filenames. Specify the appropriate one to suit the system.

"scdef.h" : "scdef_b.h" (for 1-bit eventflag)

"scdef_w.h" (for 16-bit eventflag)

"scdef.inc" : "scdef_s.inc" (for F2MC-16L/16LX/16H common code)

"scdef_f.inc" (for F2MC-16F dedicated code)

3


1.2 Notes on Using the Debugger Macro

This section contains notes on using the debugger macro.

� Notes on Using the Debugger Macro

Notes:

• Use the debugger macro after kernel initialization has been completed.

• The debugger macro may not be used while the kernel is being executed (i.e., while the PC is pointing to an address within the kernel). Doing so may generate unexpected results.

• The debugger macro may not be used on-the-fly while the emulator debugger is being used. Doing so may generate unexpected results.

4


5


This section contains notes regarding hardware.

� Notes on Hardware

Notes:

• A 16-bit microcontroller (F2MC-16L/16LX/16/16H/16F) with a built-in delayed interrupt module and bit search module is required in order to run Softune REALOS/907.

• One interrupt is required in order to operate the system clock. An interval timer is normally used to generate interrupts at regular intervals. An interval timer built into the MCU may be used.

• The delayed interrupt module is used by the OS. User programs may not be registered in the delayed interrupt vector table.

• OS performance is improved if the system stack area and the kernel control data are located within high-speed memory.

• The EI²OS function cannot be used.


6

MEMO

CHAPTER 2 Modules

The Softune REALOS/907 program is built from a number of modules with the kernel atits core.This chapter explains the function and operation of each module, and provides examples for the creation of programs.

2.1 Fields of Application for Softune REALOS/907

2.2 Organization of Softune REALOS/907

2.3 Softune REALOS/907 Functions

2.4 Application Programs

2.5 Task Management Functions

2.6 Task-Dependent Synchronization Functions

2.7 Synchronization and Communication Functions

2.8 MemoryPool Management Functions

2.9 Interrupt Management Functions

2.10 Time Management Functions

2.11 System Management Function (Getting the Version Number)

2.12 Exception Management Functions

7

CHAPTER 2 Modules

2.1 Fields of Application for Softune REALOS/907

Softune REALOS/907 is a real-time OS that conforms with the µTRON 2.01 specifications and which is used to control equipment.The µITRON specifications are standard specifications for operating systems used to control industrial equipment. Furthermore, the µITRON 2.01 specifications have been prepared and expanded for high-performance microprocessors.Softune REALOS/907 is designed to respond rapidly in real-time to processing requests. Softune REALOS/907 is suited for industrial equipment control system applications in particular.

� Fields of Application for Softune REALOS/907

Fig. 2.1 shows some of the fields of application for Softune REALOS/907.

Figure 2.1 Fields of Application for Softune REALOS/907

REALOS/907

AutomotiveAudio visual Communications control

OA equipment

Camera

Car audio, front panel control

CRT

Mobile communicationsequipment

Switching equipment

Telephone

Photocopy

VTR

FAX

Television

8


9


The Softune REALOS/907 kernel is an event-driven multitasking OS. The kernel manages the basic functions of the Softune REALOS/907 real-time OS, and supports task management and handler processing execution. Note that subsequent references to "Softune REALOS/907" refer to the kernel itself, unless noted otherwise.

� Organization of the Softune REALOS/907 Modules

Fig. 2.2 shows the organization of the Softune REALOS/907 modules.

Figure 2.2 Organization of the Softune REALOS/907 Modules

Sampletask

program

Usertask

Usertask

I/O driverSample

I/Odriver

REALOS /907 kernelTM

:Modules provided by REALOS/907

:User programs, or modules provided separately

F MC-16L/16LX/16/16H/16FFamily SOFTUNE

2

Configurator

Usertask

Analyzer

CHAPTER 2 Modules


The kernel is the core of the application system, and manages and controls each module. The primary functions of the kernel include task management, control of synchronization and communications between tasks, and memorypool and time management.

� Softune REALOS/907 Functions

Fig. 2.3 shows the Softune REALOS/907 functions.

Figure 2.3 Softune REALOS/907 Functions

� Task Management Functions

These are the basic functions needed for implementing multitask processing.

In Softune REALOS/907, a priority-based, event-driven scheduling system is used for task management.

� Task-Dependent Synchronization Functions

These functions are used for simple synchronization between tasks.

� Synchronization/Communication Functions

These functions are used for communication and synchronization between tasks. Three types of functions are supported: semaphores, Eventflags, and mailboxes.

• Semaphores:These 8-bit counter semaphores are used for resource management, etc.

• Eventflags: This function controls tasks through the generation of events. 1-bit eventflags and 16-bit eventflags are supported.

• Mailboxes: These are used for the exchange of messages.

� MemoryPool Management Functions

These functions dynamically manage memory areas registered by the user.

Memory is divided into (and managed as) block units in a memorypool. Tasks can get and return memory blocks as needed during processing execution.

Task managementfunctions

Task-Dependentsynchronization functions

System managementfunctions

Synchronization/communication functionsSemaphores, eventflags, mailboxes

Memorypoolmanagement functions

Interrupt managementfunctions

Time managementfunctions

Exception managementfunctions

REALOS/907 Functions

10


� Interrupt Management Functions

These functions perform processing in response to interrupts generated by external devices.

This interrupt processing is essential in order to respond in real-time to processing requests from external devices.

� Time Management Functions

These functions implement time-synchronized processing.

These functions support handlers that run at a specified time interval, and alarm handlers that run at a specified time.

� System Management Functions

These functions manage the status of the OS, and provide functions such as version management.

� Exception Management Functions

These functions perform processing in response to abnormalities generated within the system.

Exception handlers can be defined for the system as a whole for the following types of exceptions:

• CPU exceptions

• System call exceptions

11

CHAPTER 2 Modules


Application programs are programs created by users. Programs can be written in C or in assembler. Details on writing application programs are provided in chapter 3. Examples of programs that execute normal processing include tasks, initialization handlers, interrupt handlers, and timer handlers; an example of a program that is executed when an abnormal situation arises is an exception handler.

� Overview of Application Programs

� Programs that execute normal processing

• Tasks

A task is the fundamental unit of which application programs are comprised. Processing in an application system is implemented through the coordinated operation of multiple tasks.

• Initialization handler

After the kernel is started up, the initialization handler is the first handler that is executed.

This handler initializes tasks and performs various initialization jobs.

• Interrupt handler

This processing is executed when an interrupt is generated. Interrupt requests from peripheral devices are received by the interrupt handler, which then requests processing by a task.

• Timer handlers

There are cyclic handlers that are executed cyclically and there are alarm handlers that are executed at a specified time. These handlers are executed as part of the system clock handler.

� Programs that are executed when an abnormality arises

• Exception handlers

This processing is executed if an exception is generated while task or handler processing is being executed.

Exception processing is executed when some sort of abnormality arises during execution of normal processing.

� Application Program Structure

Fig. 2.4 shows the structure of an application program.

Figure 2.4 Application Program Structure

Task A Task B Interrupthandler

System callexceptionhandler

CPUexceptionhandler

REALOS/907

Initializationhandler

12


� Program Processing Execution Attributes

For program processing under Softune REALOS/907, two execution attributes are set: the task section and the task-independent section. System calls that can be executed is determined by this execution attribute.

• Task processing

Task processing is executed according to the task section execution attribute.

• Initialization handler processing

Initialization handler processing is executed according to the task-independent section execution attribute.

• Interrupt handler processing

Interrupt handler processing is executed according to the task-independent section execution attribute.

• Timer handler processing

Timer handler processing is executed according to the task-independent section execution attribute.

• Exception handler processing

Exception handler processing is executed according to the execution attribute under which the exception was generated.

Table 2.4 shows the Softune REALOS/907 execution attributes.

Note: Because exception handler processing is executed with the execution attribute under which the exception was generated, the exception attribute is not predetermined.

Table 2.4 Softune REALOS/907 Execution Attributes

Execution attribute Corresponding programs Characteristics

Task section

• Tasks • Exception handlers

• Practically all system calls can be executed. • Dispatching occurs. • Exception handlers shared by the system are

executed.

Task-independent section

• Initialization handler • Interrupt handler• Cyclic handler• Alarm handler• Exception handler

• Are executed after kernel startup.• Processing is executed by external interrupts.• Do not have the task attributes. • Have a context independent of tasks. • Only system calls that can be issued from the task-

independent section can be executed. • Dispatching is delayed until the task-independent

section processing is completed. • Exception handlers shared by the system are

executed.

13

CHAPTER 2 Modules

2.4.1 Task Processing

In Softune REALOS/907, a single job is written as a task. Tasks are the smallest execution units of programs, and are the program units on which the scheduling process works. Because Softune REALOS/907 is a multitasking OS, multiple tasks are ranked by priority; CPU time is then allocated to the tasks on the basis of that priority. (This allocation of time is called "scheduling.")

� Tasks Operating under Softune REALOS/907

Figure 2.4.1a illustrates tasks operating under Softune REALOS/907.

Figure 2.4.1a Tasks Operating under Softune REALOS/907

REALOS/907

Task A

Data inputprocessing

Task D

Device monitoring

Task E

Abnormalityprocessing

Task B

Data calculation processing

Task C

Data output processing

14


� Task Execution

Fig. 2.4.1b illustrates task execution. This graph shows a case where task execution requests for tasks A and B and an external interrupt request (task D) are received while task C is being executed.

Figure 2.4.1b Task Execution

Priority levelHigh

Low

REALOS/907

Task A

Task B

Task C

Interrupt handler

Event

Time

Task Bexecutionrequest

Task Aexecutionrequest

Task Atermination

request

Task Btermination

request

External interruptrequest

15

CHAPTER 2 Modules

16

2.4.2 Task Scheduling and Execution Sequence

The tasks operating under Softune REALOS/907 are controlled by an event-driven scheduling system based on priority.Normally, the kernel determines the priority ranking on the basis of the task states and priority levels. Then the tasks that are in the READY state are executed in sequence, starting with the task that has the highest priority. If there are more than one task with the same priority level, the tasks are executed in the order in which they entered the READY state.

� Task Scheduling and Execution Sequence

The tasks operating under Softune REALOS/907 are controlled by an event-driven scheduling system based on priority.

Fig. 2.4.2 illustrates the task scheduling process and the execution sequence.

Figure 2.4.2 Task Scheduling and Execution Sequence

� Priority levels and priority ranking

In Softune REALOS/907, the priority ranking is determined on the basis of the task priority levels. The task execution sequence is dictated by the priority ranking. Execution authority is passed to the highest task in the priority ranking. In the priority ranking, the tasks with the higher priority levels are ranked higher; when more than one task has the same priority level, the tasks are executed in the order in which they became executable.

Priority level 1

Priority level 2

Priority level 3

Current executabletask

The first task that becameexecutable is executed.

Tasks are executed in the order of theirpriority levels. If multiple tasks share thesame priority level, they are executed on aFIFO basis.


2.4.3 Task Dispatching

When, as a result of task scheduling, a task with a higher priority ranking than the task currently being executed becomes executable, or if the task currently being executed is in the WAIT state, a different task enters the RUN state. The processing by which task execution switching is accomplished is called "dispatching."In Softune REALOS/907, task dispatching occurs in situations such as the following:

• When a system call that causes a state transition is generated• When an interrupt is generated (i.e., when a system call from the interrupt

handler is executed)

� Task Dispatching

Task dispatching is the processing by which the task context data of the task currently being executed is replaced with the task context data of the task to be executed next.

Fig. 2.4.3 illustrates the task dispatching process.

Figure 2.4.3 Task Dispatching

� Dispatch and Preempt

A task dispatch is called simply a dispatch when it is caused by the system call issued by the executing task which transforms its own state, while a task dispatch is called a preempt when it occurs during the time when the task is not in an explicit transition.

Task A

When the task currently being executed is placed into anotherstate, the second task in the priority ranking is executed.

Task BDispatch

SAVE

Task A stack Task B stack

LOAD

PCB

DTB

AL

PCPS

AH

----------

-----

17

CHAPTER 2 Modules

18

2.4.4 Task Management Information

The tasks operating under Softune REALOS/907 are managed through the Task Control Block (TCB).The TCB is a collection of data (information) within the kernel that is used to manage the tasks.

� Information Included in the TCB

The information included in the TCB is listed below.

� Information used to manage task execution

• Task timeout count∗

• WAIT bit pattern of the 16-bit eventflag∗

• Task priority levels

• Tasks states

• Number of execution requests in queue

• Number of nested SUSPEND requests

∗ : The timeout count and the WAIT bit pattern share the same area. Even if "wai_tsk" is not included, the area is allocated when the 16-bit eventflag is selected.

� Context storage area

• CPU register context

19

MEMO

CHAPTER 2 Modules

20

2.4.5 Task States

There are six states that tasks can be in under Softune REALOS/907: RUN, READY, WAIT, SUSPEND, WAIT-SUSPEND, and DORMANT. Table 2.4.5 describes the task states.

� Task States

Table 2.4.5 Task States

Task state Description

RUN state

This is the state of the task currently being executed. Among the tasks in the READY state, the task with the highest priority ranking enters the RUN state. There is only one task in the system at any one time in this state.

READY state Tasks in this state are waiting to be assigned execution authority by the kernel. Tasks in this state can begin processing at any time.

WAIT stateTasks in this state are waiting for the requirements for release of the WAIT state to be met. Once the requirements are met, the state is placed into the READY state.

SUSPEND state Tasks in this state were forcibly interrupted by another task.Tasks in this state are forcibly placed outside of the tasks subject to scheduling.

WAIT-SUSPEND stateTasks in this state have been put into both the WAIT state and the SUSPEND state. Specifically, a task enters this state when a SUSPEND request (via "sus_tsk") is made in regards to a task that is in the WAIT state.

DORMANT state A task in this state is waiting for starting task.This is the state that a task occupies before it is started and after it is terminated.


� Task State Transitions

Fig. 2.4.5 shows the task state transition diagram.

Figure 2.4.5 Task State Transition Diagram

RUN

WAIT

WAIT-SUSPEND

SUSPEND

DORMANT

READY

DispatchPreempt

Release Wait

Forced termination

Start

Suspend Resumed

Exit

Forced terminationSuspend

Resumed

Forced termination

Forced termination

21

CHAPTER 2 Modules

22

2.4.6 Processing by the Initialization Handler

In Softune REALOS/907, the initialization handler is the first user program that is executed after OS initialization.

� Initialization Handler Execution

The initialization handler performs initialization processing that is shared among tasks, starts tasks, etc. While the reset entry routine primarily handles hardware initialization processing, the initialization handler primarily handles initialization processing concerning applications. Before any other tasks are executed, the initialization handler is called by the kernel. The initialization handler is created by the user. The initialization handler entry name is specified by the Configurator. Fig. 2.4.6 illustrates the execution of the initialization handler.

Figure 2.4.6 Initialization Handler Execution

The initialization handler is executed under the namespecified in the configuration definition statement.

r97_entry

_r97_idle

Reset interrupt REALOS/907kernel

Reset entry routine(address registered for the reset vector)

jmp r97_entry

User-defined initialization handler(label specified by theConfigurator)

ret_int


2.4.7 Processing by the Interrupt Handler

In Softune REALOS/907, the interrupt management functions can be used to execute processing for interrupts from peripheral devices.

� Interrupt Handler Execution

For interrupt management, the processing executed in response to external interrupts generated by the F2MC-16L/16LX/16/16H/16F is defined as the interrupt handler. When a corresponding interrupt is generated, the F2MC-16L/16LX/16/16H/16F directly initiates the user-defined interrupt handler. In Softune REALOS/907 processing, the time during which interrupts are prohibited is kept to a minimum. As a result, unprecedentedly fast response to interrupt requests is possible in Softune REALOS/907.

If an interrupt is generated, the user-defined interrupt handler is executed. Fig. 2.4.7 illustrates the execution of the interrupt handler.

Figure 2.4.7 Interrupt Handler Execution

The program registered for the vector corresponding tothe interrupt is executed.

Task

Interruptgenerated

Interrupt

ret_int

User-definedinterrupt handler

REALOS/907

23

CHAPTER 2 Modules

24

2.4.8 Processing by the Timer Handler

In Softune REALOS/907, it is possible to define handlers, independent of tasks, that are executed either cyclically or at a specified time.The timer handler function permits definition of the following two types of handlers:

• Cyclic handlers • Alarm handlers

� Timer Handler Execution

Fig. 2.4.8 illustrates the execution of the timer handler.

Figure 2.4.8 Timer Handler Execution

The timer handler is executed as a subroutine by the systemclock handler used by the kernel.

Interrupt generatedby a hardware timer

ret_tmr

User-definedtimer handler

REALOS/907system clock handler

Calling thetimer handler


2.4.9 Processing by the Exception Handler

In Softune REALOS/907, it is possible to execute processing in response to exceptions that are generated during program execution.Exception management permits the definition of processing as exception handlers for the following two types of exceptions:

• CPU exceptions• System call exceptions

One exception handler can be defined in the system for each type of exception.

� Exception Handler Execution

Fig. 2.4.9 illustrates the execution of the exception handlers.

Figure 2.4.9 Exception Handler Execution

When the exception processingspecified by the CPU exception handlerterminates, control returns to thelocation where the exception wasgenerated.

CPUexceptiongenerated

retp

CPU exception handler

When the exception processingspecified by the system call exceptionhandler terminates, control returns tothe location where the exception wasgenerated.

Task Task

System callexceptiongenerated

System callexception handler

retp

25

CHAPTER 2 Modules


In Softune REALOS/907, functions for starting tasks, referencing task statuses, etc., are provided as the "task management functions."

� Task Management Function System Calls

The system calls for the task management functions are listed below.

� System calls for starting/terminating tasks

• sta_tsk: Starts a task.

• ext_tsk: Is used by a task to terminate itself.

• ter_tsk: Forcibly terminates another task.

� System calls for controlling task execution

• chg_pri: Changes the task priority level.

• rot_rdq: Rotates the task ready queue.

• get_tid: Is used by a task to get its own ID number.

• tsk_sts: References the task status.

� Task Management Transition

Fig. 2.5 illustrates task management transition.

Figure 2.5 Task Management Transition

Forced termination(ter_tsk)

RUN

DORMANT

READY

Dispatch

Preempt

Start (sta_tsk) Exit (ext_tsk)

Forced termination (ter_tsk)

26

27

MEMO

CHAPTER 2 Modules

28

2.5.1 Task Creation

Creating a task involves defining the tasks necessary for running a task.A task is created by specifying the task ID number and the task attributes.A task can be statically defined as corresponding to a specified ID number by the Configurator.For details on how to accomplish this, refer to "Softune REALOS Configurator Manual."

� Task Creation

Tasks are created throug the Configurator.

The following parameters need to be specified:

• Task ID number

• Task start address

• Priority level upon task start

• User stack size

• Register bank pointer register

• Data bank register

• Additional data bank register

• Direct page register

• Condition code register

� Task ID number

The task ID number is a two-byte number that is used to identify the task. A value from 1 to 255 can be specified. Negative values cannot be used. "0" is used by any task to specify itself.

� Task start address

Specifies the starting address for the program that is the task that is being created.

Range of ID numbers

0 1 Maximum value

“TSK_SELF” cannot be specified when a task is created, since it isused by any task to specify itself.


� Priority level upon task initiation

A value from 1 to 16 can be specified for the priority level. The smaller the value, the higher the priority. Negative values cannot be used.

"0" has special uses.

Tasks running under Softune REALOS/907 are scheduled on the basis of this priority level.

The priority level of a task can be changed while that task is being executed. The new value is discarded once the task terminates. The next time the task is initiated, it is executed according to the priority level upon initiation specified by this parameter.

� User stack size

This parameter specifies the size of the stack that is used.

The configurator uses this value to automatically allocate memory from system memory.

� Register bank pointer register (RP)

This parameter specifies the register (0 to 31). Do not specify bank 1 since the kernel uses this bank. If the register parameter is omitted, "0" is assumed.

� Data bank register (DTB)

This parameter specifies the data bank register. (0 to 0xFF) If the DTB parameter is omitted, "0" is assumed.

Specify the bank where the data to be accessed via a DTB access resides.

� Additional data register (ADB)

This parameter specifies the additional data register. (0 to 0xFF) If the ADB parameter is omitted, "0" is assumed.

Specify the bank where the data to be accessed via an ADB access resides.

� Direct page register (DPR)

This parameter specifies the direct page register. (0 to 0xFF) If the DPR parameter is omitted, "0" is assumed.

Specify the page where the data to be accessed via a DPR access resides.

TPRI_INI : : Specification of priority level upon task initiationTPRI_RUN : Specification of highest priority level currently being executed(“TPRI_INI” and “TPRI_RUN” cannot be specified when a task is being created.)

Priority levelHigh Low

Range of priority levels

0 1 Maximum value

29

CHAPTER 2 Modules

30

� Condition code register (CCR)

This parameter specifies the condition code register (0 to 0xFF) If the CCR parameter is omitted, "0X40" is assumed.

Specify the status of the flags when the task is initiated. Note that the I flag must be set and that the S flag must be cleared.

� State of Tasks Defined through the Configurator

The tasks are registered in Softune REALOS/907 in either the READY state or the DORMANT state. Tasks registered in the DORMANT state are in a state in which they can be initiated and processed at any time, but they will not run until they are initiated via "sta_tsk".

Information on the specified task attributes, the starting address, etc., can be referenced by "tsk_sts". Refer to section 2.5.5, "Task Status Referencing."

31

MEMO

CHAPTER 2 Modules

32

2.5.2 Task Starting and Termination

Other tasks are started by using "sta_tsk". It is possible to issue execution requests for tasks that have been created and are in the DORMANT state. Task processing is terminated by "ext_tsk" or by "ter_tsk". When task processing is terminated, it can be either because it terminated itself or because it was forcibly terminated for some reason. The system calls "ext_tsk" and "ter_tsk" do not release resources belonging to the task that is being terminated. The user is responsible for releasing resources prior to the termination of a task.

� Task Starting

Other tasks are started by using "sta_tsk".

It is possible to issue execution requests for tasks that have been created and are in the DORMANT state. Specify the following parameter:

• Task ID number (tskid)

� State of Started Tasks

Started tasks from the DORMANT state are placed into the READY state. The priority level in this case is the priority level upon starting that was specified when the task in question was created. Whether or not the started task is actually executed depends on the scheduling by the kernel. Table 2.5.2 shows task starting and execution, while Fig. 2.5.2 illustrates task starting.

Table 2.5.2 Task Starting and Execution

Figure 2.5.2 Task Starting

Task state transition Cause

Task starting DORMANT to READY Issuance of "sta_tsk"

Task execution READY to RUN Kernel scheduling

Task APrioritylevel 2

Priority level 1

Priority level 2

Priority level 3

Task currently being executed

Task A, started by sta_tsk

DORMANT

READY

When task A is actually executeddepends on scheduling by the kernel

sta_tsk

READY tasks


� Task Termination

A task terminates itself by using the call "ext_tsk"; as a result, the task state is placed into the DORMANT state.

� Forced Termination of Other Tasks

A task forcibly terminates other tasks by using the call "ter_tsk". This call places a task from the READY state, the WAIT state, or the SUSPEND state to the DORMANT state.

Specify the following parameter:


33

CHAPTER 2 Modules

34

2.5.3 Changing Task Priority Levels

Task priority levels can be changed by using the system call "chg_pri". When a priority level is changed, the change takes effect immediately. The new priority level remains valid until the task is terminated.

� Changing Task Priority Levels

Task priority levels can be changed by using the system call "chg_pri".

Specify the following parameters:


• Priority level (tskpri)

Fig. 2.5.3 illustrates how task priority levels are changed.

Figure 2.5.3 Changing Task Priority Levels

Priority level 2

Priority level 1 Task B

Task BPriority level 3

Because task B is in the READY state, the priorityranking changes due to the change in the priority levelof task B.

chg_pri : Changes the task B priority level from 3 to 1.


2.5.4 Task Ready Queue Rotation

The system call "rot_rdq" rotates the ready queue for the specified priority level (tskpri).When the task's own priority level is specified, the current task moves to the end of the ready queue and loses execution authority. In addition, by specifying TPRI_RUN from the task-independent section, it is possible to specify the highest priority level currently being executed.

� Task Ready Queue Rotation

The system call "rot_rdq" rotates the ready queue for the specified priority level.


• Priority level (tskpri)

Fig. 2.5.4 illustrates task ready queue rotation.

Figure 2.5.4 Task Ready Queue Rotation

Priority level 2

Task A

rot_rdq Rotates the priority level 2 readyqueue

Task A

35

CHAPTER 2 Modules

36

2.5.5 Task Status Referencing

The system call "tsk_sts" references task statuses.A task can get its own ID number by using the system call "get_tid".When executed from the task-independent section, a false "0" is returned.

� Task Status Referencing

The system call "tsk_sts" references task statuses.



• Starting address for the packet that returns the task status. (pk_tsks)

The task status can be confirmed by checking the Data (packet) returned by "tsk_sts".

Fig. 2.5.5 shows the structure of the packet that is returned carrying the task status.

Figure 2.5.5 Structure of the Packet Containing Task Status Information

� Getting a Task’s Own ID Number

A task can get its own ID number by using the system call "get_tid".

0

+1

+2

pk_tsks

Current priority level

Task statustskstat

tskpri

37

MEMO

CHAPTER 2 Modules


In Softune REALOS/907, the task-dependent synchronization functions are provided in order to permit simple synchronization between tasks.

There are two functions: one places a task into the WAIT state/resumes it, while the other places a task into the SUSPEND state/resumes it. Fig. 2.6 illustrates task-dependent synchronization task state transition.

� Task-Dependent Synchronization Function System Calls

The system calls for the task-dependent synchronization functions are listed below.

� System calls for placing a task into the WAIT state and resuming it

• slp_tsk: A task uses this system call to place itself into the WAIT state.

• wai_tsk: A task uses this system call to put itself into the WAIT state for a fixed period of time.

• wup_tsk: This system call wakes a task from the WAIT state.

• can_wup: This system call cancels a task wakeup request.

� System calls for placing a task into the SUSPEND state and resuming it

• sus_tsk: This system call places another task into the SUSPEND state.

• rsm_tsk: This system call resumes a task in the SUSPEND state.

• frsm_tsk: This system call forcibly resumes a task in the SUSPEND state.

38


� Task-Dependent Synchronization Task State Transition

Fig. 2.6 illustrates task-dependent synchronization task state transition.

Figure 2.6 Task-Dependent Synchronization Task State Transition

RUN

WAIT

WAIT-SUSPEND

SUSPEND

READY

Dispatch

PreemptWait(slp_tsk, wai_tsk)

Resume (rsm_tsk, frsm_tsk)

Suspend (sus_tsk)

Release (wup_tsk)

(sus_tsk)

Suspend (sus_tsk)

Resume (rsm_tsk, frsm_tsk)

Release(wup_tsk)

(sus_tsk)

39

CHAPTER 2 Modules

40

2.6.1 Placing Tasks into the WAIT State and Waking Up those Tasks

A task is placed into the WAIT state by "slp_tsk" and "wai_tsk". Tasks that are placed into the WAIT state by these system calls are released and woken up from the WAIT state by specifying the task (as the "tskid" parameter) in the system call "wup_tsk". If "wup_tsk" is issued for a task in a different state, the request is queued.A wakeup request queued for a specified task can be cancelled by "can_wup".

� Placing into the WAIT State

A task can place itself to the WAIT state by using the system call "slp_tsk".

A task can place itself to the WAIT state for a specified length of time (tmout) by using the system call "wai_tsk".


• Timeout specification (tmout)

Tasks that are placed to the WAIT state by these system calls are released from the WAIT state by the system call "wup_tsk".

When a task wakeup request is queued, the wakeup request count is decremented by "1"; the task does not enter the WAIT state.

In "wai_tsk", it is possible to specify the time for which the task is shifted to the WAIT state. Refer to section 2.10.2, "Timeout Processing."

� Waking Up Tasks from the WAIT State

The system call "wup_tsk" wakes up a specified task (tskid).



This wakeup request is valid for tasks that were placed into the WAIT state by "slp_tsk" or by "wai_tsk". If "wup_tsk" is issued for a task that is in any other state, the "wup_tsk" request is put in a queue. Fig. 2.6.1a illustrates a task being resumed by using "wup_tsk".

Figure 2.6.1a Waking Up a Task with "wup_tsk"

READY state


A task that was placed into the WAIT stateby “slp_tsk” or “wai_tsk” is placed backinto the READY state by “wup_tsk”.

wup_tskWAIT state


� Wakeup Request Queuing

If the system call "wup_tsk" is issued for a task that was not put into the WAIT state by "slp_tsk" or by "wai_tsk", the task wakeup request is put into a queue. The queued wakeup request becomes valid when the target task executes "slp_tsk" or "wai_tsk". Fig. 2.6.1b illustrates a wakeup request being put into a queue.

Figure 2.6.1b Wakeup Request Queuing

� Wakeup Request Cancellation

A queued wakeup request for the specified task (tskid) is cancelled by using the system call "can_wup".



The number of queued requests is returned as the return parameter. Fig. 2.6.1c illustrates the cancellation of a wakeup request.

Figure 2.6.1c Wakeup Request Cancellation

READY state


Wakeup request count : 0

wup_tsk

The wakeup request count increases by "1".


READY state



can_wup

All queued wakeup requests arecancelled. The number of queuedtasks is returned as a returnparameter to the task that issued"can_wup".Wakeup request count : 0

41

CHAPTER 2 Modules

42

2.6.2 Placing Tasks into the SUSPEND State and Resuming those Tasks

The system call "sus_tsk" can be used to place another specified task (tskid) into the SUSPEND state. Tasks in the SUSPEND state are resumed by using the system calls "rsm_tsk" or "frsm_tsk".

� Placing to the SUSPEND State

The system call "sus_tsk" can be used to place another specified task (tskid) into the SUSPEND state.



Tasks in the SUSPEND state are resumed by using the system calls "rsm_tsk" or "frsm_tsk". Fig. 2.6.2a illustrates a task being placing into the SUSPEND state, and Fig. 2.6.2b illustrates the nesting of SUSPEND requests.

Note the following points:

• The system call "sus_tsk" can be issued for any task, except for one in that has not yet been started (i.e., a task in the DORMANT state).

• SUSPEND requests are nested, allowing them to be issued even for tasks that are already in the WAIT state or the SUSPEND state.

Figure 2.6.2a Placing into the SUSPEND State

READY state

Task currently being executed sus_tsk

If a SUSPEND request is issued,the target task is placing into theSUSPEND state.

SUSPEND state


Figure 2.6.2b SUSPEND Request Nesting

� Resuming Tasks in the SUSPEND State

The system call "rsm_tsk" is used to resume a specified task (tskid) that is in the SUSPEND state.



If the specified task is not in the SUSPEND state, the error "B_NOSUS" results.

The system call "frsm_tsk" is used to cancel all nested SUSPEND requests.



While "rsm_tsk" cancels one SUSPEND request, "frsm_tsk" cancels all nested SUSPEND requests.

Fig. 2.6.2c illustrates the cancellation of SUSPEND requests.

Figure 2.6.2c SUSPEND Request Cancellation

Task B SUSPEND count: 7


WAIT-SUSPEND state

SUSPEND count+1

The SUSPEND count is nested. If "sus_tsk" is issued for a task alreadyin the WAIT-SUSPEND state, theSUSPEND request count isincremented by 1.

Task A sus_tsk


One nestedSUSPEND request iscancelled.

All nested SUSPENDrequests are cancelled.

The task returns to the state itwas in when the first SUSPENDrequest was received.

SUSPEND count-1


Task A rsm_tsk Task B

SUSPEND count: 7


Task A frsm_tsk

43

CHAPTER 2 Modules


Softune REALOS/907 supports the following three functions as synchronization and communication functions.

• Semaphore : Resource management • Eventflag : Synchronization with events • Mailbox : Message exchanging

The synchronization and communication functions are implemented by issuing system calls for these objects for event notification, wait operations, status referencing, and polling. Fig. 2.7d illustrates synchronization and communication task state transition.

� System Calls for Synchronization/Communication Objects

System calls for the three types of objects (semaphores, eventflags, and mailboxes) are listed below.

� System calls for semaphores

Fig. 2.7a illustrates the system calls for semaphores.

• sig_sem: Signal operation on a semaphore (V instruction)

• wai_sem: Wait operation on a semaphore (P instruction)

• preq_sem: Wait operation on a semaphore (P instruction + polling)

• sem_sts: References the semaphore status.

Figure 2.7a System Calls for Semaphores

� System calls for eventflags

Fig. 2.7b illustrates the system calls for eventflags.

• set_flg: Sets a 1-bit/16-bit eventflag.

• clr_flg: Clears a 1-bit/16-bit eventflag.

• wai_flg: Waits for a 1-bit/16-bit eventflag.

• cwai_flg: Waits for (and clears) a 1-bit eventflag.

• pol_flg: Waits for a 1-bit/16-bit eventflag by polling.

• cpol_flg: Waits for (and clears) a 1-bit eventflag by polling.

Semaphore

Task 2sig_sem

Semaphore count0 to 255

Task 1 wai_sem

Semaphore waiting task queue

Gets semaphore count

Returns semaphore count

44


• flg_sts: References the status of a 1-bit/16-bit eventflag.

Figure 2.7b System Calls for Eventflags

� System calls for mailboxes

Fig. 2.7c illustrates the system calls for mailboxes.

• snd_msg: Sends a message to a mailbox.

• rcv_msg: Receives a message from a mailbox.

• prcv_msg: Receives a message from a mailbox by polling.

• mbx_sts: References the status of a mailbox.

Figure 2.7c System Calls for Mailboxes

� Synchronization and Communication Task State Transition

Fig. 2.7d illustrates the synchronization and communication task state transition.

Figure 2.7d Synchronization and Communication Task State Transition

Eventflag

Waiting for event

Task 2 set_flg

Set pattern

Clear pattern

Eventflag waiting task queue

Wait pattern

Task 2 clr_flg

Task 2wai_flg

Task 1

snd_msg

Sends message

Task 2

rcv_msg

Receives messageMailbox

‚q‚t‚m

WAIT

READY

DispatchPreempt

Release(sig_sem,set_flg, snd_msg)

Wait(wai_sem,wai_flg,cwai_flg,rcv_msg)

Polling(preq_sem,pol_flg, cpol_flg,prcv_msg

Object can not be gotten

Object can be gotten

RUN

45

CHAPTER 2 Modules

46

2.7.1 Creation of Synchronization/Communication Objects

Synchronization/communication objects can be created statically by specifying them in the Configurator.For details on the method of specification, refer to the "Softune REALOS/907 Configurator Manual."

� Semaphore Creation

The Configurator creates semaphores.


• Semaphore ID number

• Semaphore initialization method

• Semaphore initial value

� Eventflag Creation

The Configurator creates eventflags.


• Eventflag ID number

• Eventflag initial value

• Eventflag management method

� Mailbox Creation

The Configurator creates mailboxes.

• Mailbox ID number

� Object ID number

Specify an ID number within the permitted range.

An ID number from 1 to 127 can be specified. Negative values cannot be used.

Range of ID number

1 Maximum value0

47

MEMO

CHAPTER 2 Modules

48

2.7.2 Resource Management Using Semaphores

Semaphores are primarily used for the management of system resources. Semaphores are used when a resource is used on an exclusive basis. Softune REALOS/907 supports 8-bit counter-type semaphores. The count range is from 0 to 255. Resource management is possible by establishing a relationship between the semaphore count and the number of resources being managed.

� Signal Operations on a Semaphore

The system call "sig_sem" increments the semaphore count by one.


• Semaphore ID number (semid)

When there are tasks waiting, the task at the head of the queue shifts to the READY state.

Fig. 2.7.2a illustrates signal operations on a semaphore.

Figure 2.7.2a Signal Operations on a Semaphore

Semaphore

x : Semaphore valueA : FSemaphore count

Semaphore waiting task queue

Semaphore

Semaphore count x=A

x=A+1

To READY state

Semaphore count x=0

(x-1)³0

Task 2 wai_sem

Task 1 sig_sem

Task 2 wai_sem


� Wait Operations on a Semaphore

The system call "wai_sem" issues a resource acquisition request to the target semaphore.



If there is no semaphore count for the specified semaphore, a wait queue is established. Tasks are handled on a FIFO basis in the semaphore wait queue.

Fig. 2.7.2b illustrates wait operations on a semaphore.

Figure 2.7.2b Wait Operations on a Semaphore

� Polling of Semaphores

The system call "preq_sem" issues a resource acquisition request to the target semaphore.



If there is no semaphore count for the specified semaphore, the task does not enter the wait state; instead, the error "E_PLFAIL" is returned.

To READY state

A>0A=0

Semaphore

Semaphore count x=A

Semaphore

Semaphore count x=0

Semaphore

Semaphore count x=A-1

x : Semaphore valueA : Semaphore count

Task 1 wai_sem

Task 1wai_sem

Task 1 wai_sem

49

CHAPTER 2 Modules

50

2.7.3 Event Notification Using Eventflags

The function of eventflags is to control tasks in response to the occurrence of events. Eventflags are used in fast synchronization processing between two tasks or between a task and a handler.In Softune REALOS/907, when the kernel is set up, it is possible to choose whether to manage eventflags as one bit or as sixteen bits.

� Eventflag Types

Eventflags are used to report events. In Softune REALOS/907, it is possible to choose whether to manage eventflags as one bit or as sixteen bits.

When 1-bit flags are used, eventflags only have two states, "1" and "0". When 16-bit flags are used, each 16-bit value corresponds to a status.

� Operation of 1-bit Eventflags

Values can be set and cleared by using "set_flg" and "clr_flg".


• Eventflag ID number (flgid)

If "set_flg" is issued for an eventflag for which there is a waiting task, the eventflag is set and the task unconditionally leaves the wait queue and enters the READY state. The WAIT state can be cancelled for more than one task by one "set_flg" system call.

� Operation of 16-bit Eventflags

Values can be set and cleared by using "set_flg" and "clr_flg".



• Bit pattern to be set/cleared (setptn/clrptn)

If "set_flg" is issued for an eventflag for which there is a waiting task, the eventflag value and the pattern the task is waiting for are compared. If the necessary conditions are met, the task unconditionally leaves the wait queue and enters the READY state. The WAIT state can be cancelled for more than one task by one "set_flg" system call. The value of the eventflag at the moment that the WAIT state was released is returned as a return parameter to the task that was released from the WAIT state.

Table 2.7.3a illustrates 16-bit eventflag operation.

Table 2.7.3a 16-bit Eventflag operations

set_flg operation clr_flg operation

– setptn…… 0000 0000 0101 clrptn…… 1111 1111 1010

Before eventflag operation …… 1111 0000 0000 …… 0000 1111 1111

↓ ↓ ↓

After eventflag operation …… 1111 0000 0101 …… 0000 1111 1010


� 1-bit Eventflag Wait

When "wai_flg" is issued, a task waits for an eventflag.

When "cwai_flg" is issued, a task waits for an eventflag, after which the target eventflag is cleared.



It is possible for more than one task to be waiting for the same eventflag. Tasks entering an eventflag queue are handled on an FIFO basis.

� 16-bit Eventflag Wait

When "wai_flg" is issued, a task waits for an eventflag.



• Waiting bit pattern (waiptn)

• Waiting mode (wfmode)

It is possible for more than one task to be waiting for the same eventflag. Tasks entering an eventflag queue are handled on an FIFO basis.

� Polling a 1-bit Eventflag

When "pol_flg" is issued, a task polls an eventflag.

When "cpol_flg" is issued, a task polls an eventflag, after which the target eventflag is cleared.

If the waiting conditions for the eventflag that is the target of "pol_flg" or "cpol_flg" are not met, the task does not enter the WAIT state, and "E_PLFAIL" is returned.



� Polling a 16-bit Eventflag

When "pol_flg" is issued, a task polls an eventflag.

If the waiting conditions for the eventflag that is the target of "pol_flg" are not met, the task does not enter the WAIT state, and "E_PLFAIL" is returned.



• Waiting bit pattern (waiptn)

• Waiting mode (wfmode)

51

CHAPTER 2 Modules

52

� Waiting mode (wfmode)

This parameter specifies the eventflag waiting mode.

Table 2.7.3b lists the 16-bit eventflag waiting modes.

Table 2.7.3b 16-bit Eventflag Waiting Modes

� AND Waiting and OR Waiting (16-bit Eventflag)

The "AND waiting" and the "OR waiting" specifications can be made for waiting bit patterns.

If "AND waiting" is specified, a task waits for the eventflag until all of the bits specified as "1" in the waiting bit pattern are set. If "OR waiting" is specified, a task waits for the eventflag until any one of the bits specified as "1" in the waiting bit pattern is set.

Table 2.7.3c lists the 16-bit eventflag waiting specification.

Table 2.7.3c 16-bit Eventflag Waiting Specification

� Clear Specification (16-bit Eventflag)

If the clear specification was made, then when the conditions are met and the task is released from the WAIT state, the eventflag value is cleared to "0".

Fig. 2.7.3 illustrates the changes in an eventflag queue when the clear specification has been made.

Figure 2.7.3 Changes in an Eventflag Queue when the Clear Specification has been Made

Specified mode Label Value

Clear specification TWF_CLR H’ 0001

AND waiting TWF_ANDW H’ 0000

OR waiting TWF_ORW H’ 0002

Condition Waiting pattern Eventflag value Task status

AND 0000000000001111 00000000000011110000000000110011

Releases WAIT state Enters WAIT state

OR 0000000000001111 00000000000000010000000000110000

Releases WAIT state Enters WAIT state

If one of the tasks in the WAIT state has the"clear" specification, any tasks behind that taskin the queue are not released from the waitstate since they will reference the value of theeventflag after it has been cleared.

Set_flg

Eventflag

Eventflag

Tasks waiting for an eventflagare handled on a FIFO basis.

Task 3Task 2

Task 1 Clear specification

Task 3Task 2

53

MEMO

CHAPTER 2 Modules

54

2.7.4 Communications Using Mailboxes

Mailboxes are a message passing function. Mailboxes are used for passing asynchronous messages between tasks or between a task and a handler.In communications via mailboxes, messages are sent and received through the exchange of message pointers. Because copies are not made of messages when they are sent or received, fast communications are possible.In general, the "get_blk" system call is used to get a memory block from the memorypool; the memory block is then used as a memory storage area for messages.

� Sending Messages

In communications via mailboxes, messages are sent and received through the exchange of message pointers. Because copies are not made of messages when they are sent or received, fast communications are possible.

In general, the "get_blk" system call is used to get a memory block from the memorypool; the memory block is then used as a memory storage area for messages.

Fig. 2.7.4a illustrates a message that is to be sent.

Figure 2.7.4a Message to be Sent

� Sending Messages to a Mailbox

Messages are sent by using the "snd_msg" system call.


• Mailbox ID number (mbxid)

• Starting address of message to be sent (pk_msg)

The starting address of the message is sent to the specified mailbox. If there are waiting tasks, the message is passed to the first task in the queue.

If a message is sent to a mailbox with no waiting tasks, the message that was sent is added to the message queue. Messages in the message queue are handled on a FIFO basis.

Message addressMailbox

msgcnt[size](size-1)bytes

Reserved Area used by the OS

Area containing the actualmessage

Address that is sent to/received from the mailbox

0

+4

Body of message Body of message


Fig. 2.7.4b illustrates a message queue in a mailbox.

Figure 2.7.4b Message Queue in a Mailbox

� Receiving Messages from a Mailbox

A "get message" request is issued by using the "rcv_msg" system call.



If a message has already arrived in the specified mailbox, the first message is received.

If there are no messages in the mailbox, the task enters the waiting task queue. Tasks in the waiting task queue are handled on a FIFO basis.

Fig. 2.7.4c illustrates tasks in a queue waiting to receive messages.

Figure 2.7.4c Tasks in a Queue Waiting to Receive Messages

� Polling Messages from a Mailbox

A "get message" request is issued by using the "prcv_msg" system call.



If a message has already arrived in the specified mailbox, the first message is received.

If there are no messages in the mailbox, the task does not enter the WAIT state; instead, the error "E_PLFAIL" results.

Mailbox

Task 4

Priority 1

Task 4 rcv_msg Priority 1

Task 2

Priority 3

Task 1

Priority 1

Mailbox

55

CHAPTER 2 Modules

56

2.7.5 Referencing the Status of Synchronization/Communication Objects

The "sem_sts", "flg_sts" and "mbx_sts" system calls are used to reference the status of the synchronization/communication objects.

� Referencing the Status of a Semaphore

The "sem_sts" system call is used to reference the status of a semaphore.



• Starting address of the packet that is to be used for referencing the semaphore status (pk_sems)

� Data returned by "sem_sts"

The following information is returned in the packet that was specified for the return parameters.

� Referencing the Status of an Eventflag

The "flg_sts" system call is used to reference the status of an eventflag.



• Starting address of the packet that is to be used for referencing the eventflag status (pk_flgs)

� Data returned by "flg_sts"


In the case of a one-bit eventflag, a binary value is stored in the current eventflag pattern: 0: cleared state, 1: set state.

In the case of a 16-bit eventflag, a 16-bit value is stored.

Current semaphore count valueWaiting tasks?

semcntwtsk

+0

+2

+4

pk_sems

Current eventflag patternWaiting tasks?

flgptnwtsk

+0

+2

+4

pk_flgs


s)

� Referencing the Status of a Mailbox

The "mbx_sts" system call is used to reference the status of a mailbox.



• Starting address of the packet that is to be used for referencing the mailbox status (pk_mbxs)

� Data returned by "mbx_sts"


Because it is not possible for a waiting message queue and a sending message queue to both exist at the same time, at any given moment either "wtsk" must be "FALSE" or "pk_msg" must be "NADR".

Address of next message ("NADR" when there are no waiting messageWaiting tasks?

pk_msgwtsk

+0

+4

+8

pk_mbxs

57

CHAPTER 2 Modules


In Softune REALOS/907, the memorypool management functions are supported as functions that dynamically manage the system's memory space. The memorypool management functions dynamically manage unused memory space that is shared by tasks and handlers. Memory is assigned upon request by a task. Fig. 2.8a illustrates the flow of the memorypool management functions. Fig. 2.8b illustrates memorypool management task state transition.

� MemoryPool System Calls

The memorypool management function system calls are listed below.

� System calls that get/release memory

• get_blk: Gets memory.

• pget_blk: Gets memory by polling.

• rel_blk: Releases memory.

� System call that references the status of the memorypool

• mpl_sts: References the status of the memorypool.

� Flow of MemoryPool Management Functions

Figure 2.8a Flow of MemoryPool Management Functions

Tasks get memory blocks from the memory pool as needed.Memory blocks are released after processing.

Created by theConfigurator

Memory block

Memory block

Memory block

Memory block

Memory block

Memorypool

rel_blk

Release memory block

Memory

A portion of free memory isused as the memorypoolfor allocation to memoryblocks

Tasks can use "get_blk" and"rel_blk" to get and releaseindividual memory blocks within thememorypool

Memory block

get_blk

Get memory block

Task A

58


� MemoryPool Management Task State Transition

Figure 2.8b illustrates memorypool management task state transition.

Figure 2.8b MemoryPool Management Task State Transition

Memory can not be gotten

Memory can be gotten

RUN

WAIT

READY

Dispatch

Preempt

Release(rel_blk)

Wait(get_blk)

Polling(pget_blk)

59

CHAPTER 2 Modules

60

2.8.1 MemoryPool Creation

Softune REALOS/907 supports fixed length memorypools. Therefore, memory is divided into memory blocks of a suitable size and then managed accordingly.Static memorypools are created through specification in the Configurator. For details on the method of specification, refer to the "Softune REALOS Configurator Manual."

� MemoryPool Creation

Memorypools are created by the Configurator. Specify the following parameters.

• Memorypool ID number

• Size of memory blocks

• Number of memory blocks

❍ Memorypool ID number

Specify an ID number within the allowable range.

An ID number from 1 to 127 can be specified. Negative values cannot be used.

Range of ID numbers

0 1 Maximum value


� Size of memory blocks, number of memory blocks

Specify the size of the memory blocks to be created, and the number of memory blocks to be created.

Fig. 2.8.1 illustrates the memory block size and number specifications.

Figure 2.8.1 Memory Block Size and Number Specification

Memorypool

blksz: Specifies the size of the memory blocks

blknum: Number of memory blocks Size of the entire memorypool = blksz x blknum

61

CHAPTER 2 Modules

62

2.8.2 Getting and Releasing Memory Blocks

Requests to get memory blocks are issued by using the "get_blk" and "pget_blk" system calls. A memory block that was previously gotten is released by using the "rel_blk" system call.

� Getting Memory Blocks

A request to get a memory block is issued by using the "get_blk" system call.


• Memorypool ID number (mplid)

• Pointer for the area where the memory block pointer is stored (p_blk)

When a memory block is successfully gotten from the memorypool, the starting address of the memory block that was gotten is returned to the task, and the task continues with its processing. When a memory block could not be successfully gotten, the task enters the waiting task queue. Tasks are added to this queue on a FIFO basis. The manner in which the task joins the queue is illustrated in Fig. 2.8.2a.

Figure 2.8.2a Addition of a Task to the MemoryPool Waiting Task Queue

� Releasing Memory Blocks

A memory block that was gotten previously is released by using the "rel_blk" system call.



• Memory block starting address (blk)

The error "E_ILBLK" is returned if a memory block is released back to a different memorypool than the one that it was gotten from.

Sometimes when a memory block is released, a task in the WAIT state gets its requested memory block and places from the WAIT state into the READY state.

Memory blocks are given to waiting tasks on a FIFO basis.

Obtaining and returning memory blocks must be done on a one-to-one correspondence with a memorypool. If a memory block that has not been obtained is returned, memory control operations thereafter will not be correct.

Fig. 2.8.2b illustrates the release of a memory block.

Task 4

Priority 1

Task 4 get_blk Priority 1

Task 2

Priority 3

Number of memory blocks 0

Memorypool Task 1

Priority 1


Figure 2.8.2b Memory Block Release

� Getting Memory from a MemoryPool by Polling

A request to get a memory block can be issued by using the "pget_blk" system call.



• Pointer for the area where the memory block pointer is stored (p_blk)

When the specified memory could not be gotten, the task does not enter the waiting task queue; instead the error "E_PLFAIL" is returned to the task.

Task A

get_blk

Memorypool A

Task A

rel_blk

A memory block gotten from memorypool A mustbe returned to memorypool A. If it is returned toa different memorypool, the error “E_ILBLK” isreturned to the task.

Memorypool B

E_ILBLK is returned.

63

CHAPTER 2 Modules

64

2.8.3 Referencing the MemoryPool Status

The memorypool status is referenced by using the "mpl_sts" system call.

� Referencing the MemoryPool Status

The memorypool status is referenced by using the "mpl_sts" system call.



• Starting address of the packet that is to be used to return the memorypool status (pk_mpls)

� Data returned by mpl_sts


Size of one memory blockSize of entire memorypool

blkszmplsz

+0

+2

+4

pk_sems

Number of empty blocksfrbcntID number of the first task in the waiting task queue wtskid

+6

+8 (a false "0" is returned if there are no waiting tasks)

65

MEMO

CHAPTER 2 Modules


Softune REALOS/907 provides interrupt management functions such as interrupt handler definition and interrupt processing execution control.

� Interrupt Management Function System Calls

The interrupt management function system calls are listed below.

� System calls concerning management of interrupt level mask values

• chg_ilv: Changes interrupt level mask values.

• ilv_sts: References interrupt level mask values.

� Interrupts and Interrupt Handlers

Generally, the term "interrupt" refers to both external interrupts from peripheral devices and internal interrupts, including exceptions generated by the processor and software interrupts. In Softune REALOS/907, the term "interrupt" will be used in a narrow sense to refer to external interrupts.

The user creates processing programs for interrupts and defines them as interrupt handlers. When an interrupt is generated, the interrupt handler processing is executed with attributes that are independent of those of the task. These execution attributes are referred to as the "task-independent section."

� Interrupt Handler Processing

An interrupt handler is executed directly by the processor that received the interrupt. At the start of interrupt handler processing, it is necessary to save the registers that will be used in the interrupt handler. When interrupt processing is completed, it is necessary to restore the saved registers to their original states and then return from the interrupt handler.

Interrupt processing is executed using the task-independent section execution attributes. There are restrictions on the system calls that can be executed in the task-independent section. Table 2.9 lists the system calls that can be issued from the task-independent section.

� Standard Interrupt Processing

A general interrupt handler has the processing structure shown in Fig. 2.9.

66


Table 2.9 System Calls that can be Executed from the Task-independent Section

Figure 2.9 Interrupt Processing

System call Description

sta_tskter_tskchg_prirot_rdqget_tidtsk_sts

Starts a task. Forcibly terminates another task. Changes the priority of a task.Rotates the task ready queue. References the task's own ID number. References the task status.

sus_tskrsm_tskfrsm_tskwup_tskcan_wup

Forcibly shifts another task into the SUSPEND state. Resumes a task that was in the SUSPEND state. Forcibly resumes a task that was in the SUSPEND state. Wakes up another task.Cancels a task wake-up request.

sig_sempreq_semsem_stsset_flgclr_flgpol_flgcpol_flgflg_stssnd_msgprcv_msgmbx_sts

Returns a semaphore resource. (V instruction) Gets a semaphore resource. (P instruction/polling) References the status of a semaphore. Sets an eventflag. [1-bit/16-bit] Clears an eventflag. [1-bit/16-bit] Waits for an eventflag. (polling) [1-bit/16-bit] Waits for an eventflag. (polling) [1-bit] References the status of an Eventflag. [1-bit/16-bit] Sends a message to a mailbox. Receives a message from a mailbox. (polling) References the status of a mailbox.

ret_intret_wupchg_ilvilv_sts

Returns from an interrupt handler. Returns from an interrupt handler and wake-up a task.Changes an interrupt level mask value. References an interrupt level mask value.

pget_blkrel_blkmpl_sts

Gets a memory block from a memorypool. (polling) Returns a memory block to a memorypool. References the status of a memorypool.

set_timget_timact_cycret_tmr

Sets the system clock. References the system clock. Controls the active state of a cyclic handler. Returns from a timer handler.

get_ver References the version.

Processing continuedfrom the interrupt handler

Shift to WAIT state

Save the necessary registers

Processing for the device thatgenerated the interrupt

Releases the WAIT state taskthat requested processing

Restores the save registers

Performs processing that mustbe executed on an emergencybasis, such reading in datathat was input.

Interrupt handlerprocessing

Task processing

Peripheraldevice

67

CHAPTER 2 Modules

68

2.9.1 Interrupt Handler Definition

The Configurator can dynamically define interrupt processing corresponding to a specified interrupt definition number.For details on the method of definition, refer to the "Softune REALOS Configurator Manual."

� Interrupt Handler Definition

Interrupt handlers are defined by the Configurator.

Specify the following parameters.

• Interrupt definition number

• Interrupt handler address

� Interrupt definition number

Specify the interrupt number of the corresponding interrupt.

In the F2MC-16L/16LX/16/16H/16F specifications, the range of interrupt numbers indicated below are allocated for external interrupts; interrupt handlers can be defined for each of these numbers.

� Interrupt handler address

Specify the starting address for the interrupt handler processing. If the corresponding interrupt is generated, processing starts from this address.

Interrupt vector number

H’0B(11)

0

Configurator input

H’29(41)

H’2A(42)

H’FF

DI Delayed Interrupt


2.9.2 Interrupt Processing Execution Control

The interrupt level of a specified interrupt is changed by using the "chg_ilv" system call. The interrupt level can be referenced by using the "ilv_sts" system call.

� Changing the Interrupt Level

The interrupt level of a specified interrupt (IRQn) is changed by using the "chg_ilv" system call.


• Interrupt number (intno)

• Interrupt level value (intlv)

� Referencing the Interrupt Level

The interrupt level can be referenced by using the "ilv_sts" system call.

69

CHAPTER 2 Modules


Softune REALOS/907 provides time management functions that use an interrupt from a hardware timer as a reference for synchronized processing. This permits the implementation of functions synchronized with time, such as that specified for time-outs. It is also possible to define and execute processing as cyclic handlers (for processing that is executed cyclically, independent of any tasks) or as alarm handlers (for processing that is executed at a specified time). Cyclic handlers and alarm handlers are called "timer handlers."

� System Calls Used for Time Management

The system calls used for time management are listed below.

� Setting/referencing the time

• set_tim: Sets the system clock.

• get_tim: Reads the value of the system clock.

� Time-out processing

• wai_tsk: Places a task into the WAIT state for a certain period of time (task-dependent synchronization function system call).

� Timer handler management

• def_cyc: Defines a cyclic handler.

• act_cyc: Controls the activation of a cyclic handler.

• cyh_sts: References the status of a cyclic handler.

• def_alm: Defines an alarm handler.

• alh_sts: References the status of an alarm handler.

70


� System Clock and Actual Time

An interrupt is generated by the hardware timer at a constant interval. This interval of time is called the "system reference clock." In the example shown below, a timer interrupt is generated every 1 ms. The count of interrupts in each system reference clock cycle is called the "system clock."

Set the system reference clock in accordance with the user’s system. For example, it is possible to set a 1-ms interrupt by the watch timer for the reference clock, or to set a synchronized pulse (variable from 30 ms to 4 ms) that is generated at each rotation of a rotating drum for the reference clock.

Actual time can be calculated on the basis of the system reference clock and the system clock.

Actual time = (system reference clock) × (system clock)

Ex.: System reference clock: 1 ms

System clock: 60,000

1 × 60,000 = 60,000 ms = 60.000 sec.

� System Clock Data

The system clock is handled as 48-bit unsigned data. The range of values for the system clock is 0 to (248 - 1). Because the F2MC-16L/16LX/16/16H/16F uses 32-bit registers, the system clock value is separated into two values. In cases where there is no need for a particularly long time interval specification, such as for the time-out specification, 16-bit data is used.

� System Reference Clock

In order to permit operation according to the same time references on different systems, the µITRON specifications define "system reference time." If system reference time is adopted, the system clock value is set to a value representing the cumulative number of milliseconds since the system reference time.

System reference time: January 1, 1985 = 0

At system startup, the system clock value is initialized to "0". Set the system clock value to the standard value, based on the current time.

Specification using 16-bit data : timeout, etc.

Specification using 48-bit data : absolute time, etc.Unsigned values

Bits

utime ltime15 0 31 0

0 to FFFF

System clock value

‚O (2 -1)48

71

CHAPTER 2 Modules

72

� Cyclic Handler Processing

Cyclic handler processing is executed according to the execution attributes of the task-independent section. There are restrictions on the system calls that can be executed in the task-independent section. Refer to section 2.9, "Interrupt Management Functions."

Cyclic handlers are executed from the Softune REALOS/907 system clock handler as software interrupt processing. Therefore, at the start of cyclic handler processing, it is necessary to save the registers that will be used in the cyclic handler. When the cyclic handler processing is completed, it is necessary to restore the saved registers to their original states and then execute the "ret_tmr" system call.

Fig. 2.10a illustrates cyclic handler processing.

Figure 2.10a Cyclic Handler Processing

� Releasing the Definition of a Cyclic Handler

The definition of a cyclic handler is released when NADR "-1" is specified for "pk_cyh" in "def_cyc".

The cyclic handler is executed as a subroutinefrom the system clock handler used by the kernel.

Interrupt generated bythe hardware timer

ret_tmr

Cyclic handler


Calls thetimer

handler


� Alarm Handler Processing

Alarm handler processing is executed according to the execution attributes of the task-independent section. There are restrictions on the system calls that can be executed in the task-independent section. Refer to section 2.9, "Interrupt Management Functions."

Alarm handlers are executed from the Softune REALOS/907 system clock handler as software interrupt processing. Therefore, at the start of alarm handler processing, it is necessary to save the registers that will be used in the alarm handler. When the alarm handler processing is completed, it is necessary to restore the saved registers to their original states and then execute the "ret_tmr" system call.

Fig. 2.10b illustrates alarm handler processing.

Figure 2.10b Alarm Handler Processing

� Releasing the Definition of an Alarm Handler

The definition of an alarm handler is released in either of the following cases:

• When NADR "-1" is specified for "pk_alh" in "def_alm"

• When execution of the alarm handler terminates

Interrupt generated bythe hardware timer

ret_tmr

Alarm handler


Calls thetimer

handler

The alarm handler is executed as a subroutinefrom the system clock handler used by the kernel.

73

CHAPTER 2 Modules

74

2.10.1 Setting and Reading the System Clock

The system clock value is set to the specified value by using the "set_tim" system call.The current system clock value can be read by using the "get_tim" system call.

� Setting the System Clock

The system clock value is set to the specified value by using the "set_tim" system call.


• Address of packet showing the current time (pk_time)

• Time data (utime, ltime)

If the "set_tim" system call is used to change the system clock while the Softune REALOS/907 system is running, the times at which tasks waiting for a certain time and timer handlers waiting for execution will operate may vary. If you want a task or handler to operate at a specific time, it is necessary to reset that time. Tasks or handlers that are to operate after the passage of a relative amount of time will operate normally.

Fig. 2.10.1a illustrates the setting of the system clock.

Figure 2.10.1a Setting the System Clock

� Reading the System Clock

The current system clock value can be read by using the "get_tim" system call.


• Address of the packet in which the current time is to be returned (pk_time)

Fig. 2.10.1b illustrates the process if reading the system clock.

Figure 2.10.1b Reading the System Clock

set_tim

utime ltime

15:00:00

12

39

6

get_tim

utime ltime

9:00:00

12

39

6


2.10.2 Time-out Processing

The time-out specification can be made using the "wai_tsk" system call.

� Time-out Time

If a task is not released from the WAIT state before a specified time elapses, the WAIT state is forcibly released and "E_TMOUT" is returned.

The time data specified in this case is 16-bit system clock data.

When "0" is specified, tasks do not enter the WAIT state.

� Time-out Error

If the conditions being awaited are not met within the specified time-out time, a time-out error results and the task is placed into the READY state. Fig. 2.10.2 illustrates the time-out error.

Figure 2.10.2 Time-out Error

0

Time-out time

(2 -1)16

Time-out time

wai_tsk Error E_TMOUTExecutionstate

75

CHAPTER 2 Modules

76

2.10.3 Definition of Cyclic Handlers

Cyclic handlers can be defined by using the "def_cyc" system call.

� Definition of Cyclic Handlers

Cyclic handlers can be defined by using the "def_cyc" system call.


• Cyclic handler specification number (cyhno)

• Cyclic handler address (cychdr)

• Cyclic handler activation status (cyhact)

• Cyclic time interval (cytime)

� Cyclic handler specification number (cyhno)

Specify an unused specification number within the range.

The maximum value is specified during system configuration.

If a value outside of the range is specified, the error "E_PAR" is returned.

� Cyclic handler address (cychdr)

Specify the address of the cyclic handler being defined.

� Cyclic handler activation status (cyhact)

Specify the cyclic handler activation status. The "TCY_ON | TCY_INI" and "TCY_OFF" specifications are illustrated below.

If a status other than "TCY_ON", "TCY_OFF" or "TCY_INI" is specified, the error "E_RSMD" results.

Cyclic handler specification number

1 Maximum value

Cyclicexecution

Cyclicexecution

Cyclicexecution

Cyclicexecution

“TCY_ON | TCY_INI” Specification

Cyclic interval Cyclic intervalCyclic interval Cyclic interval

Wait state

Handler initiationret_tmr

Time

ret_tmr ret_tmr ret_tmr

Cyclicexecution

Cyclic interval


� Cyclic interval time (cytime)

Specify the cyclic interval time.

When cytime = 0, the error "E_ILTIME" results.

“TCY_OFF” Specification

Wait state

Handler execution The handler is not executed even if the specified time elapses.

Time

Cyclic intervalCyclic interval Cyclic interval Cyclic intervalCyclic interval

Cyclicexecution

Cyclicexecution

Cyclicexecution

Cyclicexecution

Cyclicexecution

Cyclic interval time

1 (216 -1)

77

CHAPTER 2 Modules

78

2.10.4 Cyclic Handler Control

The activation status of a cyclic handler can be controlled by using the "act_cyc" system call.

� Cyclic Handler Control

The activation status of a cyclic handler can be controlled by using the "act_cyc" system call.

Specify the following parameters.


• Cyclic handler activation status (cyhact)

� Cyclic handler activation status

• Stopping execution of a cyclic handler

Specify "TCY_OFF" for "cyhact". Once this specification is made, the cyclic handler is not executed even when the specified time elapses.

• Resuming execution of a cyclic handler

Specify "TCY_ON" for "cyhact". In this case, the length of time from when this system call is issued until the first execution of the first handler is not constant.

• Initializing the count for a cyclic initiation handler

Specify (TCY_ON || TCY_OFF) | [TCY_INI] for "cyhact".

If (TCY_ON | TCY_INI) was specified for "cyhact", the handler is first initiated exactly when the specified time elapses after the execution of this system call.

“TCY_ON” Specification

Wait state

Handler executionret_tmr

Time

ret_tmr ret_tmr

act_cycissuance

“TCY_ON|TCY_INI” Specification

ret_tmr

Time

ret_tmr

Wait state

Handler executionact_cyc

issuance

Cyclic interval Cyclic interval Cyclic interval

Cyclic interval Cyclic interval Cyclic interval Cyclic interval


2.10.5 Referencing the Status of a Cyclic Handler

The status of a cyclic handler can be referenced by using the "cyh_sts" system call.

� Referencing the Status of a Cyclic Handler

The status of a cyclic handler can be referenced by using the "cyh_sts" system call.



• Starting address of the packet to which the cyclic handler status is to be returned (pk_cyhs)

� Data returned by cyh_sts


Cyclic interval time Time remaining before next execution of handler

cytimelftime

+0

+2

+4

pk_cyhs

Cyclic handler activation statuscyhact+6

79

CHAPTER 2 Modules

80

2.10.6 Definition of Alarm Handlers

Alarm handlers can be defined by using the "def_alm" system call.

� Definition of Alarm Handlers

Alarm handlers can be defined by using the "def_alm" system call.


• Alarm handler specification number (alhno)

• Alarm handler address (almhdr)

• Handler execution time (time)

• Execution time specification mode (tmmode)

� Alarm handler specification number (alhno)

Specify an unused specification number within the range.

The maximum value is specified during system configuration.

If a value outside of the range is specified, the error "E_PAR" is returned.

� Alarm handler address (almhdr)

Specify the address of the alarm handler being defined.

� Handler execution time (time)

Specify the alarm handler execution time with 48-bit signed system clock data.

� Execution time specification mode (tmmode)

TTM_ABS (0): Absolute time specification

If an execution time specification made in absolute time is for a time prior to the current time, the error "E_ILTIME" is returned.

Alarm handler specification number

Maximum value1

System startup def_almissuance

Absolute time Time


2.10.7 Referencing the Status of an Alarm Handler

The status of an alarm handler can be referenced by using the "alh_sts" system call.

� Referencing the Status of an Alarm Handler

The status of an alarm handler can be referenced by using the "alh_sts" system call.


• Alarm handler specification number (alhno)

• Starting address of the packet to which the alarm handler status is to be returned (p_lftime)

� Data returned by alh_sts

Time remaining until handler execution (low-order 4 bytes) ltime

+0

+4

p_lftime

Time remaining until handler execution (high-order 2 bytes)utime+6

81

CHAPTER 2 Modules

2.11 System Management Function (Getting the Version Number)

In Softune REALOS/907, a function that gets the ITRON version number is provided as a system management function.

� System Management Function System Call

The system management function system call is indicated below.

• get_ver: Gets the ITRON version number.

� Getting the Version Number

The ITRON version number can be referenced by using the "get_ver" system call.

Specify the following parameter. The data shown in Fig. 2.11 is returned in the specified packet.

• Starting address of the packet to which the version information is to be returned (pk_ver)

Figure 2.11 Information Gotten by get_ver

Level classification of kernel specifications 000 : mITRON 001 : Reserved 010 : Reserved 011 : ITRON2 basic specifications 100 : ITRON2 partially expanded specifications 101 : ITRON2 expanded specifications 110 : Reserved 111 : Reserved

M=1 : Multiprocessor supportM=0 : Single processorV=1 : Virtual memory supportP=1 : MMU support

Level classification of file specifications 00 : Not supported 01 : <<FI0>> specifications 10 : <<FI1>> specifications 11 : Reserved

I/O specifications 00 : Not supported 01 : Standard specifications 10 : Reserved 11 : Reserved

Version descriptor0 151412 1310 119841 3 5 6 7

0 00IOFIL000LEV M V P

spec ver

ITRON/mITRON specification version number

TRON specification class 0 : Common to TRON 1 : ITRON 1, ITRON2 2 : BTRON 3 : CTRON 4 : Reserved 5 : mITRON 6 : mBTRON

TRON specification version Represented by three-digit packed BCD code

0 3 4 15

MAGIC

OS producer/developer Indicates the developer. H'0009 : Fujitsu

ITRON/mITRON specification version number

CPU data Indicates the CPU information.

OS format number Indicates the product release. H'0001: Release 1

OS product version number Indicates the version of this product. H'0401: Version 4, level 1

Product number, productmanagement information Indicates the management information for this product.

Version descriptor Provides an overview of the functions that can be used in this product. H'0000: mITRON specifications

Single processorFile supportNo I/O support

cpu var

maker idspver prver

prno[1]prno[2] prno[3]prno[0]

82


83


The exception management functions perform processing regarding abnormalities generated by the system.In Softune REALOS/907, processing regarding exceptions can be defined and executed as an "exception handler."

� Types of Exceptions

Table 2.12a lists the types of exceptions defined in Softune REALOS/907.

Table 2.12a Exceptions Generated in Softune REALOS/907

� CPU Exception Handler and System Call Exception Handler

The CPU exception handler is executed as an interrupt generated by the CPU when an undefined instruction error or an address access error occurs while the CPU is executing instructions.

The system call exception handler is executed when an error occurs during the execution of Softune REALOS/907 system call processing.

Two types of system call exception handlers can be selected in the Configurator. For one type, the exception handler is called for all system call errors; in the other, the exception handler is called only for errors other than "E_OK", "E_PLFAIL", and "E_TMOUT".

The CPU exception handler or system call exception handler are executed when the execution of program processing is the cause. One exception handler of either type can be defined in the system; the same exception handler is executed by exceptions that are generated within tasks and handlers.

� Manipulating Exception Information and the Registers After Return

By overwriting exception information, it is possible to change the contents of registers after returning from a system call. The relationship between the overwritten exception information and the contents of registers after return is shown in Table 2.12b.

Table 2.12b Exception Information and Registers after Return

Exception Description of exception Cause of exception

CPU exception Exception generated by a processor Processor instruction execution

System call exception Exception generated when an error occurred during execution of a system call System call processing execution

Exception information Registers after return

Error code (pk_expt -> ersc) AL register

Error flag (pk_expt -> erfg) When equal to 0, zero flag is cleared When not equal to zero, zero flag is set

Register information other than AL and zero flag (pk_expt -> reglist) Register corresponding to exception information

CHAPTER 2 Modules

84

2.12.1 Exception Handler Processing

Exception handler processing is called from the kernel as a subroutine.When an exception is generated due to some abnormality, an exception handler is executed. Information on the type of exception that was generated and data such as the value of the registers when the exception was generated are passed to the exception handler as parameters. For details on the parameters, refer to section 3.7, "Creating Exception Handlers."

� Exception Handler Processing

Because exception handler processing is called from the kernel as a subroutine, exception handler processing is terminated by restoring the registers, etc., to the state they were in when the exception handler was executed and then by returning control to the kernel. Fig. 2.12.1 illustrates exception handler processing.

Figure 2.12.1 Exception Handler Processing

Use the PCB:PC values in the exception information in order to determine the cause of the exception.

It is possible to change the contents of the registers after returning from the system call by overwriting the contents of the exception information. In the case of a CPU exception, because it is not possible to return to a program where an exception occurred as is, it is necessary to overwrite the return address (PCB:PC) within the exception information. The question of what address to return to depends on the contents of the program processing. When a CPU exception occurs, if the task that generated the exception is interrupted or forcibly terminated and processing that generates an infinite loop is set as the return destination, it is possible to immediately switch processing to another task after returning from the exception handler.

If the registers after returning have been changed, it is highly possible the unexpected results will be obtained. Be very careful when changing the registers.

If an exception occurred in a task, the exception information is stored in the task's own stack and is then passed to the exception handler. Therefore, in a system where an exception handler is registered, it is necessary to allocate adequate space for the stacks belonging to each task. In addition, because it is possible for interrupt processing to be executed or even another exception to be generated during exception processing, it is necessary to consider both the size of the stack used in the interrupt processing as well as the size of the stack used by the exception handler itself.

When exception processing by the CPUexception handler is completed, controlreturns to the location where the exception was generated.

CPUexceptiongenerated

retp

CPU exception handler

When exception processing by the the systemcall exception handler is completed, controlreturns to the location where the exception was generated.

Task Task

System callexceptiongenerated

System call exception handler

retp


The contents of the I, ILM, S, and RP registers that are set when the exception handler is executed are the same as their contents were when the system call that generated the exception was called.

The contents of the AL and AH registers and of flags other than those in the I, ILM, and S registers are undefined.

The CPU exception handler is registered by setting the starting label in the Configurator and then setting the kernel label "r97_cpu_expt" in the INT #10 vector area (FFFFD4 to FFFFD6).

A label setting as a CPU exception handler is called by the "r97_CPU_expt".

85

CHAPTER 2 Modules

86

2.12.2 Exception Handler Definition

Only one user-created CPU exception handler or system call exception handler can be defined by the Configurator.For details on the method of specification, refer to the "Softune REALOS Configurator Manual."

� Exception Handler Definition

Only one user-created CPU exception handler or system call exception handler can be defined by the Configurator.


• Exception handler address

• System call exception handler type

� Exception handler address

Specify the exception handler processing start address. If an exception is generated, processing starts from this address.

� System call exception handler type

Specify the system call exception handler processing method.

If type 1 is selected, exception processing is performed for all errors.

If type 2 is selected, exception processing is performed for all errors other than "E_OK", "E_PLFAIL", and "E_TMOUT".

CHAPTER 3 Creating Application Programs

This chapter discusses points that require special attention when creating user application programs.

3.1 Program Types

3.2 Issuing System Calls

3.3 Task Creation

3.4 Initialization Handler Creation

3.5 Interrupt Handler Creation

3.6 Timer Handler Creation

3.7 Exception Handler Creation

3.8 System Clock Handler

3.9 System Clock Handler Interface

87


3.1 Program Types

The programs that run under the Softune REALOS/907 can be broadly classified into tasks and handlers.When creating programs, depending on the type of task or handler being created, their characteristics may differ and there may be restrictions on the system calls that can be issued.Softune REALOS/907 task and handler programs can be written in either C language or in assembly language. Tasks and handlers written in C language are written as a single function. Details on writing each type of program in C language or assembly language are provided in the individual sections on program creation.

� Program Types

Table 3.1 describes the program types.

Table 3.1 Program Types

Class Program name Program contents

Tasks User task Tasks that perform user processing. (Task section)User-created idle task. (Task section)

Handlers

Initialization handler Handler that is initiated first after kernel startup; starts up and initializes tasks. (Task independent section)

Interrupt Handler Handler that performs processing in response to interrupts.(Task independent section)

Timer handlerHandler that manages time based on the system clock; in order to use a timer handler, it is necessary to create a system clock handler program.

Cyclic handler Handler that is executed at a specified time interval. (Task independent section)

Alarm handler Handler that is executed at a specified time. (Task independent section)

Exception handler

Handler that performs processing when an exception is generated The execution attributes of the handler that is executed differ according to the location where the exception was generated.

• Exception handler (task-independent section) for exceptions generated in the task-independent section

• Exception handler (task section) for exceptions generated in the task section

CPU exception handler Exception handler for CPU exceptions

System call exception handler

Exception handler for errors accompanying the execution of system calls

System clock handler program Handler that calls the system clock handler for OS

88

3.1 Program Types

� Programs written in C

In Softune REALOS/907, the processing interface is based on the use of registers. Therefore, it is necessary to adapt the interface to the execution of kernel system calls from C.

• Execution of system calls from programs written in C

In order to execute system calls from programs written in C, use the C compiler’s in-line expansion function for ITRON system call functions. For details, refer to section 3.2, "Issuing System Calls."

89



This section describes the issuance of system calls in C and in assembly language.

� Issuing System Calls in C

When issuing a system call in C, describe the system call as a function call.

For the function formats from each system call, refer to chapter 4, "System Calls."

Fujitsu’s C compiler for the F2MC-16L/16LX/16/16H/16F Series includes a system call function in-line expansion option (-K REALOS); if a program is compiled with this option specified, code that issues the system calls is generated.

� Issuing System Calls in Assembly Language

When issuing a system call in assembly language, the necessary parameters are in set the registers and stack, and then the software trap instruction (the "intp" instruction) is executed. However, when actually writing the program, use the "scall" macro function.

For details on the registers in which parameters must be set for each system call, refer to chapter 4, "System Calls."

90

91

MEMO


92

3.2.1 Issuing System Calls in C

System calls are issued in C either by using the system call function in-line expansion feature of the C compiler, or by using the system call interface library.

� System Call Function In-line Expansion

Fujitsu’s C compiler for the F2MC-16L/16LX/16/16H/16F Series includes a system call function in-line expansion option (-K REALOS).

If a program with system calls described as C function calls is compiled with this option specified, code that sets the necessary parameters in the registers and stack and then calls the kernel is generated.

For details on how to specify this option, refer to the "FR family F2MC family Optimized C Compiler Manual."

Fig. 3.2.1 illustrates the execution of system calls through in-line expansion.

Figure 3.2.1 Execution of System Calls through In-line Expansion

Program written in C

_task

mv a, #1 intp sta_tsk

TASK task() {

}

ercd=sta_tsk(1)

Code generated by C compiler

Kernel

System callprocessing

Compile


� Issuing "sta_tsk" in C

The issuance of "sta_tsk" in C is shown below.

tskid=TSK_ID;ercd=sta_tsk(tskid);if (ercd!=E_OK)

err();

93


94

3.2.2 Issuing System Calls in Assembly Language

When issuing a system call in assembly language, the necessary parameters are set in the registers, and then the F2MC-16L/16LX/16/16H/16F software interrupt instruction (the "intp" instruction) is executed. However, when actually writing the program, use the "scall" macro function.

� Issuing System Calls in Assembly Language

The procedure for issuing system calls is as follows:

(1) Set the necessary parameters in the registers.

(2) Execute the software interrupt instruction.

(3) After the execution of system call processing, the return parameters are returned to each register.

For details on the parameters and return parameters for each system call, refer to chapter 4, "System Calls."

� Issuing "sta_tsk" in Assembly Language

The issuance of "sta_tsk" in assembly language is shown below.

movn a,#TSK_ID

scall sta_tsk

3.3 Task Creation

95

3.3 Task Creation

Tasks can be described in C or in assembly language.

� Describing a Task Program in C

When describing a task program in C, the task is described as one function. It is necessary to issue the "ext_tsk" system call at the end of the task program.

� Describing a Task Program in Assembly Language

When describing a task program in assembly language, it is necessary to issue the "ext_tsk" system call at the end of the task program.

� When Providing a User-defined Idle Task

An idle loop (consisting of just an infinite loop) is included in the kernel. If the user does not provide an idle task, the idle task included in the kernel is used. However, if the idle loop is to be used for some sort of processing, the user creates the idle task. An idle task is written as a task that executes an infinite loop. The idle task thus created must be given a lower task priority than all other tasks in the Configurator task definition.


96

3.3.1 Describing a Task Program in C

When describing a task program in C, the task is described as one function.It is necessary to issue the "ext_tsk" system call at the end of the task program.

� Example of a Task Program Described in C

An example of a task program described in C is shown below.

#include "scdef.h"

TASK taskA() /∗ Task name task A ∗/

{

.

.

.

.

.

.

.

.

Task processing

.

.

.

.

.

.

.

.

ext_tsk(); /∗ Task end ∗/

}

TASK idle_task() /∗ Idle task ∗/

{

while (1) {

; /∗ Endless loop ∗/

}

}

97

MEMO


98

3.3.2 Describing a Task Program in Assembly Language

When describing a task program in assembly language, it is necessary to issue the "ext_tsk" system call at the end of the task program.

� Register Statuses when a Task is Initiated (before issue of sta_tsk)

Fig. 3.3.2 shows the register statuses when a task is initiated.

Figure 3.3.2 Status of Registers upon Task Initialization

Indeterminate

(Stack area for task that is runnning)

Stack size for taskthat is running~ ~

0

(System stack area)

System stack size~ ~

Context informationContext information

Indeterminate

Task start address

Indeterminate

AH

AL

DPR

RW7

USP

USB

Indeterminate

PC

ILM:RP:CCRPS

SSP

SSB

ADB

DTB

PCB

RW0

Specification duringconfiguration



Task startbank address

Context information or contentsof register bank indicated by RP

3.3 Task Creation

� Example of a Task Program Described in Assembly Language

An example of a task program described in assembly language is shown below.

#include scdef.h

.IMPORT ext_tsk

.

.

.

.

.

.

.

.SECTION CODE,CODE, ALIGN=2

.

.

.

.

.

.

.

.EXPORT taskA

taskA: mov A,#3 ; Task name task A.......

Task processing

.

.

.

.

.

.

.

scall ext_tsk ; Task end

(.ALGN)

.EXPORT idle-task

idle-task: bra idle-task ; Endless Loop.......

99



The initialization handler can be described in C or in assembly language.

� Describing the Initialization Handler Program in C

When describing the initialization handler program in C, the initialization handler is described as one function.

This function must be described and compiled as an interrupt function. For details on how to describe interrupt functions, refer to the "FR family F2MC family SOFTUNE C Compiler Manual."

� Describing the Initialization Handler Program in Assembly Language

When describing the initialization handler program in assembly language, the initialization handler program is responsible for saving the register status.

The initialization handler terminates with the "reti" instruction. However, when actually writing the program, use the "scall" macro instruction to call the "ret_int" system call.

When the initialization handler is executed, all tasks are in the DORMANT state. At this point, the first task that must enter the READY state is woken up.

100


3.4.1 Describing the Initialization Handler Program in C

When describing the initialization handler program in C, the initialization handler is described as one function. This function must be described and compiled as an interrupt function. For details on how to describe interrupt functions, refer to the "FR family F2MC family SOFTUNE C Compiler Manual."

� Example of an Initialization Handler Program Described in C

An example of an initialization handler program described in C is shown below.

• When "_inihdr" is defined in the configuration definition statement "INIT_HDR_ENTRY"

#include "scdef.h"

#pragma register(2) /∗ Register bank specification ∗/

__interrupt INIHDR inihdr() /∗ Initialization handler name inihdr ∗/

{

.

.

.

.

.

.

Initialization handler procesing

.

.

.

.

.

.

ret_int(); /∗ Handler end ∗/

}

#pragma noregister

101


102

3.4.2 Describing the Initialization Handler Program in Assembly Language

When describing the initialization handler program in assembly language, the initialization handler program is responsible for saving the register status when an interrupt is generated.The initialization handler terminates with the "reti" instruction. However, when actually writing the program, use the "scall" macro instruction to call the "ret_int" system call.

� Register Statuses when the Initialization Handler is Executed

Fig. 3.4.2 shows the register statuses when the initialization handler is initiated.

Figure 3.4.2 Status of Registers upon Initialization Handler Execution


~ ~

0

Initialization handlerstart bank address

* : Register bank set in the initialization handler

Old PSOld PC

Old PCBOld DTBOld ADBOld DPR

Old ALOld AH

~~

- 2- 4- 6- 8

-10-12

Stack size for taskthat is running

System stack size

(System stack area)

Indeterminate

Indeterminate

Initialization handler start address

Indeterminate

Indeterminate

AH

AL

DPR

RW7

USP

USB

Indeterminate

PC

ILM:RP:CCRPS

SSP

SSB

ADB

DTB

PCB

RW0

*

Indeterminate



� Example of an Initialization Handler Program Described in Assembly Language

An example of an initialization handler program described in assembly language is shown below.

• When "_inihdr" is defined in the configuration definition statement "INIT_HDR_ENTRY"

#include scdef.inc

data.SECTION.DATA.H

DATA, DATA, ALIGN=24

.SECTION CODE, CODE, ALIGN=2

inihdr: ; Initialization handler name inihdr

movmovmovmovw

rp, #INIRGa, #BNKSYM(data)adb, arw2, #data

; Register bank specification

.

.

.

.

.

.

.

Initialization handler processing

.

.

.

.

.

scall ret_int ; Handler end.....

.end

103



The interrupt handler can be described in C or in assembly language.

� Describing the Interrupt Handler Program in C

When describing the interrupt handler program in C, the interrupt handler is described as one function.

This function must be described and compiled as an interrupt function. For details on how to describe interrupt functions, refer to the "FR family F2MC family SOFTUNE C Compiler Manual."

� Describing the Interrupt Handler Program in Assembly Language

When describing the interrupt handler program in assembly language, the interrupt handler program is responsible for saving the register status when an interrupt occurs.

The interrupt handler terminates with the "reti" instruction. However, when actually writing the program, use the "scall" macro instruction to call the "ret_int" system call.

104


3.5.1 Describing the Interrupt Handler Program in C

When describing the interrupt handler program in C, the interrupt handler is described as one function. This function must be described and compiled as an interrupt function. For details on how to describe interrupt functions, refer to the "FR family F2MC family SOFTUNE C Compiler Manual."

� Example of an Interrupt Handler Program Described in C

An example of an interrupt handler program described in C is shown below.

#include "scdef.h"

#progma register(2) /∗ Register bank specification ∗/

__interrupt INTHDR inthdrA() /∗ Initialization handler name inthdrA ∗/

{

.

.

.

.

.

Interrupt handler processing

.

.

.

.

.

ret_int(); /∗ Handler end ∗/

}

#pragma noregister

105


106

3.5.2 Describing the Interrupt Handler Program in Assembly Language

When describing the interrupt handler program in assembly language, the interrupt handler program is responsible for saving the register status when an interrupt is generated.The interrupt handler terminates with the "reti" instruction. However, when actually writing the program, use the "scall" macro instruction to call the "ret_int" system call.

� Register Statuses when the Interrupt Handler is Executed

Fig. 3.5.2 shows the register statuses when the interrupt handler is executed.

Figure 3.5.2 Status of Registers upon Interrupt Handler Execution

Interrupt handler start address

~ ~

0 Old PSOld PC


Old ALOld AH

~~

- 2- 4- 6- 8

-10-12

Indeterminate

AH

AL

DPR

RW7

USP

USB

Indeterminate

Indeterminate

PC

ILM:RP:CCRPS

SSP

SSB

ADB

DTB

PCB

RW0

*



Interrupt handlerstart bankaddress

* : Level of external interrupt that was received

System stack size

(System stack area)



� Example of an Interrupt Handler Program Described in Assembly Language

An example of an interrupt handler program described in assembly language is shown below.

#include scdef.inc

data.SECTION.DATA.H

DATA, DATA, ALIGN=24


inthdrA: ; Handler name inthdrA

movmovmovmovw

rp, #INTRGa, #BNKSYM(data)adb, arw2, #data

; Register bank specification

.

.

.

.

.

.

.

Initialization handler processing

.

.

.

.

.

scall ret_int ; Handler end

.end

107



A timer handler can be described in C or in assembly language. There are two types of timer handlers:

• Cyclic handlers • Alarm handlers

� Describing a Timer Handler Program in C

When describing a timer handler program in C, the timer handler is described as one function.

� Describing a Timer Handler Program in Assembly Language

When describing a timer handler program in assembly language, the timer handler program is responsible for saving the register status when the timer handler is executed.

The timer handler terminates with the "reti" instruction. However, when actually writing the program, use the "scall" macro instruction to call the "ret_tmr" system call.

108


3.6.1 Describing a Timer Handler Program in C

When describing a timer handler program in C, the timer handler is described as one function.

� Example of a Timer Handler Program Described in C

Examples of timer handler programs described in C are shown below.

• For a cyclic handler

• For an alarm handler

#include "scdef.h"


__interrupt CYCHDR cychdrA() /∗ Handler name cychdrA ∗/

{

.

.

.

.

Cyclic initiation handler processing

.

.

.

.

ret_tmr() ; /∗ Handler end ∗/

}

#pragma noregister

#include "scdef.h"


__interrupt ALMHDR almhdrA() /∗ Handler name almhdrA ∗/

{

.

.

.

.

Alarm handler processing

.

.

.

.

ret_tmr() ; /∗ Handler end ∗/

}

#pragma noregister

109


110

3.6.2 Describing a Timer Handler Program in Assembly Language

When describing a timer handler program in assembly language, the timer handler program is responsible for saving the register status when the timer handler is initiated.The timer handler terminates with the "reti" instruction. However, when actually writing the program, use the "scall" macro instruction to call the "ret_tmr" system call.

� Register Statuses when a Timer Handler is Executed

Fig. 3.6.2 shows the register statuses when the timer handler is executed.

Figure 3.6.2 Status of Registers upon Timer Handler Execution

~ ~

0

* : System clock interrupt level

Old PSOld PC


Old ALOld AH

~~

- 2- 4- 6- 8

-10-12

Timer handlerstart address

Indeterminate

Indeterminate

AH

AL

DPR

RW7

USP

USB

Indeterminate

Indeterminate

PC

ILM:RP:CCRPS

SSP

SSB

ADB

DTB

PCB

RW0

*


Timer handlerstart bankaddress

Context information or contentsof register bank indicated by RP System stack size

(System stack area)



� Example of a Timer Handler Program Described in Assembly Language

An example of a timer handler program described in assembly language is shown below.

• For a cyclic handler

• For an alarm handler

#include scdef.inc

.SECTION CODE,CODE,ALIGN=2

cychdrA: ; Handler name cychdrA

mov rp, #2 ; Register bank specification.....

Cyclic initiation handler processing

.

.

.

.

.

scall ret_tmr ; Handler end

.end

#include scdef.inc

.SECTION CODE,CODE,ALIGN=2

almhdrA: ; Handler name almhdrA

mov rp, #2 ; Register bank specification.....

Alarm handler processing

.

.

.

.

.

scall ret_tmr ; Handler end

.end

111



Exception handlers can be described in C or assembly language. There are two exception handlers:

• CPU exception handler • System call exception handler

For details, refer to section 2.12, "Exception Management Functions," in chapter 2, "Modules."

� Describing an Exception Handler in C

When describing an exception handler program in C, the exception handler is described as one function. When an exception handler is executed, the information regarding the generation of the exception is passed to the exception handler as the arguments for this function.

� Describing an Exception Handler in Assembly Language

When describing an exception handler program in assembly language, the pointer that points to the information regarding the generation of the exception is stored in the stack (@ SP + 4) when the exception handler is initiated.

The exception handler is terminated by the "retp" instruction.

� Handler Entry Names

The entry names specified in the Configurator definition statement and the function name of the exception handlers must match. When a handler is described in C, the symbol "_" must be added in front of the C function name in the Configurator definition statement.

� Registration in the Interrupt Vectors (CPU Exception Handler Only)

In order to use the CPU exception handler function, it is necessary to register the kernel label "r97_cpu_expt" in the INT #10 vector area (H’FFFFD4 to H’FFFFD6).

This setting is made automatically if the exception handler is registered in the Configurator.

112

113

MEMO


114

3.7.1 Describing an Exception Handler Program in C

When describing an exception handler program in C, the exception handler is described as one function. When an exception handler is executed, the information regarding the generation of the exception is passed to the exception handler as the arguments for this function.

� Parameters Passed to the Exception Handlers

The following are the parameters that are passed to the exception handler arguments.

T_EXPT ∗pk_expt : Exception generation information 1

: Exception generation information 2

typedef struct t_expt {

INT ersc; : System call function code (not used in the CPU exception handler)

INT ercd; : Error code (not used in the CPU exception handler)

INT erfg; : Error flag

INT tskid; : ID of task where exception occurred

T_EXPTRG ∗pk_exptrg; : Register values when exception occurred

} T_EXPT;

typedef struct t_exptrg {

UH usp_reg: : USP register value

UH ssp_reg: : SSP register value

UB usb_reg: : USB register value

UB ssb_reg: : SSB register value

UH ps_reg: : PS register value

UH pc_reg: : PC register value

UB pcb_reg: : PCB register value

UB dtb_reg: : DTB register value

UB adb_reg: : ADB register value

UB dpr_reg: : DPR register value

UH al_reg: : AL register value

UH ah_reg: : AH register value

} T_EXPTRG;


� Example of an Exception Handler Program Described in C

An example of an exception handler program described in C is shown below.

#include "scdef.h"

#progma except

Configurator definition statement

EXTHDR scerrhdr(T_EXPT ∗pk_expt) SYS_EXTHDR_ENTRY _scerrhdr, 2

/∗ Exception handler name scerrhdr ∗/

{

.

.

.

.

Record of names of system calls that generated exceptions, etc.

.

.

.

.

return ; /∗ Handler end ∗/

}

EXTHDR systemdownhdr(T_EXPT ∗pk_expt) /∗ Exception handler name systemdownhdr ∗/

{ /∗ r97_cpu_expt label registration in INT #10 required ∗/....

Record of system status for reference at restart

.

.

.

.

cpu_reset() ; /∗ CPU reset ∗/

} Configurator definition statement

CPU_EXTHDR_ENTRY _systemdownhdr

#pragma noexcept

115


116

3.7.2 Describing an Exception Handler Program in Assembly Language

When describing an exception handler program in assembly language, the pointer that points to the information regarding the generation of the exception is stored in the stack (@ SP + 4) when the exception handler is executed.The exception handler is terminated by the "retp" instruction.

� Register Statuses when an Exception Handler is Executed

Fig. 3.7.2 shows the register statuses when an exception handler is executed.

Figure 3.7.2 Status of Registers upon Exception Handler Execution


* : Interrupt level value when exception was generated

~

Exception handlerstart address

Indeterminate

Indeterminate

AH

AL

DPR

RW7

SP

SPB

Indeterminate

Indeterminate

PC

ILM:RP:CCRPS

ADB

DTB

PCB

RW0

*

Exceptionhandler startbank address

+26 AHAL

usp_regtskid

~

+24+22+21+10+ 8+ 6

erfgercdersc

Exception handler return address

dpr_reg

Pointer for the exception information

+ 4+ 2

0+ 8+ 4

0



� Example of an Exception Handler Program Described in Assembly Language

An example of an exception handler program described in assembly language is shown below.

• For system call exceptions

#include scdef.inc

.SECTION CODE,CODE, ALIGN=2

.EXPORT serrhdr

serrhdr: ; Exception handler name serrhdr

mov rp, #0 ; Register bank specification

movw rw2,@(rw3+4) ; Task, non-task determination

mov a, @(rw3+6)

mov adb, a

movw a, @(rw2+6)

bz notask ; If a handler, jump to "notask".....

; Processing of errors that occurred in a task

Error processing

.

.

.

.

.

bra end

.ALIGN 2

notask: ; Processing of errors that occurred in a handler.....

Error processing

.

.

.

.

.

end: retp ; Handler end

ALIGN 2

.end


SYS_EXTHDR_ENTRY serrhdr

117


118

• For CPU exceptions

#include scdef.inc


.EXPORT except

except: ; Exception handler name except

mov rp, #0 ; Register bank specification

movw rw2,@(rw3+4) ; Task, non-task determination

mov a, @(rw3+6)

mov adb, a

movw a, @(rw2+6)

bz notask ; If a handler, jump to "notask".....

; Processing of errors that occurred in a task

Error processing

.

.

.

.

.

bra end

.ALIGN 2

notask: ; Processing of errors that occurred in a handler.....

Error processing

.

.

.

.

.

end: retp ; Handler end

.ALIGN 2

.end


CPU_EXTHDR_ENTRY except

119

MEMO



Kernel time management uses the system clock as a reference. The system clock is generated by calling the system clock handler on a fixed cycle.The system clock handler is provided as a part of the kernel. However, the user is responsible for creating the processing that calls the system clock handler on a fixed cycle, and other related processing.The user cyclically executes the user clock handler.

� System Clock Handler

The system clock handler performs the following processing.

• System clock updating

• Cyclic handler management and execution

• Alarm handler management and execution

• "wai_tsk" time-out management

The system clock required for kernel time management is implemented by cyclically executing the system clock handler. There are five different methods for implementing the system clock. For details, refer to section 3.9, "System Clock Handler Interface." The user selects one of these methods and describes a system clock program and vector definition in accordance with the selected method; in addition, the user selects a system clock return method in the Configurator for the selected system clock implementation method.

Execute the system clock handler at the interrupt processing level.

When using the system calls indicated below, it is necessary to create a system clock handler program.

� Task-dependent synchronization function

wai_tsk

� Time management functions

set_tim, get_tim

def_cyc, act_cyc, cyh_sts

def_alm, alh_sts

120


� System Clock Handler Program

The system clock handler is provided on the kernel side. The user creates a system clock handler program that cyclically executes the system clock handler. Generally, because the system clock is counted on a fixed cycle, the system clock handler should be designed so that it is executed according to the interval timer interrupt. The creation of the hardware for the timer used for the system clock is left to the user’s discretion.

Depending on the timer used for the system clock, other timer-related processing may be required in addition to executing the timer handler. For example, an interrupt program that is executed by a timer interrupt should be created with consideration given to the need to clear that timer interrupt request (making preprocessing needed), the need to set the next count value because there is no reload function (making post-processing needed), and the need for commonality with the user’s own timer management processing (making pre- or post-processing needed).

Note: Use the initialization handler to initialize and start up the system clock timer.

121



The system clock handler is executed cyclically, using any of the following five methods.

a. call <system clock handler entry address> (execute in assembler program) → Return method selection: RET instruction

b. callp <system clock handler entry address> (execute in assembler program)→ Return method selection: RETP instruction

c. jmp[p] <system clock handler entry address> (execute in assembler program) → Return method selection: ret_int system call

d. Register <system clock handler entry address> in interrupt vector→ Return method selection: ret_int system call

e. (∗r97_tbl.sclkhdr)(); (execute in C program) → Return method selection: RETP instruction (create C program on large model) → Return method selection: RET instruction (create C program on small model)

Note: In the case of method a, b, or e, issue "ret_int" to terminate the origin of the system clock handler call.

� System Clock Handler Interface

System clock handler entry address:

An address indicated by either of the following:

• Label name: r97_sclk_hdr, _r97_sclk_hdr

• Address stored in a four-byte area from kernel configuration (_r97_tbl) offset 20

Return parameters: None

Register save: When "call" or "callp" are used, AL, AH, and the various arithmetic flags are lost.

Stack used: 2 bytes (excludes stack used by subroutines or function calls)

Methods "a" "b" and "e" are used when some sort of operations concerning the timer circuit are required before or after the execution of the system clock handler. In this situation, issue the "ret_int" system call at the end of the interrupt processing that was the origin of the system clock handler call.

With method "a" select the "ret" instruction in the Configurator for the system clock handler return method; with methods "b" and "e" select the "retp" instruction.

Method "c" is used when the system clock handler is executed from an application interrupt handler and then the interrupt processing is terminated. It is necessary, right before the execution of the "jmpp" instruction, to restore the stack pointer (SP) value to its value at the start of interrupt processing. Select "ret_int" for the system clock handler return method.

In method "d" the system clock handler is registered as a direct interrupt handler.

122


Once the system clock handler label "r97_sclk_hdr" is registered in an interrupt vector, it is possible to execute the system clock handler directly from a timer interrupt. Select "ret_int" for the system clock handler return method.

In method "e," the system clock handler is executed by referencing the address stored in r97_tbl.sclkhdr in C(declared as external reference as exterm T_R97_TBL r97_tbl;).

After registering a user-created handler in an interrupt vector, call the system clock handler from the user-created handler. Issue the "ret_int" system call as the method of return from the user-created handler.

Fig. 3.9 summarizes the above information.

*:Part B in (e) varies with a compiler mode

Figure 3.9 System Clock Handler Return Methods

Creation method Part A Part B Part C Pre-processing

Post-processing

(a)(b)

(c)(d)

C language (e)(5)

callcallpjmp [p]

–(∗r97_tbl.sclkhdr)()

retretp

ret_intret_intretp

or ret*

ret_intret_int

––

ret_intret_int

YesYesYesNoYesYes

YesYesNoNoYesYes

Return method can be selected in the Configurator

Task User-created timer interrupt processing

Pre-processing

Post-processing

A

C

System clock handler

System clock handler provided by Softune REALOS/907

B

Assembly language

123

124

MEMO

CHAPTER 4 System Calls

This chapter describes the Softune REALOS/907 system calls in a reference format.

4.1 List of System Calls

4.2 System Call Descriptions

4.3 Task Management Function System Calls

4.4 Task-Dependent Synchronization Function System Calls

4.5 Synchronization/Communication Function System Calls

4.6 MemoryPool Management Function System Calls

4.7 Interrupt Management Function System Calls

4.8 Time Management Function System Calls

4.9 System Management Function System Calls

125


4.1 List of System Calls

The system calls are listed in Table 4.1 by function.

� List of System Calls

Table 4.1 List of System Calls

Function System call

Function codeDescription

DEC HEX

Task management

sta_tskext_tskter_tskchg_prirot_rdqget_tidtsk_sts

-23-21-25-27-28-24-20

H’FFE9H’FFEBH’FFE7H’FFE5H’FFE4H’FFE8H’FFEC

Starts a task. Terminates the task issuing the call. Forcibly terminates another task. Changes the priority of a task. Rotates the task ready queue. Gets the task’s own ID number. Gets the task status.

Task-Dependent synchronization

sus_tskrsm_tsk

frsm_tskslp_tskwai_tsk

wup_tskcan_wup

-33-35-36-38-37-39-40

H’FFDFH’FFDDH’FFDCH’FFDAH’FFDBH’FFD9H’FFD8

Forcibly places a task into the SUSPEND state. Resumes a task that was in the SUSPEND state. Forcibly resumes a task that was in the SUSPEND state.Moves a task into the WAIT state. Moves a task into the WAIT state for a certain period of time.Wakes up a task in the WAIT state. Cancels a task wake-up request.

Synchronization/communications

sig_semwai_sem

preq_semsem_sts

set_flgclr_flg

wai_flgcwai_flg

pol_flgcpol_flg

flg_stssnd_msgrcv_msg

prcv_msgmbx_sts

-55-53

-203-52-48-47-46-45

-202-201-44-63-61

-204-60

H’FFC9H’FFCBH’FF35H’FFCCH’FFD0H’FFD1H’FFD2H’FFD3H’FF36H’FF37H’FFD4H’FFC1H’FFC3H’FF34H’FFC4

Semaphore signal operation (V instruction) Gets a semaphore resource. (P instruction) Gets (polls) a semaphore resource. (P instruction) References the status of a semaphore. Sets a 1-bit/16-bit eventflag. Clears a 1-bit/16-bit eventflag. Waits for a 1-bit/16-bit eventflag. Waits for a 1-bit eventflag (and clears the flag). Waits for (polls) a 1-bit/16-bit eventflag. Waits for (polls) a 1-bit eventflag (and clears the flag). References the status of a 1-bit/16-bit eventflag. Sends a message to a mailbox. Receives a message from a mailbox. Receives (polls) a message from a mailbox. References the status of a mailbox.

Memory poll management

get_blkpget_blk

rel_blkmpl_sts

-77-205-79-76

H’FFB3H’FF33H’FFB1H’FFB4

Gets memory. Gets (polls) memory. Returns memory. References the memorypool status.

Interrupt managementret_int

ret_wupchg_ilvilv_sts

-69-70-67-68

H’FFBBH’FFBAH’FFBDH’FFBC

Returns from an interrupt handler. Returns from interrupt processing and wakes up a task. Changes an interrupt mask. References an interrupt mask.

Time management

set_timget_timdef_cycact_cyccyh_stsdef_almalh_stsret_tmr

-83-84-90-94-92-89-91-93

H’FFADH’FFACH’FFA6H’FFA2H’FFA4H’FFA7H’FFA5H’FFA3

Sets the system clock. Reads the system clock value. Defines a cyclic initiation handler. Controls the active state of a cyclic handler. References the status of a cyclic handler. Defines an alarm handler. References the status of an alarm handler. Returns from a timer handler.

System management get_ver -16 H’FFF0 Gets the ITRON version number. DEC: Decimal HEX: Hexadecimal

126

127

MEMO



The format for the system call descriptions in this chapter is explained below.

� System Call Descriptions

<System call name (Caps)> (<function English>)

<Description of function Japanese>-20 Task section Task independent section

<C language interface>

<Assembly language interface>

Function code(decimal) Indicates whether this system

call can be issued from the task section

: Can be issued × : Cannot be issued

Indicates whether this system call can be issued from the task-independent section

: Can be issued × : Cannot be issued

Error code as function valueSystem call name

Parameters Parameter declarationParameter names

Memory packetstructures

Explanation ofparameters


Format ER ercd=tsk_sts(T_TSKS * pk_tsks, ID tskid);typedef struct t_tsks [

TSTA tskstat ; TPRI tskpri ;

} T_TSKS ;Input parameters tskid Task ID

TSK_SELF(0): Own task specificationpk_tsks Pointer for area where task information is stored

Output parameters ercd Error code ("E_OK" is normal)pk_tsks->tskstat Task status codepk_tsks->tskpri Task priority

ADB:AH+0 tskstat

tskpri+1

Task status code

Task priority

Registerallocations forparameters

+2


Input parameters ADB:AH Starting address of area (two bytes) where task information is stored

AL Task IDSystem calls scall tsk_stsOutput parameters ·ZF 1: Normal end

AL E_OK

·ZF 0: Error end AL Error code

128


<Error codes>

<Dispatching causes>

<Description>

<Examples>

Errors that could begenerated whenthis system call isissued

<Error codes>DescriptionLabel Code

E_RSID

E_OK

E_IDOVR

-23

-35

Normal endTSK_SELF specified in task_independentsectionID number is too large

0

<Dispatching causes>

This system call does not create a dispatching situation.Causes of dispatchingfor this system call

<Description>

References the information on the specified task.Description and notes regardingthe processing performed bythis system call

<Examples>

Example of thesystem call beingissued in C language

#include"scdef.h" #define TSKID_2 2

TASK task_1() { ERercd; T_TSKS pk_task;

ercd = tsk_sts(&pk_task,TSKID_2);

}

C language interface

#include scdef.inc.IMPORT tsk_sts

tasksts: .RES.B 2

mov a,#BNKSYM(tasksts)mov adb,amovw a,#taskstsmv a,#TASK_IDscall tsk_stsbnz error

Assembly language interface

˝˝

˝

˝˝

˝

Example of thesystem call beingissued in assemblylanguage

129


130

4.2.1 Parameters

In the C language interface items, the parameters are represented in the format shown in Table 4.2.1.When writing a program for Softune REALOS/907, use parameters that accord with these data types.

� Data Types Used in Softune REALOS/907

Table 4.2.1 Data Types Used in Softune REALOS/907

Type declaration Description Remarks

typedef signed chartypedef signed shorttypedef signed longtypedef signed chartypedef signed shorttypedef signed longtypedef Htypedef UH

B;H;W;UB;UH;UW;INT;UINT;

Signed 8-bit integerSigned 16-bit integerSigned 32-bit integerUnsigned 8-bit integerUnsigned 16-bit integerUnsigned 32-bit integerSigned 16-bit integerUnsigned 16-bit integer

typedef signed chartypedef signed shorttypedef signed long

VB;VH;VW;

Variable data type (8 bits)Variable data type (16 bits)Variable data type (32 bits)

Data type varies; the number of bits is known, but the data type is unknown

typedef voidtypedef void FAR

∗VP;( ∗FP)();

Pointer with variable data type Program start address

typedef VW BOOL; Boolean value FALSE (0) TRUE (1)

typedef Htypedef INTtypedef UBtypedef H

ID;ER;TSTA;HNO;

Object ID number Error code Task status code Handler number

Range 0 to 127

typedef Btypedef UHtypedef UHtypedef UHtypedef UHtypedef UHtypedef UH

TPRI;FPTN;SCNT;MEMSZ;BCNT;CY;TMO;

Task priority Eventflag Semaphore count Memory size Number of memory blocks Cycle count Time-out

Range 1 to 16

Range 0 to 255

Range (0) to (215-1)Range (0) to (215-1)

typedef INT FN; Function code

typedef void FARtypedef void FARtypedef void FARtypedef void FARtypedef void FARtypedef void

IHIHDR;INTHDR;CYCHDR;ALMHDR;EXTHDR;TASK;

Initialization handler typeInterrupt handler type Cyclic handler type Alarm handler type Exception handler type Task type

131

MEMO


132

4.2.2 Parameters that Require Caution

This section describes parameters that require extra caution. While not specifically noted in the system call descriptions, pay attention to the following points.

� Task ID Numbers

The task ID numbers are used to identify tasks.

The maximum value for the task ID number is registered in the OS during system configuration.

� Object ID Numbers (ID Numbers Other Than Task ID Numbers)

The object ID numbers are used to identify objects.

The maximum value for the object ID number is registered in the OS during system configuration.

This restriction applies to "semid", "flgid", "mbxid", and "mplid".

tskid : Task ‚h‚c (Task Identifier)ID number of task to be executed

Meaning of parameter

The following restriction applies to task ID numbers.

User ID number

Indicates the current task itself (TSK_SELF).

0 1 255


The following restriction applies to object ID numbers.

User ID number

Reserved; cannot be specified

0 1 127

flgid : Eventflag ID (Eventflag Identifier)Eventflag ID number used to reference the status


� Handler Numbers (Timer Handler Numbers)

The handler numbers are used to identify handlers.

The maximum value for the handler number is registered in the OS during system configuration.

This restriction applies to "cycno" and "almno".

� Task Priority Levels

The initial priority level upon task initialization (TPRI_INI) is valid when "chg_pri" is issued. The maximum priority level currently running (TPRI_RUN) is valid when "rot_rdq" is issued.

This restriction applies to "itskpri" and "tskpri".

cycno : Cyclic Handler Number (Cyclic Handler Number)Number for cyclic handler being defined


The following restriction applies to handler specification numbers.

User ID number

Reserved; cannot be specified

0 1 127

Parameter value that requires special attention when the system call isissued

The following restriction applies to priority levels.

Indicates the priority level upon task initialization (TPRI_INI).Indicates the maximum priority level currently running (TPRI_RUN).

tskpri : Task Priority Level (Task Priority)

TPRI_INI(0) : Changes priority level to the priority level that wasspecified for task initialization when the task wascreated

For user0 1 16

133


134

4.2.3 Time-out Specification Restrictions

In the parameter descriptions, there is no special mention of the following restrictions concerning the time-out specification.

� When a Time-out is Specified

When the conditions are met within the specified time → Normal end

When the conditions are not met within the specified time → Error (E_TMOUT)

� Relationship between "tmout" and Actual Time

The relationship between "tmout" and actual time is as follows:

(Actual time) = (tmout) × (system reference clock)

� Time-out Specification

Fig. 4.2.3 shows a typical example of a time-out specification.

Figure 4.2.3 Time-out Specification

tmout : Time-out specification(Timeout)(0) to (216-1) : Specification of time-out time


135


There are seven system calls for the task management functions.• sta_tsk • rot_rdq • ext_tsk • get_tid • ter_tsk • tsk_sts • chg_pri

� Task Management Function System Calls

There are seven system calls for the task management functions.

� sta_tsk (Start Task)

This system call starts a task.

� ext_tsk (Exit Task)

This system call terminates the current task.

� ter_tsk (Terminate Task)

This system call forcibly terminates another task.

� chg_pri (Change Task Priority)

This system call changes the task priority level.

� rot_rdq (Rotate Ready Queue)

This system call rotates the task ready queue.

� get_tid (Get Task Identifier)

This system call gets the ID of the current task.

� tsk_sts (Task Status)

This system call references the status of the specified task.


136

4.3.1 sta_tsk (Start Task)

This system call starts a task.-23 Task section Task independent section


Format: ER ercd = sta_tsk(ID tskid) ;

Input parameters: tskid Task ID

Output parameters: ercd Error code (E_OK: normal)


Input parameters: AL Task ID

System call: scall sta_tsk

Output parameters: • ZF 1: Normal endAL E_OK

• ZF 0: Error endAL Error codes

<Error codes>

<Dispatch causes>

When a task with a higher priority level than the task that issued this system call is started, the new task is dispatched.

<Description>

The "sta_tsk" system call starts the specified task according to the information in the task definition statement specified in the Configurator. The started task moves from the DORMANT state to the READY state.

The processing performed by this system call includes setting the stack pointer, setting the register bank, setting the task priority level, and starting the program. In addition this system call initializes the task wake-up request queue and suspend request queue counts to "0".

If the specified task is not in the DORMANT state, "E_NODMT" is returned. "E_NODMT" is also returned if the "own task" specification (TSK_SELF = 0) was made from the task section.

"E_RSID" is returned if "TSK_SELF" was specified in the non-task section.

"E_IDOVR" is returned if the value exceeding the maximum number of tasks designated by the configurator or the negative value is specified to the task ID.

Label Code Description

E_OKE_RSIDE_IDOVRE_NODMT

0-23-35-54

Normal end "TSK_SELF" was specified in a non-task ID number too large Task is not in DORMANT state


<Examples>

• C language interface

• Assembly language interface

#include "scdef.h"#define START_TSK_ID 2TASK master_task() /∗ Task ID = 1 ∗/{

:sta_tsk(START_TSK_ID) ; /∗ Starts task ∗/

:}

TASK user_tsk() /∗ Task ID = 2 ∗/{

:}

#include scdef.inc.IMPORT sta_tsk

START_TASK_ID .equ 2 :mv a, #START_TASK_IDscall sta_tsk ;Starts taskbnz error :

137


138

4.3.2 ext_tsk (Exit Task)

This system call terminates the current task.-21 Task section Task independent section ×


Format: void ext_tsk(void);

Input parameters: None

Output parameters: In case of normal endDoes not return to the source of the call.

In the case of an error end Returns "E_CTX" to the AL register and enters an infinite loop.



System call: scall ext_tsk

Output parameters: • None : Normal endDoes not return to the source of the call.

• ZF 0: Error endAL Error codes

Return "E_CTX" to the AL register and enters an infinite loop.

<Error codes>

The following error code is valid only at exception handling.

<Dispatch causes>

When the task that issued this system call terminates, the task with the next highest priority ranking is dispatched.


E_CTX -69 Context error (used from the non-task section)


<Description>

The "ext_tsk" system call terminates the current task and moves it into the DORMANT state. Because this processing terminates the task, control does not return to the source of the call.

The "ext_tsk" system call can not be executed from the non-task section. If this system call is issued from the non-task section, "E_CTX" is returned and the task enters an infinite loop.

The "ext_tsk" system call does not release resources (memory blocks, semaphores, etc.) previously obtained by the task. If it is necessary to release resources, execute "sig_sem" (V instruction) or "rel_blk" before executing the "ext_tsk" system call.

Always use the "ext_tsk" system call to terminate a task program.

When the "ext_tsk" system call is issued, the execution right always is passed to another task in the READY state (or, if there are none, an idle task).

<Examples>



#include "scdef.h"

TASK task1(){

: ext_tsk() ; /∗ Task end ∗/

}

#include scdef.inc.IMPORT ext_tsk

:.EXPORT task1

task1: :

scall ext_tsk ; Task end :

139


140

4.3.3 ter_tsk (Terminate Task)

This system call forcibly terminates another task.-25 Task section Task independent section


Format: ER ercd = ter_tsk(ID tskid);

Input parameters: tskid Task ID (1 to maximum task ID)



Input parameters: AL Task ID (1 to maximum task ID)

System call: scall ter_tsk


• ZF 0: Error occurredAL Error codes

<Error codes>

<Dispatch causes>

This system call does not create a dispatching situation.


E_OKE_RSIDE_IDOVRE_SELFE_DMT

0-23-35-49-53

Normal end "TSK_SELF" was specified for a task ID in the non-task section ID number too large Task specified itself Task is in DORMANT state


<Description>

This system call forcibly terminates the specified task. Specify a task ID ranging from 1 to the highest possible task ID. If the specified task is in the DORMANT state, "E_DMT" is returned. If the current task is specified, "E_SELF" is returned.

If "TSK_SELF" is specified for the task ID in the non-task section, "E_RSID" is returned.

If a value that exceeds the maximum number of tasks as specified in the Configurator is specified for the task ID, or if a negative value is specified for the task ID, "E_IDOVR" is returned.

Resources acquired by the target task (memory blocks, semaphores, etc.) are not automatically released by this system call.

If the specified task is in the WAIT or SUSPEND state, that task is moved from the WAIT state to the DORMANT state by this system call.

<Examples>



#include "scdef.h"

TASK task1(){

:ter_tsk(2) ; /∗ Forcibly terminates the task indicated ∗/

/∗ by task ID "2". ∗/:

}

#include scdef.inc.IMPORT ter_tsk

:mv a, #2scall ter_tsk ; Forcibly terminates the task bnz error ; indicated by task ID "2".

:

141


142

4.3.4 chg_pri (Change Task Priority)

This system call changes the task priority level.-27 Task section Task independent section


Format: ER ercd = chg_pri(ID tskid, TPRI tskpri);

Input parameters: tskid Task ID (1 to maximum task ID)TSK_SELF (0) Own task

tskpri Task priority (1 to minimum task priority level) TPRI_INI (0) Initial priority level



Input parameters: AL Task ID (1 to maximum task ID) TSK_SELF (0) Own task

AH Task priority (1 to minimum task priority level) TPRI_INI (0) Initial priority level

System call: scall chg_pri



<Error codes>

<Dispatch causes>

If the priority level of the target task was changed so that it is higher than the priority level of the task that issued the system call, the target task is dispatched.

If the priority level of the task that issued the system call was lowered below that of the task with the next highest political ranking, the task with the next highest political ranking is dispatched.


E_OKE_RSIDE_TPRIE_IDOVRE_DMT

0-23-38-35-53

Normal end "0" was specified for a task ID in the non-task section Incorrect task priority level ID number too large Task is in DORMANT state


<Description>

This system call changes the current priority level of the specified task to the specified priority level.

If the same priority level is specified for the new priority level as the current priority level, the execution ranking is not changed. If a different priority level is specified, the task is added to the end of the ready queue for the new priority level.

"TSK_SELF" or a task ID from 1 to the maximum task ID can be specified for the task ID. If "TSK_SELF" is specified, the priority level of the current task is the one that is changed. If this is specified in the non-task section, "E_RSID" is returned. If this command is issued for a task in the DORMANT state, "E_DMT" is returned. If an ID that exceeds the maximum number of tasks as specified in the Configurator is specified for the task ID, "E_IDOVR" is returned.

For the task priority level, specify either "TPRI_INI" or a priority level from 1 to the minimum task priority level.

If "TPRI_INI" is specified, the initial task priority level as specified in the task generation information is set. If a value outside the range from 1 to the minimum priority level is specified, "E_TPRI" is returned.

The new (changed) priority level set by this system call is valid until the task is terminated. Once the task enters the DORMANT state, the previous priority level becomes invalid. The next time the task is executed, the initial task priority level as specified in the task generation information is set.

If the priority level of another task is raised above the priority level of the current task, the task that was specified enters the RUN state and the current task moves to the READY state.

If the priority level of the current task is decreased, it may be preempted (i.e., the execution authority may be passed to a READY task with a higher priority level).

<Examples>



#include "scdef.h"

TASK task1(){

: chg_pri(2, 3) ; /∗ Sets the priority level of the task indicated ∗/

/∗ by task ID "2" to priority level "3" ∗/ :

}

#include scdef.inc.IMPORT chg_pri :mv a, #TPRI_INI ; New task priority levelmv a, #TSK_SELF ; ID of task to be changed scall chg_pri ; Issuance of system call bnz error ; Error when ZF = 0 :

143


144

4.3.5 rot_rdq (Rotate Ready Queue)

This system call rotates the task ready queue.-28 Task section Task independent section


Format: ER ercd = rot_rdq(TPRI tskpri);

Input parameters: tskpri Priority level of ready queue to be rotated TPRI_RUN (0) Highest priority ready queue containing READY tasks



Input parameters: AL Priority level of ready queue to be rotated TPRI_RUN (0) Highest priority ready queue containing READY tasks

System call: scall rot_rdq



<Error codes>

<Dispatch causes>

If the priority level that was specified is the same as that of the task that issued the system call, and there are other tasks with that priority level, the task that is next in the priority ranking is dispatched.

<Description>

This system call rotates the ready queue for the specified priority level. If "TPRI_RUN" was specified for the priority level, the ready queue corresponding to the priority level of the task in the RUN state (the current task) is rotated.

For the task priority level, specify either "TPRI_INI" or a priority level from 1 to the minimum task priority level. If a value outside this range is specified, "E_TPRI" is returned.

When a ready queue is rotated, the task at the head of the ready queue is moved to the end of the ready queue. Round robin scheduling is possible by issuing "rot_rdq" at a fixed interval.

The "rot_rdq" system call can be issued from the task section with "TPRI_RUN" specified for the priority level for the purpose of ridding the current task of the execution authority, since "TPRI_RUN" specifies the ready queue for the priority level of the current task.

If there are no tasks in the ready queue for the specified priority level, no processing is performed and the system call terminates normally.


E_OKE_TPRI

0-38

Normal end Incorrect task priority level


<Examples>



#include "scdef.h"#define ROT_RDQ_PRI 1TASK func(){

:rot_rdq(ROT_RDQ_PRI) ; /∗ Rotates ready queue ∗/

:}

#include scdef.incROT_RDQ_PRI.equ 1

: mv a, #ROT_RDQ_PRI ; Priority level of ready queue to be rotated scall rot_rdq ; Issuance of system call bnz error ; Error when the zero flag (ZF) = 0

:

145


146

4.3.6 get_tid (Get Task Identifier)

This system call gets the ID of the current task.-24 Task section Task independent section


Format: ER ercd = get_tid(ID ∗p_tskid);

Input parameters: p_tskid Pointer to area where task ID is stored

Output parameters: ercd Error code (E_OK: normal)∗p_tskid Current task ID

0: Non-task



System call: scall get_tid

Output parameters: • ZF 1: Normal endAL Current task ID

0: Non-task

<Error codes>

<Dispatch causes>


<Description>

This system call references the ID number of the current task.

If this system call is issued from the task-independent section, "FALSE (0)" is returned in the return parameter "tskid".


E_OK 0 Normal end


<Examples>



#include "scdef.h"ID readid() /∗ Function that returns the task ID ∗/{ ID tskid ;

get_tid(&tskid); return(tskid);}

#include scdef.in:

.IMPORT get_tid:

scall get_tidcbne a, #0, untask ;Task, non-task check

:untask: ;Non-task check

:

147


148

4.3.7 tsk_sts (Get Task Status)

This system call references the status of the specified task.-20 Task section Task independent section


Format: ER ercd = tsk_sts(T_TSKS ∗pk_tsks, ID tskid);typedef struct t_tsks {

TSTA tskstat ;TPRI tskpri ;

} T_TSKS ;

Note: The structure "T_TSKS" is defined by "scdef.h".

Input parameters: pk_tsks Pointer for the area where the task information is stored tskid Task ID

TSK_SELF (0): Current task specification

Output parameters: ercd Error code (E_OK: normal) pk_tsks->tskstat Task status code pk_tsks->tskpri Task priority level Task status code =TTS_RUN (H’01) : RUN state

= TTS_RDY (H’02) : READY state = TTS_WAI (H’04) : WAIT state = TTS_SUS (H’08) : SUSPEND state = TTS_WAS (H’0c) : WAIT-SUSPEND state = TTS_DMT (H’10) : DORMANT state


Input parameters: ADB:AH Starting address of area (2 bytes) where the task information is stored

AL Task ID TSK_SELF (0): Current task specification

System call: scall tsk_sts


Task status code = TTS_RUN (H'01) : RUN state = TTS_RDY (H'02) : READY state = TTS_WAI (H'04) : WAIT state = TTS_SUS (H'08) : SUSPEND state = TTS_WAS (H'0c) : WAIT-SUSPEND state= TTS_DMT (H'10) : DORMANT state

• ZF 0: Error end AL Error code

tskstattskpri

Task status codeTask priority level

ADB:AH+0+1+2


<Error codes>

<Dispatch causes>


<Description>

This system call returns information on the status of the specified task. If "TSK_SELF (0)" was specified for the task ID, information on the current task is returned. If "TSK_SELF (0)" was specified in the non-task section, "E_RSID" is returned.


The task information includes the task priority level and the task status.

<Examples>




E_OKE_RSIDE_IDOVR

0-23-35

Normal end "TSK_SELF" specified in the non-task section ID number is too large

#include "scdef.h"

gettaskcondition(tskid) ID tskid ;{ T_TSKS tasksts ;

if(tsk_sts(&tasksts, tskid) == E_OK) { return(tasksts. tskstat) ; }}

#include scdef.inc.IMPORT tsk_sts

:tasksts: .RES.B 2 :

mov a,#BNKSYM(tasksts) ; Sets the area where mov adb,a ; the task informationmovw a,#tasksts ; is to be stored Task mv a,#TASK_ID ; Task ID specificationscall tsk_stsbnz error

:

149



There are seven task-dependent synchronization function system calls.• sus_tsk • wai_tsk • rsm_tsk • wup_tsk • frsm_tsk • can_wup• slp_tsk

� Task-Dependent Synchronization Function System Calls

There are seven task-dependent synchronization function system calls.

� sus_tsk (Suspend Task)

This system call moves another task into the SUSPEND state.

� rsm_tsk (Resume Task)

This system call resumes a task that was in the SUSPEND state.

� frsm_tsk (Force Resume Task)

This system call forcibly resumes a task that was in the SUSPEND state.

� slp_tsk (Sleep Task)

This system call moves the current task into the WAIT state.

� wai_tsk (Wait for Wakeup Task)

This system call moves the current task into the WAIT state for a fixed period of time.

� wup_tsk (Wakeup Task)

This system call wakes up a task in the WAIT state.

� can_wup (Cancel Wakeup Task)

This system call cancels all task wakeup requests.

150

151

MEMO


152

4.4.1 sus_tsk (Suspend Task)

This system call moves another task into the SUSPEND state.-33 Task section Task independent section


Format: ER ercd = sus_tsk(ID tskid);





System call: scall sus_tsk


• ZF 0: Error occurred AL Error code

<Error codes>

<Dispatch causes>


<Description>

This system call interrupts execution of the specified task and puts it into the SUSPEND state. The task can be released from the SUSPEND state by issuing either "rsm_tsk" or "frsm_tsk".

Specify a value from 1 to the maximum task ID for the task ID. If the specified task is in the DORMANT state, "E_DMT" is returned.

If the current task was specified, "E_SELF" is returned. If "TSK_SELF = 0" was specified in the non-task section, "E_RSID" is returned.

The "sus_tsk" system call stores up to 255 suspend requests for a single task. If the queue exceeds 255 when this system call is issued, "E_QOVR" is returned.

If the "sus_tsk" system call is issued for a task in the WAIT state, the task enters the WAIT-SUSPEND state. In addition to "slp_tsk" and "wai_tsk", other system calls that put a task into the WAIT state include system calls that make the task wait for resources such as in the synchronization, communication and memorypool management functions.


E_OKE_RSIDE_IDOVRE_SELFE_DMTE_QOVR

0-23-35-49-53-74

Normal end "TSK_SELF" was specified for a task ID in the non-task section ID number too large Current task cannot be specified Specified task is in DORMANT state Suspend count overflow


<Examples>



#include "scdef.h"#define SUSPEND_TASK_ID 2TASK task1(){

: sus_tsk(SUSPEND_TASK_ID) ;

:}

#include scdef.inc.IMPORT sus_tsk

SUSPEND_TASK_ID .equ 2 :

mv a,#SUSPEND_TASK_ID ; Task ID scall sus_tskbnz error :

153


154

4.4.2 rsm_tsk (Resume Task)

This system call resumes a task that was in the SUSPEND state.-35 Task section Task independent section


Format: ER ercd = rsm_tsk(ID tskid);





System call: scall rsm_tsk



<Error codes>

<Dispatch causes>

If a task with a higher priority level than the task that issued this system call is released from the SUSPEND state, the task that was released from the SUSPEND state is dispatched.

<Description>

This system call resumes a specified task that is in the SUSPEND state. Specify a value from 1 to the maximum task ID for the task ID. If the specified task is in the DORMANT state, "E_DMT" is returned. If the specified task is not in the SUSPEND state, "E_NOSUS" is returned. If the current task is specified, "E_SELF" is returned.

If "TSK_SELF" is specified for the ID in the non-task section, "E_RSID" is returned.


Up to 255 suspend requests issued by means of the "sus_tsk" system call can be stored for a single task. If the number of requests in the suspend queue is two or more when this system call is issued, the length of the queue is reduced by one and the SUSPEND state is not released.


E_OKE_RSIDE_IDOVRE_SELFE_DMTE_NOSUS

0-23-35-49-53-56

Normal end "TSK_SELF" was specified for a task ID in the non-task section ID number too large Current task cannot be specified Specified task is in DORMANT state Specified task is not in SUSPEND state


If the specified task is in the WAIT-SUSPEND state and the length of the suspend request queue is "1," the specified task enters the WAIT state.

If the specified task is in the SUSPEND state and the length of the suspend request queue is "1," the specified task enters the READY state. If the priority level of the specified task is higher than that of the current task, the execution authority is passed to the specified task.

<Examples>



#include "scdef.h"#define RESUME_TASK 2TASK task1() { : rsm_tsk(RESUME_TASK) ; :}

#include scdef.inc .IMPORT rsm_tskRESUME_TASK .equ 2 : mv a,#RESUME_TASK ; Task ID scall rsm_tsk bnz error :

155


156

4.4.3 frsm_tsk (Force Resume Task)

This system call forcibly resumes a task that was in the SUSPEND state.-36 Task section Task independent section


Format: ER ercd = frsm_tsk(ID tskid);





System call: scall frsm_tsk


• ZF 0: Error occurredAL Error code

<Error codes>

<Dispatch causes>

If a task with a higher priority level than the task that issued this system call is released from the SUSPEND state, the task that was released from the SUSPEND state is dispatched.


E_OKE_RSIDE_IDOVRE_SELFE_DMTE_NOSUS

0-23-35-49-53-56

Normal end "TSK_SELF" was specified for a task ID in the non-task section ID number too large Current task cannot be specified Specified task is in DORMANT state Specified task is not in SUSPEND state


<Description>

This system call forcibly resumes a specified task that is in the SUSPEND state. Specify a value from 1 to the maximum task ID for the task ID. If the specified task is in the DORMANT state, "E_DMT" is returned. If the specified task is not in the SUSPEND state, "E_NOSUS" is returned. If the current task is specified, "E_SELF" is returned.

If "TSK_SELF" is specified for the ID in the non-task section, "E_RSID" is returned.


This system call releases the specified task from the SUSPEND state, regardless of the length of the suspend request queue.

If the specified task is in the WAIT-SUSPEND state, the specified task enters the WAIT state.

If the specified task is in the SUSPEND state, the specified task enters the READY state. If the priority level of the specified task is higher than that of the current task, the execution authority is passed to the specified task.

<Examples>



#include "scdef.h"#defineRESUME_TASK_ID 2TASK task1() {

: frsm_tsk(RESUME_TASK_ID) ;

:}

#include scdef.inc.IMPORT frsm_tsk

RESUME_TASK_ID .equ 2 :

mv a,#RESUME_TASK_ID ; Task ID scall frsm_tskbnz error

:

157


158

4.4.4 slp_tsk (Sleep Task)

This system call moves the current task into the WAIT state.-38 Task section Task independent section ×


Format: ER ercd = slp_tsk(void);





System call: scall slp_tsk



<Error codes>

<Dispatch causes>

When the task that issued the system call enters the WAIT state, the task that is next in the priority ranking is dispatched.

<Description>

This system call moves the current task from the RUN state to the WAIT state. The WAIT state is released when there is a wakeup request for the task from a source other than the task. Task wakeup requests are made through "wup_tsk" and "ret_wup".

The "slp_tsk" system call cannot be issued from the non-task section. If this system call is issued from the non-task section, "E_CTX" is returned.

If the wakeup request count for the current task is not "0", then this system call reduces the wakeup request count by one without moving the task into the WAIT state. If the wakeup request count for the current task is "0", the task enters the WAIT state. The wakeup request count is increased by "wup_tsk" and "ret_wup".


E_OKE_CTX

0-69

Normal end Context error (issued from the non-task section)


<Examples>



#include "scdef.h"

TASK task1(){ slp_tsk() ; /∗ To WAIT state ∗/

:}

#pragma register(0)#define TASK1_ID 1__interrupt INTHDR interrupt_handler(){ wup_tsk(TASK1_ID) ; ret_int ( );}#pragma noregister

#include scdef.inc .IMPORT slp_tsk, wup_tskTASK1_ID .equ 1 :task1: scall slp_tsk ; To WAIT state bnz error :interrupt_handler: mov rp, #0 mv a, #TASK1_ID scall wup_tsk scall ret_int :

159


160

4.4.5 wai_tsk (Wait for Wakeup Task)

This system call moves the current task into the WAIT state for a fixed period of time.-37 Task section Task independent section ×


Format: ER ercd = wai_tsk(TMO tmout);

Input parameters: tmout Time-out count (0 to 65,535)



Input parameters: AL Time-out count (0 to 65,535)

System call: scall wai_tsk



<Error codes>

<Dispatch causes>

When the task that issued this system call enters the WAIT state, the task with the next highest priority ranking is dispatched.

<Description>

This system call waits for a wakeup request for the current task until the specified time elapses. When "wai_tsk" is issued, the current task moves to the RUN state or the WAIT state. When the specified time elapses, "E_TMOUT" is returned. The task can be woken up by either "wup_tsk" or "ret_wup".

The time-out count counts the system clock cycles. The actual length of time is the product of the system clock cycle multiplied by the time-out count.


E_OKE_TNOSPTE_CTXE_TMOUT

0-19-69-85

Normal end Timer function not supported Context error (issued from non-task section) Time-out


The time-out count can be specified over a range from 0 to 65,535. If "0" is specified, control returns immediately to the source of the call, without the task entering the WAIT state.

This system call cannot be used in the non-task section. If this system call is executed from the non-task section, "E_CTX" is returned. If "wai_tsk" is not included in the Configurator, "wai_tsk" cannot be used. In this situation, if "wai_tsk" is called, "E_TNOSPT" is returned.

If the current task’s wakeup request count is not "0" when "wai_tsk" is called, the wakeup request count is reduced by "1" and the task does not enter the WAIT state.

If the current task's wakeup request count is "0", the task enters the WAIT state.

<Examples>



#include "scdef.h"#define WAIT_TIME 100TASK task1(){

wai_tsk(WAIT_TIME) ; : /∗ Enter WAIT state for a count of up to 100 ∗/

}

#pragma register(0)__interrupt INTHDR int_hdr(){

wup_tsk(1); /∗ Wake up task 1 ∗/ ret_int( );}#pragma noregister

#include scdef.inc.IMPORT wai_tsk, wup_tsk

WAIT_TIME .equ 100:

task1:mvw a, #WAIT_TIME ; The time-out periodscall wai_tsk ; To WAIT state bnz error

:int_hnd:

mov rp, #0mv a, #1scall wup_tsk ; Wake up task 1scall ret_int

:

161


162

4.4.6 wup_tsk (Wakeup Task)

This system call wakes up a task that was put in the WAIT state by executing either the "slp_tsk" system call or the "wai_tsk" system call.

-39 Task section Task independent section


Format: ER ercd = wup_tsk(ID tskid);




Input parameters: AL Task ID

System call: scall wup_tsk



<Error codes>

<Dispatch causes>

If a task with a higher priority than the task that issued the system call is woken up, the task that was woken up is dispatched.



0-23-35-49-53-74

Normal end "TSK_SELF" was specified for a task ID in the non-task section ID number too large Current task cannot be specified Specified task is in DORMANT state Wakeup request count overflow


<Explanation>

This system call issues a wakeup request for a task that was put in the WAIT state by either the "slp_tsk" system call or the "wai_tsk" system call. The task that receives the wakeup request enters the READY state. If the priority level of the task that received the wakeup request is higher than that of the task that issued the "wup_tsk" system call, execution authority is passed to the task that received the wakeup request.

The current task cannot be specified. If it is specified, "E_SELF" is returned.

If "TSK_SELF" is specified in the non-task section, "E_RSID" is returned.


If the wakeup request is issued to a task in the DORMANT state, "E_DMT" is returned.

If the specified task is not in the WAIT state due to "slp_tsk" or "wai_tsk", the task wakeup request goes into the wakeup request queue.

If the number of task wakeup requests in the queue exceeds 255, "E_QOVR" is returned.

If the wakeup request was issued to a task in the WAIT-SUSPEND state, the task moves the SUSPEND state.

<Examples>



#include "scdef.h"

TASK task1(){

slp_tsk() ; /∗ To WAIT state ∗/:

}TASK task2(){

wup_tsk(1) ; /∗ Wake up task 1 ∗/ext_tsk() ;

}

#include scdef.inc.IMPORT slp_tsk, wup_tsk

:task1:

scall slp_tsk ; To WAIT statebnz error

:task2:

mv a, #1scall wup_tsk ; Wake up task 1

:

163


164

4.4.7 can_wup (Cancel Wakeup Task)

This system call cancels all task wakeup requests.-40 Task section Task independent section


Format: ER ercd = can_wup(INT ∗p_wupcnt, ID tskid);

Input parameters: p_wupcnt Pointer for area where queued wakeup request count is stored

tskid Task ID (1 to maximum task ID) TSK_SELF (0) Current task specification

Output parameters: ercd Error code (E_OK: normal) ∗p_wupcnt Queued wakeup request count


Input parameters: AL Task ID (1 to maximum task ID) TSK_SELF (0) Current task specification

System call: scall can_wup

Output parameters: • ZF 1: Normal endAL Queued wakeup request count


<Error codes>

<Dispatch causes>



E_OKE_RSIDE_IDOVRE_DMT

0-23-35-53

Normal end "TSK_SELF" was specified for a task ID in the non-task section ID number too large Specified task is in DORMANT state


<Description>

This system call cancels all queued task wakeup requests for the specified task, and returns the number of wakeup requests that were cancelled.

Specify either "TSK_SELF" or a value from 1 to the maximum task ID for the task ID. If "TSK_SELF" was specified, the task wakeup requests for the current task are cancelled. If the specified task is in the DORMANT state, "E_DMT" is returned. If "TSK_SELF" was specified for the task ID in the non-task section, "E_RSID" is returned.


When performing processing that wakes up a task cyclically, this system call can be used to determine whether or not processing was completed within a certain period of time (by determining whether or not the next wakeup request was generated before "slp_tsk" was executed in response to the previous wakeup request).

<Examples>



#include "scdef.h"

TASK task1(){ INT ∗wupcnt ;

: can_wup(wupcnt, 2) ;

:}

#include scdef.inc.IMPORT can_wup

:mv a, #2 ; Task IDscall can_wupbnz error

:

165



There are fifteen different synchronization/communication function system calls.• sig_sem • pol_flg • wai_sem • cpol_flg • preq_sem • flg_sts • sem_sts • snd_msg • set_flg • rcv_msg • clr_flg • prcv_msg • wai_flg • mbx_sts• cwai_flg

� Synchronization/Communication Function System Calls

There are fifteen different synchronization/communication function system calls.

� sig_sem (Signal Semaphore)

This system call performs a signal operation (V instruction) for a semaphore.

� wai_sem (Wait on Semaphore)

This system call performs a wait operation (P instruction) for a semaphore.

� preq_sem (Poll and Request Semaphore)

This system call performs a wait operation (P instruction with polling) for a semaphore.

� sem_sts (Get Semaphore Status)

This system call references the status of a semaphore.

� set_flg (Set Eventflag)

This system call sets a 1-bit/16-bit eventflag.

� clr_flg (Clear Eventflag)

This system call clears a 1-bit/16-bit eventflag.

� wai_flg (Wait Eventflag)

This system call waits for a 1-bit/16-bit eventflag.

� cwai_flg (Wait and Clear Eventflag)

This system call waits for a 1-bit eventflag.

� pol_flg (Poll Eventflag)

This system call gets (via polling) a 1-bit/16-bit eventflag.

� cpol_flg (Poll and Clear Eventflag)

This system call gets (via polling) a 1-bit eventflag.

� flg_sts (Get Eventflag Status)

This system call references the status of a 1-bit/16-bit eventflag.

� snd_msg (Send Message to Mailbox)

166


This system call sends a message to a mailbox.

� rcv_msg (Receive Message from Mailbox)

This system call receives a message from a mailbox.

� prcv_msg (Poll and Receive Message from Mailbox)

This system call receives (via polling) a message from a mailbox.

� mbx_sts (Mailbox Status)

This system call references the mailbox status.

167


168

4.5.1 sig_sem (Signal Semaphore)

This system call performs a signal operation (V instruction) for a semaphore.-55 Task section Task independent section


Format: ER ercd = sig_sem(ID semid);

Input parameters: semid Semaphore ID



Input parameters: AL Semaphore ID

System call: scall sig_sem



<Error codes>

<Dispatch causes>

If a task with a priority level higher than the task that issued this system call is released from the semaphore wait state, the task that was released from the WAIT state is dispatched.

<Description>

This system call generates one count for the specified semaphore. The semaphore count range is from 0 to 255.

If there is a task waiting for the specified semaphore, the first task in the semaphore wait queue enters the READY state. In this case, the count for the specified semaphore effectively remains unchanged.

If there are no tasks in the WAIT state, the count for the specified semaphore is increased by "1".


E_OKE_NOSPTE_RSIDE_IDOVRE_QOVR

0-17-23-35-74

Normal end Semaphore not supported ID number is "0" ID number too large Semaphore count overflow


Tasks enter the semaphore wait queue in the sequence in which they entered the WAIT state. In other words, the task that entered the WAIT state first is the task that is woken up.

If the task that is woken up is in the READY state, it is possible that the task that issued "sig_sem" will be preempted as a result of scheduling.

If the semaphore count exceeds 255 as a result of this system call being issued, "E_QOVR" is returned.

If the semaphore ID is specified as "0", "E_RSID" is returned.

If a value that exceeds the maximum semaphore ID as specified in the Configurator is specified for the semaphore ID, or if a negative value is specified for the semaphore ID, "E_IDOVR" is returned.

If the semaphore is not registered in the Configurator, "E_NOSPT" is returned.

<Examples>



#include "scdef.h"#define SEM_ID 1TASK task1(){ wai_sem(SEM_ID) ;

: /∗ Exclusive processing area ∗/ sig_sem(SEM_ID) ;

:}

TASK task2(){ wai_sem(SEM_ID) ;


:}

#include scdef.inc.IMPORT sig_sem :

SEM_ID .equ 1 :

mv a, #SEM_IDscall sig_sembnz error :

169


170

4.5.2 wai_sem (Wait on Semaphore)

This system call performs a wait operation (P instruction) for a semaphore.-53 Task section Task independent section ×


Format: ER ercd = wai_sem(ID semid);





System call: scall wai_sem



<Error codes>

<Dispatch causes>

If the task that issued this system call enters the semaphore wait state, the task with the next highest priority ranking is dispatched.

<Description>

This system call requests one count from the specified semaphore, and waits until the request is met.

If the count for the specified semaphore is "1" or higher, the count is decremented by "1" and control returns to the source of the call. If the count is "0", the task enters the WAIT state until one count is generated for the semaphore.

A task that enters the WAIT state is added to the end of the semaphore wait queue.

If this system call is issued from the non-task section, "E-CTX" is returned.





E_OKE_NOSPTE_RSIDE_IDOVRE_CTX

0-17-23-35-69

Normal end Semaphore not supported ID number is "0"ID number too large Context error (issued from non-task section)


<Examples>



#include "scdef.h"#define SEM_ID 1TASK task1(){ wai_sem(SEM_ID) ;


:}TASK task2(){ wai_sem(SEM_ID) ;


:}

#include scdef.inc.IMPORT wai_sem

:SEM_ID .equ 1

:mv a, #SEM_IDscall wai_sembnz error

:

171


172

4.5.3 preq_sem (Poll and Request Semaphore)

This system call performs a wait operation (P instruction with polling) for a semaphore.-203 Task section Task independent section


Format: ER ercd = preq_sem(ID semid);





System call: scall preq_sem



<Error codes>

<Dispatch causes>


<Description>

This system call requests one count from the specified semaphore. If the count can not be obtained, the task does not enter the WAIT state; instead, "E_PLFAIL" is returned.





E_OKE_NOSPTE_RSIDE_IDOVRE_PLFAIL

0-17-23-35-89

Normal endSemaphore not supported ID number is "0" ID number too large Count is "0"


<Examples>



#include "scdef.h"#define SEM_ID 1TASK task1(){ if(preq_sem(SEM_ID) == E_OK) {

: }

:}

#include scdef.inc.IMPORT preq_sem

:SEM_ID .equ 1

:mv a, #SEM_IDscall preq_sembnz error

:

173


174

4.5.4 sem_sts (Get Semaphore Status)

This system call references the status of a semaphore.-52 Task section Task independent section


Format: ER ercd =sem_sts(T_SEMS ∗pk_sems, ID semid);typedef struct t_sems { SCNT semcnt ; ID wtskid ;} T_SEMS ;

Note: The structure "T_SEMS" is defined in the header file.

Input parameters: pk_sems Pointer for area where semaphore information is to be stored

semid Semaphore ID

Output parameters: ercd Error code (E_OK: normal)pk_sems->semcnt Current count valuepk_sems->wtskid ID of first task in semaphore waiting queue

0: No waiting tasks (FALSE)


Input parameters: ADB:AH Address of area (four bytes) where semaphoreinformation is stored

AL Semaphore ID

System call: scall sem_sts


0: No waiting tasks (FALSE)• ZF 0: Error end

AL Error code

<Error codes>


E_OKE_NOSPTE_RSIDE_IDOVR

0-17-23-35

Normal end Semaphore not supported ID number is "0" ID number too large

semcntwtskid

Current semaphore count ID of first task in semaphore waiting queue

ADB:AH+0+2+4


<Dispatch causes>


<Description>

This system call returns information on the specified semaphore. The semaphore information includes the current semaphore count and the ID of the task at the head of the queue for the specified semaphore.

Tasks are added to the semaphore wait queue in the order in which they entered the WAIT state; "sem_sts" returns the ID of the first task in this queue.

If there are no tasks waiting for the specified semaphore, "FALSE (0)" is returned.




<Examples>



#include "scdef.h"#define SEMAPHORE_ID 1TASK task1(){ T_SEMS sems ; ER ercd ;

ercd = sem_sts(&sems, SEMAPHORE_ID) ;:

}

#include scdef.inc.IMPORT sem_sts

SEMAPHORE_ID .equ 1.SECTION T_DATA, DATA, ALIGN=2

sems .RES.H 2

.SECTION T_CODE, CODE, ALIGN=2 ; Sets area where themov a, #BNKSYM (sems) ; semaphore informationmov adb, a ; is to be storedmovw a, #SEMAPHORE_ID ; Semaphore ID scall sem_sts specification bnz error

175


176

4.5.5 set_flg (Set Eventflag)

This system call sets a 1-bit eventflag.-48 Task section Task independent section


Format: ER ercd = set_flg(ID flgid);

Input parameters: flgid 1-bit eventflag ID



Input parameters: AL 1-bit eventflag ID

System call: scall set_flg



<Error codes>

<Dispatch causes>

When a task with a higher priority level than the task that issued the system call is released from waiting for an eventflag, the task that was released from the WAIT state is dispatched.

<Description>

This system call sets the specified 1-bit eventflag to "1" and moves a task waiting for that 1-bit eventflag into the READY state.

Tasks waiting for a 1-bit eventflag are added to the queue in the order in which they requested the 1-bit eventflag. When "set_flg" is issued, the task in the queue are woken up, starting from the front of the queue. However, if there are any tasks in the queue that are waiting as a result of "cwai_flg" being issued, the 1-bit eventflag is regarded as having been cleared at that point, and any subsequent tasks in the queue are not woken up. When there are tasks that have been woken up and are in the READY state, it is possible that, as a result of scheduling, the task that issued "set_flg" may be preempted (i.e., execution authority is passed to the task that was released from waiting for the flag, and the current task enters the READY state).



0-17-23-35

Normal end 1-bit eventflag not supported ID number is "0" ID number too large


Tasks that are released from waiting for the flag but that do not have a suspend count of "0" (i.e., tasks that were in the WAIT-SUSPEND state), enter the SUSPEND state.

If the eventflag is not registered in the Configurator, "E_NOSPT" is returned.

If the eventflag ID is specified as "0", "E_RSID" is returned.

If a value that exceeds the maximum eventflag ID as specified in the Configurator is specified for the eventflag ID, or if a negative value is specified for the eventflag ID, "E_IDOVR" is returned.

This system call can be used when 1-bit eventflags are selected in the Configurator.

<Examples>



#include "scdef.h"#define EVFLG_ID 1

TASK task1(){ set_flg(EVFLG_ID) ; /∗ Set eventflag ∗/

:}

#include scdef.inc.IMPORT set_flg

EVFLG_ID .equ 1:

mv a, #EVFLG_ID ; ID of eventflag to be setscall set_flgbnz error

:

177


178

4.5.6 clr_flg (Clear Eventflag)

This system call clears a 1-bit eventflag.-47 Task section Task independent section


Format: ER ercd = clr_flg(ID flgid);





System call: scall clr_flg



<Error codes>

<Dispatch causes>


<Description>

This system call clears the specified 1-bit eventflag to "0".







0-17-23-35

Normal end1-bit eventflag not supported ID number is "0" ID number too large


<Examples>




TASK task1(){ clr_flg(EVFLG_ID) ; /∗ Clear eventflag ∗/

:}

#include scdef.inc.IMPORT clr_flg

EVFLG_ID .equ 1:

mv a, #EVFLG_ID ; Eventflag ID to be clearedscall clr_flgbnz error

:

179


180

4.5.7 wai_flg (Wait Eventflag)/cwai_flg (Wait and Clear Eventflag)

These system calls wait for a 1-bit eventflag to be set.-46/-45 Task section Task independent section ×


Format: ER ercd = wai_flg(ID flgid); Flag not clearedER ercd = cwai_flg(ID flgid); Flag cleared





System call: scall wai_flg Flag not clearedscall cwai_flg Flag cleared



<Error codes>

<Dispatch causes>

If the task that issued one of these system calls begins waiting for an eventflag, the task with the next highest priority is dispatched.

<Description>

These system calls cause the task to wait until the specified 1-bit eventflag is set. In the case of "wai_flg", the state of the 1-bit eventflag does not change after it is set, while in the case of "cwai_flg", the 1-bit eventflag is cleared once it has been set.



0-17-23-35-69

Normal end 1-bit eventflag not supported ID number is "0" ID number too large Context error (issued from a non-task section)


If the specified 1-bit eventflag is not in the set state, the task that issued "wai_flg" or "cwai_flg" enters the wait state. The tasks waiting for a 1-bit eventflag are woken up by "set_flg" being issued. However, if there is a task in the queue that is waiting for a 1-bit eventflag because it issued "cwai_flg", the 1-bit eventflag is cleared after that task is woken up, with the result that subsequent tasks in the 1-bit eventflag waiting queue are not woken up.

If the specified 1-bit eventflag is already set, the task does not enter the WAIT state, and control returns immediately to the task that was the source of the call.

The "wai_tsk" and "cwai_tsk" system calls cannot be issued from the non-task section. If they are issued, "E_CTX" is returned.




These system calls can be used when 1-bit eventflags are selected in the Configurator.

<Examples>



#includeb "scdef.h"#define EVENTFLAG_ID 1

TASK task1(){ wai_flg(EVENTFLAG_ID) ; /∗ Wait for the eventflag with ID 1 ∗/

:}

#include scdef.inc.IMPORT wai_flg

EVENTFLAG_ID .equ 1 :mv a, #EVENTFLAG_ID ; Eventflag IDscall wai_flgbnz error :

181


182

4.5.8 pol_flg (Poll Eventflag)/cpol_flg (Poll and Clear Eventflag)

These system calls get the state of a 1-bit eventflag.-202/-201 Task section Task independent section


Format: ER ercd = pol_flg(ID flgid); Flag not clearedER ercd = cpol_flg(ID flgid); Flag cleared





System call: scall pol_flg Flag not clearedscall cpol_flg Flag cleared



<Error codes>

<Dispatch causes>

These system calls do not create a dispatching situation.

<Description>

These system calls get the state of the specified 1-bit eventflag. In the case of "pol_flg", the state of the 1-bit eventflag does not change after the 1-bit eventflag is gotten, while in the case of "cpol_flg", the 1-bit eventflag is cleared once the 1-bit eventflag has been gotten.

For both "pol_flg" and "cpol_flg", "E_OK" is returned if the 1-bit eventflag is in the set state, and "E_PLFAIL" is returned if the flag is in the cleared state.




These system calls can be used when 1-bit eventflags are selected in the Configurator.



0-17-23-35-89

Normal end 1-bit eventflag not supported ID number is "0" ID number too large 1-bit eventflag not set


<Examples>




TASK task1(){ if (pol_flg(EVFLG_ID) == E_OK) {

: }

:}

#include scdef.inc.IMPORT pol_flg

EVFLG_ID .equ 1:

mv a, #EVFLG_ID ; Flag IDscall pol_flgbz yes_set

:

183


184

4.5.9 flg_sts (Get Eventflag Status)

This system call references the status of a 1-bit eventflag.-44 Task section Task independent section


Format: ER ercd = flg_sts(T_FLGS ∗pk_flgs, ID flgid);typedef struct t_flgs {

FPTN flgptn ;ID wtskid ;

} T_FLGS ;

Note: The structure "T_FLGS" is defined in the header file.

Input parameters: pk_flgs Pointer for area where 1-bit eventflag information is stored

flgid 1-bit eventflag ID

Output parameters: ercd Error code (E_OK: normal)pk_flgs->flgptn 1-bit eventflag state

0: Cleared 1: Set

pk_flgs->wtskid ID of first task in 1-bit eventflag waiting queue FALSE (0): No waiting tasks


Input parameters: ADB:AH Address of area (four bytes) where 1-bit eventflag information is stored

AL 1-bit eventflag ID

System call: scall flg_sts



flgptn

wtskid

1-bit eventflag state

ID of first task in semaphore waiting queue

ADB:AH+0

+2

+4

0: Cleared 1: Set



<Error codes>

<Dispatch causes>


<Description>

This system call returns current information on the specified eventflag. The eventflag information includes the state (set/cleared) of the specified eventflag and the ID of the first task in the queue corresponding to the specified eventflag.

For the eventflag state information, "0" is returned if the eventflag is in the cleared state, and "1" is returned if the flag is in the set state.

Tasks are added to the eventflag wait queue in the order in which they entered the WAIT state; "flg_sts" returns the ID of the first task in this queue. If there are no tasks waiting for the specified eventflag, "FALSE (0)" is returned.







0-17-23-35

Normal end Eventflag not supported ID number is "0" ID number too large

185


186

<Examples>



#include "scdef.h"#define EVFLG_ID 1TASK task1(){ T_FLGS flgs ; ER ercd ;

: ercd = flg_sts(&flgs, EVFLG_ID) ;

:}

#include scdef.inc.IMPORT flg_sts

EVFLG_ID .equ 1.SECTION T_DATA, DATA, ALIGN=2

flgs .RES.H 2

.SECTION T_CODE, CODE, ALIGN=2 :mov a, #BNKSYM (flgs) ; Sets area where themov adb, a ; eventflag informationmovw a, #flgs ; is to be stored mv a, #EVFLG_ID Eventflag ID specificationscall flg_stsbnz error

:

187

MEMO


188

4.5.10 set_flg (Set Eventflag)

This system call sets a 16-bit eventflag as the logical sum of the eventflag bit pattern and "setptn".



Format: ER ercd = set_flg(ID flgid, UINT setptn);

Input parameters: flgid 16-bit eventflag IDsetptn Bit pattern to be set



Input parameters: AH Bit pattern to be setAL 16-bit eventflag ID

System call: scall set_flg



<Error codes>

<Dispatch causes>

When a task with a higher priority level than the task that issued the system call is released from waiting for an eventflag, the task that was released from the WAIT state is dispatched.



0-17-23-35



<Description>

This system call sets the bit pattern for the specified 16-bit eventflag ID. Set the desired bit pattern, represented with ones, in "setptn". Tasks waiting for the resulting flag bit pattern are released from the WAIT state in sequence, starting from the head of the queue. In this situation, bits represented by "0" in "setptn" are not changed. If there is a task in the queue that is waiting due to the "wai_flg" system call with the clear specification, the bit pattern of the 16-bit eventflag is cleared when that task is released by the "set_flg" system call, so subsequent tasks in the queue are not released. If there are any tasks that were released from waiting and entered the READY state, it is possible that, as a result of scheduling, the task that issued "set_flg" may be preempted (i.e., execution authority is passed to the task that was released from waiting for the flag, and the current task enters the READY state).

Tasks that are released from waiting for the flag but that do not have a suspend count of "0" (i.e., tasks that were in the WAIT-SUSPEND state), enter the SUSPEND state, not the READY state.





<Examples>



#include "scdef.h":

#define SETPTN 0x0F0F ;#define EVFLG_ID 1 ;TASK task1(){ : set_flg(EVFLG_ID, SETPTN) :}

#include scdef.inc.IMPORT set_flg

SETPTN .equ h’0F0FEVFLG_ID .equ 1

:movw a, #SETPTNmv a, #EVFLG_ID ; Flag ID scall set_flgbnz error

:

189


190

4.5.11 clr_flg (Clear Eventflag)

This system call clears a 16-bit eventflag.-47 Task section Task independent section


Format: ER ercd = clr_flg(ID flgid, UINT clrptn);

Input parameters: flgid 16-bit eventflag IDclrptn Bit pattern to be cleared



Input parameters: AH Bit pattern to be clearedAL 16-bit eventflag ID

System call: scall clr_flg



<Error codes>

<Dispatch causes>


<Description>

This system call clears the bit pattern for the specified 16-bit eventflag ID. Set the bit pattern to be cleared, represented in zeroes, in "clrptn". In this situation, bits represented by "1" in "clrptn" are not changed.







0-17-23-35



<Examples>



#include "scdef.h"#define EVFLG_ID 1 ;

TASK task1(){ : clr_flg(EVFLG_ID, 0xF0FF) ; :}

#include scdef.inc.IMPORT clr_flg

EVFLG_ID .equ 1:

movw a, #h’F0FF ; Clear patternmv a, #EVFLG_ID ; Flag ID scall clr_flgbnz error

:

191


192

4.5.12 wai_flg (Wait Eventflag)

This system call causes the task to wait until the eventflag conditions based on the wait mode and the wait bit pattern are met.

-46 Task section Task independent section ×


Format: ER ercd = wai_flg(UINT ∗p_flgptn, ID flgid, UINT waiptn, UINT wfmode);

Input parameters: flgid 16-bit eventflag IDwaiptn Wait bit patternwfmode Wait mode: (TWF_ANDW || TWF_ORW) [| TWF_CLR]

TWF_ANDW (0) AND waitTWF_ORW (2) OR wait TWF_CLR (1) Clear specification

Output parameters: ercd Error code (E_OK: normal)∗p_flgptn Flag bit pattern when wait was released


Input parameters:


System call: scall wai_flg

Output parameters: • ZF 1: Normal endAL Flag bit pattern when WAIT state is released


<Error codes>


E_OKE_NOSPTE_RSMDE_RSIDE_PARE_IDOVRE_CTX

0-17-22-23-3335-69

Normal end 16-bit eventflag not supported Illegal wait mode (wfmode) ID number is "0" Wait bit pattern (waiptn) is "0" ID number too large Context error (issued from non-task section)

waiptnwfmode

ADB:AH+0+2+4

Address of area (4 bytes) containing the wait release condition parameters Wait bit pattern Wait mode: (TWF_ANDW || TWF_ORW) [| TWF_CLR] TWF_ANDW (0) AND wait TWF_ORW (2) OR wait TWF_CLR (1) Clear specification


<Dispatch causes>

When the task that issued this system call begins waiting for the eventflag, the task with the next highest priority is dispatched.

<Description>

This system call puts a task into the WAIT state until the wait bit pattern is set in the specified 16-bit eventflag. Either "AND wait" or "OR wait" can be selected for the wait release condition.

If the "clear" specification is added, then after the release of the WAIT state the 16-bit eventflag bit pattern is cleared (to H’0000).

If the flag bit pattern of the specified 16-bit eventflag ID does not match the wait release conditions for the wait bit pattern specified by the "wai_flg" system call, the task that issued "wai_flg" enters the WAIT state.

In order to wake up the tasks in the WAIT state, it is necessary to use the "set_flg" system call to change the bit pattern to one that matches the wait release conditions. However, if one of the tasks is waiting for the 16-bit eventflag with the clear specification, tasks behind that task in the queue waiting for the 16-bit eventflag are not woken up because the 16-bit eventflag is cleared once that task wakes up.

If the flag bit pattern of the specified 16-bit eventflag ID does match the wait release conditions for the wait bit pattern specified by the "wai_flg" system call, the task that issued the call does not enter the WAIT state; instead, control returns immediately to that task.

The "wai_flg" system call cannot be issued from the non-task section. If it is, "E_CTX" is returned.

If "0" is specified for the wait bit pattern, "E_PAR" is returned. Because there are no tasks with a wait bit pattern of "0", if all bits are set by "set_flg," wait release results regardless of the 16-bit eventflag conditions that were being waited for. Therefore, the task at the head of the queue is always released from waiting, regardless of the 16-bit eventflag wait conditions.

If any mode other than one of the reserved modes is specified for the wait mode, "E_RSMD" is returned.

If "TWF_CLR" is specified by itself for the wait mode, it is interpreted as if both "TWF_ANDW" and "TWF_CLR" were specified. Nevertheless, do not write code in which "TWF_CLR" is specified by itself.

If "TWF_ANDW" and "TWF_ORW" are both specified for the wait mode, it is interpreted as if "TWF_ORW" was specified. Nevertheless, do not write code in which "TWF_ANDW" and "TWF_ORW" are both specified.





193


194

<Examples>



#include "scdef.h"#define EVENTFLAG_ID 1 ;#define WAIPTN 0x1234

TASK task1(){ UINT flgptn ;

: wai_flg(&flgptn, EVENTFLAG_ID, WAIPTN,TWF_ANDW) ;

:}

#include scdef.inc.IMPORT wai_flg

EVENTFLAG_ID .equ 1WAIPTN .equ h’1234

:.SECTION T_DATA, DATA, ALIGN=2

flg_para .RES.H 2

.SECTION T_CODE, CODE, ALIGN=2:

mov a, #BNKSYM (flg_para)mov adb, amovw rw2, #flg_paramovw a, #WAIPTNmovw @rw2, amovw a, #TWF_ANDWmovw @(rw2+2), amovw a, rw2mv a, #EVENTFLAG_IDscall wai_flgbnz error

:

195

MEMO


196

4.5.13 pol_flg (Poll Eventflag)

This system call gets the bit pattern when the bit pattern of the 16-bit eventflag satisfies the conditions.



Format: ER ercd = pol_flg(UINT ∗p_flgptn, ID flgid, UINT waiptn, UINT wfmode);

Input parameters: flgid 16-bit eventflag IDwaiptn Wait bit patternwfmode Wait mode: (TWF_ANDW || TWF_ORW) [| TWF_CLR]

TWF_ANDW (0) AND waitTWF_ORW (2) OR wait TWF_CLR (1) Clear specification

Output parameters: ercd Error code (E_OK: normal)∗p_flgptn Flag bit pattern that was gotten


Input parameters:


System call: scall pol_flg

Output parameters: • ZF 1: Normal endAL Flag bit pattern that was gotten


waiptn

wfmode

ADB:AH+0

+2

+4

Address of area (4 bytes) containing the wait release condition parameters Wait bit pattern Wait mode: (TWF_ANDW || TWF_ORW) [| TWF_CLR] TWF_ANDW (0) AND wait TWF_ORW (2) OR wait TWF_CLR (1) Clear specification


<Error codes>

<Dispatch causes>


<Description>

This system gets the state of the specified 16-bit eventflag. Either "AND wait" or "OR wait" can be selected as a condition for getting the status.

If the "clear" specification is added, then after the 16-bit eventflag bit pattern is gotten, it is cleared.

If the flag bit pattern of the specified 16-bit eventflag does match the wait bit pattern condition for getting the status, the flag bit pattern is returned to the task; if pattern does not match, "E_PLFAIL" is returned.

If "0" is specified for the wait bit pattern, "E_PAR" is returned.

If any mode other than one of the reserved modes is specified for the wait mode, "E_RSMD" is returned.

If "TWF_CLR" is specified by itself for the wait mode, it is interpreted as if both "TWF_ANDW" and "TWF_CLR" were specified. Nevertheless, do not write code in which "TWF_CLR" is specified by itself.

If "TWF_ANDW" and "TWF_ORW" are both specified for the wait mode, it is interpreted as if "TWF_ORW" was specified. Nevertheless, do not write code in which "TWF_ANDW" and "TWF_ORW" are both specified.






E_OKE_NOSPTE_RSMDE_RSIDE_PARE_IDOVRE_PLFAIL

0-17-22-23-33-35-89

Normal end 16-bit eventflag not supported Illegal wait mode (wfmode) ID number is "0" Wait bit pattern (waiptn) is "0" ID number too large 16-bit eventflag not set

197


198

<Examples>



#include "scdef.h"#define EVENTFLAG_ID 1 ;#define WAIPTN 0x1234#define WFMODE (TWF_ORW | TWF_CLR)

TASK task1(){ UNIT p_flgptn ;

: if(pol_flg(&p_flgptn, EVENTFLAG_ID, WAIPTN,WFMODE) == E_OK) {

: }

:}

#include scdef.inc.IMPORT pol_flg

EVENTFLAG_ID .equ 1WAIPTN .equ h’1234WFMODE .equ (TWF_ORW |TWF_CLR) ; OR wait with clear specification


flg_para: .RES.H 2


mov a, #BNKSYM(flg_para)mov adb, amovw rw2, #flg_paramovw a, #WAIPTN ; Wait patternmovw @rw2, amovw a, #WFMODE ; OR wait with clear specificationmovw @(rw2+2), amovw a, rw2mv a, #EVENTFLAG_ID ; Eventflag IDscall pol_flg ; System call issuancebz yes_set ; When ZF = 1, set bit

: ; pattern when wait : ; is released into AL

199

MEMO


200

4.5.14 flg_sts (Get Eventflag Status)

This system call references the status of a 16-bit eventflag.-44 Task section Task independent section


Format: ER ercd = flg_sts(T_FLGS ∗pk_flgs, ID flgid);typedef struct t_flgs {

FPTN flgptn ;ID wtskid ;

} T_FLGS ;

Note: The structure "T_FLGS" is defined in the header file.

Input parameters: pk_flgs Pointer for area where 16-bit eventflag information is stored

flgid 16-bit eventflag ID

Output parameters: ercd Error code (E_OK: normal)pk_flgs->flgptn 16-bit eventflag bit pattern pk_flgs->wtskid ID of first task in 16-bit eventflag waiting queue

FALSE (0): No waiting tasks


Input parameters: ADB:AH Address of area (four bytes) where 16-bit eventflag information is stored


System call: scall flg_sts



<Error codes>



0-17-23-35

Normal end Eventflag not supported ID number is "0" ID number too large

flgptn

wtskid

ADB:AH+0

+2

+4

Address where 16-bit eventflag information is stored 16-bit eventflag bit patternID of first task in 16-bit eventflag waiting queue

FALSE (0): No waiting tasks


<Dispatch causes>


<Description>

This system call returns current information on the specified 16-bit eventflag. The 16-bit eventflag information includes the 16-bit eventflag bit pattern and the ID of the first task in the queue corresponding to the specified 16-bit eventflag.

Tasks are added to the 16-bit eventflag wait queue in the order in which they entered the WAIT state; "flg_sts" returns the ID of the first task in this queue. If there are no tasks waiting for the specified 16-bit eventflag, "FALSE (0)" is returned.





<Examples>



#include "scdef.h"#define EVFLG_ID 1TASK task1(){ T_FLGS flgs ; ER ercd ;

: ercd = flg_sts(&flgs, EVFLG_ID) ;

:}

#include scdef.inc.IMPORT flg_sts

EVFLG_ID .equ 1.SECTION T-DATA, DATA, ALIGN=2

flgs .RES.H 2


mov a, #BNKSYM(flgs) ; Sets area where themov adb, a ; eventflag informationmovw a, #flgs ; is to be stored mv a, #EVFLG_ID ; Eventflagscall flg_sts ; ID specificationbnz error

:

201


202

4.5.15 snd_msg (Send Message to Mailbox)

This system call sends a message to a mailbox.-63 Task section Task independent section


Format: ER ercd = snd_msg(ID mbxid, T_MSG FAR ∗pk_msg);typedef struct t_msg { UW _Wrsv_00 ; VB msgcont[2] ;} T_MSG ;

Note:The structure "T_MSG" is defined in the header file. The length of the message portion of this structure is tentatively declared as "2".

Input parameters: mbxid Mailbox ID pk_msg Message pointer pk_msg->msgcont[] Body of message



Input parameters:

AL Mailbox ID

System call: scall snd_msg



<Error codes>



0-17-23-35

Normal end Mailbox not supportedID number is "0" ID number too large

_Wrsv_00msgcont

ADB:AH+0+4

+(4+n)

Starting address of message OS reserved area Body of message (length: n bytes)


<Dispatch causes>

If a task with a higher priority level than the task that issued this system call is released from waiting for the mailbox, the task that was released from the WAIT state is dispatched.

<Description>

This system call sends a message to the specified mailbox. The body of the message itself is not copied; only the address of the message structure is passed to the mailbox. Therefore, it is necessary to save the body of the message until the message is received.

Sending and receiving messages must have a one-to-one correspondence in communication. If a message sent to the mailbox is not received and a message is again sent with the same message address specified, mailbox control thereafter will not be executed correctly.

If there are no tasks waiting for a message in the specified mailbox, the message is added to the end of the message queue.

If there are tasks waiting for a message in the specified mailbox, the first task in the queue receives the message and is released from the WAIT state. If a task is released from the WAIT state and enters the READY state, the task that issued "snd_msg" may be preempted as a result of scheduling.

The first portion of the message area is used for OS management. The size of this area is four bytes. In applications, use the body of the message as the area for communicating messages.

If the mailbox ID is specified as "0", "E_RSID" is returned.

If a value that exceeds the maximum mailbox ID as specified in the Configurator is specified for the mailbox ID, or if a negative value is specified for the mailbox ID, "E_IDOVR" is returned.

If the mailbox is not registered in the Configurator, "E_NOSPT" is returned.

203


204

<Examples>



#include "scdef.h"#define SEND_DATA 20#define MBX_ID 1typedef struct t_mail { UW _Wrsv_00 ; B ∗msgptr} T_MAIL ;

TASK task1(){ T_MAIL FAR ∗message ;

: get_blk((Void FAR ∗∗)&message. MBX_ID) ; message->msgptr=(B ∗)"Hello"; snd_msg(1, (T_MSG FAR ∗)message) ;

:}

#include scdef.inc.IMPORT snd_msg

MBX_ID .equ 1.SECTION T_DATA, DATA, ALIGN=2

message .RES.W 1.SDATA "Hello"


mov a, BNKSYM(message) ; Message specificationmov adb, a ;mov a, #message ;mv a, #MBX_ID ; Destination mailbox specificationscall snd_msgbnz error

:

205

MEMO


206

4.5.16 rcv_msg (Receive Message from Mailbox)

This system call receives a message from a mailbox.-61 Task section Task independent section ×


Format: ER ercd = rcv_msg(T_MSG FAR ∗∗ppk_msg, ID mbxid);typedef struct t_msg { UW _Wrsv_00 ; VB msgcont[2] ;} T_MSG ;


Input parameters: ppk_msg Pointer for area where message is to be storedmbxid Mailbox ID

Output parameters: ercd Error code (E_OK: normal)∗ppk_msg Message pointer ("far" pointer) ppk_msg->msgcont[] Body of message


Input parameters: AL Mailbox ID

System call: scall rcv_msg

Output parameters: • ZF 1: Normal end


<Error codes>



0-17-23-35-69

Normal end Mailbox not supportedID number is "0" ID number too large Context error (issued from non-task)

_Wrsv_00msgcont

ADB:AL+0+4

+(4+n)



<Dispatch causes>

If the task that issued this system call begins waiting for the mailbox, the task with the next highest priority ranking is dispatched.

<Description>

This system call causes the task to wait to receive a message from the specified mailbox. If a message has already been sent to the specified mailbox, the address of the message at the front of the message queue is returned. If no message has been sent to the mailbox, the task that was the source of this call enters the WAIT state.

The system call "rcv_msg" returns the message by means of a 24-bit address that includes the bank address (the "far" pointer for the C language interface).

This system call cannot be issued from the non-task section. If this system call is issued from the non-task section, "E_CTX" is returned.




<Examples>



#include "scdef.h"#define MBX_ID 1TASK task1(){ T_MSG FAR ∗msg ;

: if(rcv_msg((T_MSG FAR ∗∗) &msg, MBX_ID) == E_OK) {

: }

:}

#include scdef.inc.IMPORT rcv_msg

MBX_ID .equ 1:

mv a, #MBX_ID ; ID of mailbox from which message; is to be received

scall rcv_msgbnz error

:

207


208

4.5.17 prcv_msg (Poll and Receive Message from Mailbox)

This system call receives (via polling) a message from a mailbox.-204 Task section Task independent section


Format: ER ercd = prcv_msg(T_MSG FAR ∗∗ppk_msg, ID mbxid);typedef struct t_msg { UW _Wrsv_00 ; VB msgcont[2] ;} T_MSG ;


Input parameters: ppk_msg Pointer for area where message is to be storedmbxid Mailbox ID

Output parameters: ercd Error code (E_OK: normal)∗ppk_msg Message pointer ("far" pointer) ppk_msg->msgcont[] Body of message


Input parameters: AL Mailbox ID

System call: scall prcv_msg



<Error codes>



0-17-23-35-89

Normal end Mailbox not supportedID number is "0" ID number too large No message

_Wrsv_00msgcont

ADB:AL+0+4

+(4+n)



<Dispatch causes>


<Description>

This system call receives a message from the specified mailbox. If a message has already been sent to the specified mailbox, the address of the message at the front of the message queue is returned. If no message has been sent to the mailbox, the task that was the source of this call does not enter the WAIT state; instead, "E_PLFAIL" is returned.

The system call "prcv_msg" returns the message by means of a 24-bit address that includes the bank address (the "far" pointer for the C language interface).




<Examples>



#include "scdef.h"#define MBX_ID 1TASK task1(){ T_MSG FAR ∗msg ;

: if(prcv_msg((T_MSG FAR ∗∗)&msg, MBX_ID) != E_PLFAIL) {

: }

:}

#include scdef.inc.IMPORT prcv_msg

MBX_ID .equ 1:

mv a, #MBX_ID ; ID of mailbox from which message; is to be received

scall prcv_msgbnz error

:

209


210

4.5.18 mbx_sts (Get Mailbox Status)

This system call references the status of a mailbox.-60 Task section Task independent section


Format: ER ercd = mbx_sts(T_MBXS ∗pk_mbxs, ID mbxid);typedef struct t_mbxs { T_MSG FAR ∗pk_msg ; ID wtskid;} T_MBXS ;

Note:The structures "T_MBXS" and "T_MSG" are defined in the header file.

Input parameters: pk_mbxs Pointer for area where message is to be storedmbxid Mailbox ID

Output parameters: ercd Error code (E_OK: normal)pk_mbx->pk_msg Address of message at start of message queue

NADR(0): No message pk_mbx->wtskid ID of first task in queue waiting for a message

FALSE(0): No waiting tasks


Input parameters: ADB:AH Address of area (6 bytes) where mailbox information is to be stored Mailbox ID

AL Mailbox ID

System call: scall mbx_sts


• ZF 0: Error endAL Error

pk_msgwtskid

ADB:AH+0+4+6

Address of message at start of message queueNADR(0): No message

ID of first task in queue waiting for a message FALSE(0): No waiting tasks


<Error codes>

<Dispatch causes>


<Description>

This system call returns information concerning the status of the specified mailbox. The mailbox information includes the address of the first message in the message queue and the ID of the first task in the message waiting queue.

If there are no messages in the specified mailbox, "NADR (0)" is returned in the message address information. If there are no tasks in the WAIT state waiting for a message in the specified mailbox, "FALSE (0)" is returned in the waiting task ID information.

There can either be a message or a task waiting for a message, not both. Therefore, "mbx_sts" only returns information on one or the other.






0-17-23-35


211


212

<Examples>



#include "scdef.h"#define MBX_ID 1TASK task1(){ T_MBXS mbxsts ; ER ercd ;

: ercd = mbx_sts(&mbxsts, MBX_ID) ; if(ercd == E_OK) {

if(mbxsts. pk_msg != NADR) {/∗ Message exists ∗/

} else if(mbxsts.wtskid !=0) {/∗ Waiting task exists ∗/

} } else {

/∗ Error ∗/ }

:}

#include scdef.inc.IMPORT mbx_sts

MBX_ID .equ 1.SECTION T_DATA, DATA, ALIGN=2

mbxsts .RES.H 3

.SECTION T_CODE, CODE, ALIGN=2 :

mov a, #BNKSYM(mbxsts) ; Status storage address specificationmov adb, amovw a, #mbxstsmovn a, #MBX_ID ; Mailbox ID specificationscall mbx_stsbnz error

:

213

MEMO



There are four memorypool management function system calls:• get_blk • rel_blk • pget_blk • mpl_sts

� MemoryPool Management Function System Calls

There are four memorypool management function system calls:

� get_blk (Get Memory Block)

This system call gets memory.

� pget_blk (Poll and Get Memory Block)

This system call gets via polling memory.

� rel_blk (Release Memory Block)

This system call releases memory.

� mpl_sts (MemoryPool Status)

This system call references the status of a memorypool.

214

215

MEMO


216

4.6.1 get_blk (Get Memory Block)

This system call gets (or waits for) a fixed-length memory block.-77 Task section Task independent section ×


Format: ER ercd = get_blk(void FAR ∗∗p_blk, ID mplid);

Input parameters: p_blk Pointer for area where memory block pointer is to be stored

mplid Memorypool ID

Output parameters: ercd Error code (E_OK: normal)∗p_blk Pointer for memory block that was allocated

("far" pointer)


Input parameters: AL Memorypool ID

System call: scall get_blk

Output parameters: • ZF 1: Normal endADB:AL Starting address of memory block that was allocated


<Error codes>

<Dispatch causes>

If the task that issued this system call begins waiting for the memorypool, the task with the next highest priority ranking is dispatched.



0-17-23-35-69

Normal end Mailbox not supportedID number is "0" ID number too large Context error (issued from non-task)


<Description>

This system call causes a task to wait in order to get a memory block from the specified memorypool.

If one block is allocated from the specified memorypool, the starting address of that block is returned to the task. If there are no available memory blocks because all memory blocks in the specified pool are in use, then the task waits until a memory block is released by another task.

If there are tasks in the WAIT state, they wait for blocks to be released in the sequence in which they made their requests.

The memory block that is allocated is one block of fixed length. Information on the memorypool block length, number of blocks, allocation, etc., is defined in the memorypool creation information.

The system call "get_blk" returns the memory block by means of a 24-bit address that includes the bank address (the "far" pointer for the C language interface).

Memory blocks that have been allocated are released using the "rel_blk" system call. In this case, the memory block to be released is specified by using the starting address of the memory block as allocated by the "get_blk" system call. Therefore, the task that issued "get_blk" must retain the starting address of the memory block allocated to it until it releases that memory block. For example, if the allocated memory block was used for a message, the memory block starting address should be retained until the task that is the recipient of the message receives the message or until all processing concerning that message is complete.

This system call cannot be issued from the non-task section. If this system call is issued from the non-task section, "E_CTX" is returned.

If the memorypool ID is specified as "0", "E_RSID" is returned.

If a value that exceeds the maximum memorypool ID as specified in the Configurator is specified for the memorypool ID, or if a negative value is specified for the memorypool ID, "E_IDOVR" is returned.

If the memorypool is not registered in the Configurator, "E_NOSPT" is returned.

217


218

<Examples>



#include "scdef.h"#define MPL_ID 1TASK task1(){ char FAR ∗buf ; : if(get_blk((void FAR ∗∗)&buf, MPL_ID) == E_OK) {

: }

:}

#include scdef.inc.IMPORT get_blk

MPL_ID .equ 1:

mv a, #MPL_IDscall get_blkbnz errormovw blk_address, a ; adb:almov a, adb ; Starting address of memory blockmov blk_bank, a

219

MEMO


220

4.6.2 pget_blk (Poll and Get Memory Block)

This system call gets (via polling) a fixed-length memory block.-205 Task section Task independent section


Format: ER ercd = pget_blk(void FAR ∗∗p_blk, ID mplid);

Input parameters: p_blk Pointer for area where memory block pointer is to be stored

mplid Memorypool ID

Output parameters: ercd Error code (E_OK: normal)∗p_blk Pointer for memory block that was allocated

("far" pointer)


Input parameters: AL Memorypool ID

System call: scall pget_blk

Output parameters: • ZF 1: Normal endADB:AL Starting address of memory block that was allocated


<Error codes>

<Dispatch causes>


<Description>

This system call gets one memory block from the specified memorypool and returns the starting address of the memory block. If there are no available memory blocks because all memory blocks in the specified pool are in use, then "E_PLFAIL" is returned.

Tasks in the WAIT state waits until memory blocks are released in a wait request order.

The memory block that is allocated is one block of fixed length. Information on the memorypool block length, number of blocks, allocation, etc., is defined in the memorypool creation information.

The system call "pget_blk" returns the memory block by means of a 24-bit address that includes the bank address (the "far" pointer for the C language interface).



0-17-23-35-89

Normal end Mailbox not supportedID number is "0" ID number too large Polling failed (no available blocks)


Memory blocks that have been allocated are released using the "rel_blk" system call. In this case, the memory block to be released is specified by using the starting address of the memory block as allocated by the "pget_blk" system call. Therefore, the task that issued "pget_blk" must retain the starting address of the memory block allocated to it until it releases that memory block. For example, if the allocated memory block was used for a message, the memory block starting address should be retained until the task that is the recipient of the message receives the message or until all processing concerning that message is complete.

If there are no blocks available under the specified memorypool ID, "E_PLFAIL" is returned.




<Examples>



#include "scdef.h"#define MPL_ID 1TASK task1(){ char FAR ∗buf ;

: if(pget_blk,(void FAR ∗∗)&buf, MPL_ID)

== E_PLFAIL) { }

:}

#include scdef.inc.IMPORT pget_blk

MPL_ID .equ 1:

mv a, #MPL_IDscall pget_blkbnz errormovw blk_address, a ; adb:almov a, adb ; Starting address of memory blockmov blk_bank, a

221


222

4.6.3 rel_blk (Release Memory Block)

This system call releases a fixed-length memory block.-79 Task section Task independent section


Format: ER ercd = rel_blk(ID mplid, void FAR ∗blk);

Input parameters: mplid Memorypool ID blk Memory block pointer



Input parameters: AL Memorypool IDADB:AH Memory block address

System call: scall rel_blk

Output parameters: • ZF 1: Normal endADB:AL E_OK


<Error codes>

<Dispatch causes>

If a task with a higher priority level than the task that issued this system call is released from waiting for the memorypool, the task that was released from waiting is dispatched.

<Description>

This system call releases an allocated memory block to the specified memorypool. If the address of the memory block being released does not belong to the specified memorypool, "E_ILBLK" is returned.


E_OKE_NOSPTE_RSIDE_IDOVRE_ILBLK

0-17-23-35-59

Normal end Mailbox not supportedID number is "0" ID number too large Illegal memory block address


In order to avoid reduced performance by the system call, the "rel_blk" system call does not check to determine whether or not the specified memory block has been allocated (or whether or not it has already been released). If a memory block that has not been allocated is specified, subsequent memory management operations will not be performed correctly.

If there are any tasks waiting for the memorypool ID to which the memory block was released, the first task in the queue gets the memory block.

If the task (the first task in the waiting queue of the released memorypool ID) which got the memory block that was released enters the READY state, the task that issued "rel_blk" may be preempted.




<Examples>



#include "scdef.h"#define MPL_ID 1TASK task1(){ char FAR ∗buf ;

: if(rel_blk(MPL_ID, (void FAR ∗)&buf) == E_OK) {

: }

:}

#include scdef.inc.IMPORT rel_blk

MPL_ID .equ 1:

mov a, #BNKSYM(blk_address) ; Bank addressmov adb, amovw a, #blk_address ; Memory block addressmv a, #MPL_ID ; Memorypool IDscall rel_blkbnz error

:

223


224

4.6.4 mpl_sts (Get MemoryPool Status)

This system call gets the status of a memorypool.-76 Task section Task independent section


Format: ER ercd = mpl_sts(T_MPLS ∗pk_mpls, ID mplid);typedef struct t_mpls {

MEMSZ blksz ;MEMSZ mplsz ;BCNT frbcnt ;ID wtskid ;

}

Note:The structure "T_MPLS" is defined in the header file.

Input parameters: pk_mpls Pointer for the packet in which the memorypool information is to be stored

mplid Memorypool ID

Output parameters: ercd Error code (E_OK: normal) pk_mpls->blksz Size of one memory block pk_mpls->mplsz Size of entire memorypool pk_mpls->frbcnt Number of available blocks pk_mpls->wtskid ID of first task in queue



Input parameters: ADB:AH Address of area (8 bytes) where the memorypool information is stored

AL Memorypool ID

System call: scall mpl_sts

Output parameters: • ZF 1: Normal end AL E_OK

• ZF 0: Error endAL Error code

blksz

frbcnt

ADB:AH+0

+4

+8

Address where memorypool information is to be stored Size of one memory block Size of entire memorypool Number of available blocks ID of first task in queue


mplsz

wtskid

+2

+6


<Error codes>

<Dispatch causes>


<Description>

This system call returns information on the current status of the specified memorypool. The memorypool information includes the size of one memory block, the size of the entire memorypool, the number of available blocks, and the ID of the first task in the queue.

For the ID information on the first task in the queue, the ID of the first task in the queue for the specified memorypool is returned. Tasks are arranged in the memory waiting queue in the order in which they began waiting for memory. If there are no tasks in the WAIT state for the specified memorypool, "FALSE (0)" is returned for the ID of the first task in the WAIT state.



0-17-23-35


225


226

<Examples>



#include "scdef.h"#define MPL_ID 1TASK task1(){ T_MPLSstatus ;

: mpl_sts(&status, MPL_ID) ;

:}

#include scdef.inc.IMPORT mpl_sts

MPL_ID .equ 1:

.SECTION T_DATA, DATA, ALIGN=2status_area .RES.H 4


mov a, #BNKSYM (status_area) ; Memorypool informationmov adb, a ; Storage addressmov a, #status_area ; Memorypool IDmv a, #MPL_IDscall mpl_stsbnz error

:


227


There are four interrupt management function system calls:• ret_int • chg_ilv • ret_wup • ilv_sts

� Interrupt Management Function System Calls

There are four interrupt management function system calls:

� ret_int (Return from Interrupt Handler)

This system call returns from an interrupt handler.

� ret_wup (Return and Wakeup Task)

This system call returns from an interrupt handler and wakes up a task.

� chg_ilv (Change Interrupt Level)

This system call changes processor interrupt levels.

� ilv_sts (Interrupt Level Status)

This system call returns the processor interrupt level value as a return parameter.


228

4.7.1 ret_int (Return from Interrupt Handler)

This system call returns from an interrupt handler.Task section × Task independent section


Format: void ret_int(void) ;

Output parameters: Control does not return to the source of the call. • "ret_int()" is defined as a macro in the header file.• Always use "ret_int()" in a function declared with the "__interrupt" qualifier.


Input parameters: SP Contents of SP register at the start of interrupt processing

System call: scall ret_int

Output parameters: Control does not return to the source of the call.

<Error codes>

None (Error checking is not performed.)

<Dispatch causes>


<Description>

The "ret_int" system call is issued when terminating interrupt processing. Because "ret_int" actually terminates the interrupt processing, control does not return to the source of this system call. When terminating interrupt processing, always issue the "ret_int" system call, not the "reti" instruction.

When writing the interrupt handler in assembly language, it is necessary, before issuing "ret_int", to restore the system stack pointer (SP) to its value that it had at the start of interrupt processing. For example, operation is not guaranteed if, as part of the interrupt processing, the "ret_int" system call is executed from inside a subroutine called by the "call" instruction or another such instruction.

When writing the interrupt handler in C, issue "ret_int()" within a function declared with the "__interrupt" qualifier. As a matter of fact, the "ret_int()" is replaced with the "return" statement. Issuing "ret_int()" from a function called by the interrupt handler creates a subroutine instruction to return to the interrupt handler. As a result, the interrupt handler is not terminated by the issuance of "ret_int()" from a function called by the interrupt handler.

The "ret_int" system call can only be issued from the initialization handler or an interrupt handler. It cannot be issued from a task, a cyclic handler, or an alarm handler.

The "ret_int" system call is replaced by equivalent processing during macro expansion in both assembly language and in C.

When a system call is issued in an interrupt handler and the task status is changed, the scheduling function shifts execution authority to the task with the highest priority level. (The task that was running before the interrupt occurred is preempted.)

If a task has not been started by the initialization handler, control is passed to the system idle task.


<Examples>



#include "scdef.h"

#pragma register(1)

__interrupt INTHDR int_hdr(){ set_flg(1) ;

:ret_int() ; /∗ Terminates interrupt handler ∗/

}#pragma noregister

#include scdef.inc:

inthdr:pushw rw2 ; Restores the SP to its original value

: ; when the interrupt handler popw rw2 ; terminates if the stack was usedscall ret_int ; Terminates interrupt handler

:

229


230

4.7.2 ret_wup (Return and Wakeup Task)

This system call returns from an interrupt handler and wakes up a task.Task section × Task independent section


Format: void ret_wup(ID tskid) ;


Output parameters: Control does not return to the source of the call. • "ret_wup()" is defined as a macro in the header file.• Always use "ret_wup()" in a function declared with the "__interrupt" qualifier.


Input parameters: AL Task ID SP Contents of SP register at the start of interrupt processing

System call: scall ret_wup

Output parameters: Control does not return to the source of the call.

<Error codes>

The following error codes are valid only in an exception handler.

<Dispatch causes>

If a task with a priority level higher than that which was running when the interrupt was generated is specified, that task is dispatched.

<Description>

The "ret_wup" system call wakes up the specified task and terminates interrupt processing. In actuality, this system call issues "wup_tsk" and then issues "ret_int". Because "ret_wup" terminates the interrupt processing, control does not return to the source of this system call. Note that if an error occurs, exception processing is performed but control does not return to the source of the system call. When error processing is desired, use "wup_tsk" and "ret_int".



0-23-35-49-53-74

Normal end "TSK_SELF" was specified in the non-task section ID number too large Cannot specify the current task Specified task is in the DORMANT state Queue count overflow


When system call exception processing is generated, the "wup_tsk" system call, not "ret_wup", is stored in the function code in the exception information that is passed to the exception handler.

When writing the interrupt handler in assembly language, it is necessary, before issuing "ret_wup", to restore the system stack pointer (SP) to its value that it had at the start of interrupt processing. For example, operation is not guaranteed if, as part of the interrupt processing, the "ret_wup" system call is executed from inside a subroutine called by the "call" instruction or another such instruction.

When writing the interrupt handler in C, issue "ret_wup()" within a function declared with the "__interrupt" qualifier. Because the "ret_wup()" function is actually replaced with "wup_tsk()" and the "return" statement, when issuing "ret_wup()" from a function called by the interrupt handler, interrupt processing is not terminated until the "return" statement is executed. In the same manner, interrupt processing is not terminated in an assembly language program until "reti" or "retiq" are executed.

The "ret_wup" system call can be issued from a handler (the initialization handler, an interrupt handler, a cyclic handler, or an alarm handler). It cannot be issued from a task.

The "ret_wup" system call is replaced by equivalent processing during macro expansion in both assembly language and in C.

When a system call is issued in an interrupt handler and the task status is changed, the scheduling function passes execution authority to the task with the highest priority level.

<Examples>



#include "scdef.h"

#pragma register(1)

__interrupt INTHDR int_hdr(){ set_flg(1) ;

: ret_wup(1) ;/∗ Wakes up the task with the specified task ID and then terminates handler ∗/}#pragma noregister

#include scdef.inc#IMPORT wup_tsk

inthdr::

pushw rw2 ; Restores the SP to its original value: ; before issuing "ret_wup" if the stack

popw rw2 ; pointer was moved mv a, #1 ; ID of task to be woken upscall ret_wup ; Wakes up task and then terminates handler

:

231


232

4.7.3 chg_ilv (Change Interrupt Level)

This system call changes processor interrupt levels.-67 Task section Task independent section


Format: ER ercd = chg_ilv(UINT intno, UINT intlv);

Input parameters: intno Interrupt number Number from 0 to 255 corresponding to IRQ0 to IRQ255

intlv Interrupt level to be set Specify in a range from 0 to 7 "0" indicates the highest interrupt level "7" indicates that the interrupt is masked (prohibited)



Input parameters: AL Interrupt number Number from 0 to 255 corresponding to IRQ0 to IRQ255

AH Interrupt level to be set Specify in a range from 0 to 7 "0" indicates the highest interrupt level "7" indicates that the interrupt is masked (prohibited)

System call: scall chg_ilv

Output parameters: • ZF 1: Normal endAL E_OK - ZF


<Error codes>

<Dispatch causes>



E_OKE_NOSPTE_VECNE_PAR

0-17-42-33

Normal end Interrupt number undefined Interrupt number too large Illegal interrupt level specification


<Description>

This system call changes specified interrupt levels (IRQn). Specify a value from 0 to 7 for the interrupt level. Interrupt level "0" indicates the highest priority level, while interrupt level "6" indicates the lowest priority level. Interrupt level "7" disables (masks) the specified interrupt.

The "chg_ilv" system call writes the ICR (Interrupt Control Register). In this case, the Intelligent I/O Service is also cancelled at the same time (ISE = 0, ICS0 to 3 = 0). Therefore, use "chg_ilv" to change interrupt levels before setting and running the Extended Intelligent I/O Service.

For details on the Extended Intelligent I/O Service, refer to the user’s manual for the chip being used.

<Examples>



#include "scdef.h"#define IRQ11#define ILV22

TASK task1(){ chg_ilv(IRQ1, ILV2) ; /∗ Sets IRQ1 interrupt level ∗/

: /∗ to the value of ILV2 ∗/}

#include scdef.inc.IMPORT chg_ilv

IRQ1 .equ 1ILV2 .equ 2

:mov a, #ILV2mov a, #IRQ1scall chg_ilvbnz error

:

233


234

4.7.4 ilv_sts (Get Interrupt Level Status)

This system call returns the processor interrupt level value as a return parameter.-68 Task section Task independent section


Format: ER ercd = ilv_sts(UINT ∗p_intlv, UINT intno);

Input parameters: intno Interrupt number Number from 0 to 255 corresponding to IRQ0 to IRQ255

Output parameters: ercd Error code (E_OK: normal) ∗p_intlv Interrupt level (0 to 7)


Input parameters: AL Interrupt number Number from 0 to 255 corresponding to IRQ0 to IRQ255

System call: scall ilv_sts

Output parameters: • ZF 1: Normal end AL Interrupt level (0 to 7)


<Error codes>

<Dispatch causes>



E_OKE_NOSPTE_VECN

0-17-42

Normal end Interrupt number undefined Interrupt number too large


<Description>

This system call returns the interrupt level of the specified interrupt (IRQn). A value from 0 to 7 is returned for the interrupt level. Interrupt level "0" indicates the highest priority level, while interrupt level "6" indicates the lowest priority level. Interrupt level "7" disables (masks) the specified interrupt.

The "ilv_sts" system call reads the ICR (Interrupt Control Register).

<Examples>



#include "scdef.h"#define INTR_LEVEL 12

TASK task1(){ UINT intlv; level = ilv_sts(&intlv, INTR_LEVEL) ;

:}

#include scdef.inc.IMPORT ilv_sts

INTR_LEVEL equ 12:

mov a, #INTR_LEVELscall ilv_stsbnz error

:

235



There are eight time management function system calls.• set_tim • cyh_sts • get_tim • def_alm • def_cyc • alh_sts • act_cyc • ret_tmr

� Time Management Function System Calls

There are eight time management function system calls.

� set_tim (Set Time)

This system call sets the value of the system clock according to the specified time data.

� get_tim (Get Time)

This system call reads the value of the system clock.

� def_cyc (Define Cyclic Handler)

This system call defines a task-independent section handler that runs at a specified time interval.

� act_cyc (Active Cyclic Handler)

This system call changes the cyclic handler activity status.

� cyh_sts (Cyclic Handler Status)

This system call references the status of a cyclic handler.

� def_alm (Define Alarm Handler)

This system call defines a task-independent section handler that is executed after a fixed period of time.

� alh_sts (Alarm Handler Status)

This system call references the status of an alarm handler.

� ret_tmr (Return from Timer Handler)

This system call returns from a timer handler.

236

237

MEMO


238

4.8.1 set_tim (Set Time)

This system call sets the value of the system clock according to the specified time data.



Format: ER ercd = set_tim(T_TIME ∗pk_time);typedef struct t_time {

UW ltime;UH utime;

} T_TIME;

Note: The structure "T_TIME" is defined in the header file.

Input parameters: pk_time Pointer for area where the time setting is stored pk_time->ltime Low-order 32-bits of the system clock pk_time->utime High-order 16-bits of the system clock



Input parameters:

System call: scall set_tim



<Error codes>

<Dispatch causes>



E_OKE_TNOSPT

0-19

Normal end Timer not supported

ltimeutime

ADB:AL+0+4+6

Starting address of area (6 bytes) where the time setting is stored

Low-order 32-bits of the system clock

High-order 16-bits of the system clock


<Description>

This system call sets the system clock. The specified value assumes one cycle of the reference clock as one count.

At startup, the kernel does not initialize the value of the system clock that is stored internally.

If there is a timer handler that is set for execution at a time prior to the time set by this system call, that handler is initialized by the issuance of this system call.

If the system clock is not supported in the Configurator, "E_TNOSPT" is returned.

<Examples>



#include "scdef.h"

T_TIME new_time = { 0x12345678L, 0 } ;

TASK task1() { set_tim(&new_time) ;

:}

#include scdef.inc.IMPORT set_tim


new_time .DATA.H 5678.DATA.H 1234.DATA.H 0000

SECTION T_CODE, CODE, ALIGN=2:

mov a, #BNKSYM(new_time)mov adb, amovw a, #new_timescall set_tim

:

239


240

4.8.2 get_tim (Get Time)

This system call reads the value of the system clock.-84 Task section Task independent section


Format: ER ercd = get_tim(T_TIME ∗pk_time);typedef struct t_time {

UW ltime;UH utime;

} T_TIME;

Note: The structure "T_TIME" is defined in the header file.

Input parameters: pk_time Pointer for area where the system clock is stored

Output parameters: ercd Error code (E_OK: normal)pk_time->ltime Low-order 32-bits of the system clock pk_time->utime High-order 16-bits of the system clock


Input parameters: ADB:AL Starting address of area (6 bytes) where the system clock is stored

System call: scall get_tim



<Error codes>

<Dispatch causes>



E_OKE_TNOSPT

0-19

Normal end Timer not supported

ltimeutime

ADB:AL+0+4+6

Address of area where the system clock is stored Low-order 32-bits of the system clock

High-order 16-bits of the system clock


<Description>

This system call returns the starting address of the area where the system clock is stored. The system clock information is 6 bytes long. If the system clock is not supported in the Configurator, "E_TNOSPT" is returned.

<Examples>



#include "scdef.h"

TASK task1(){ T_TIME clock ;

:get_tim(&clock) ;

:}

#include scdef.inc.IMPORT get_tim


clock RES.H 3

SECTION T_CODE, CODE, ALIGN=2:

mov a, #BNKSYM (clock) ; Address where system clock value is storedmov adb, amovw a, #clockscall get_tim

:

241


242

4.8.3 def_cyc (Define Cyclic Handler)

This system call defines a task-independent section handler that runs at a specified time interval.



Format: ER ercd = def_cyc(HNO cyhno, T_CYH ∗pk_cyh);typedef struct t_cyh {

CY cytime ;FP cychdr ;UINT cyhact ;

} T_CYH ;

Note: The structure "T_CYH" is defined in the header file.

Input parameters: cyhno Cyclic handler number (1 to maximum number of cyclic handlers registered)

pk_cyh Pointer for cyclic handler setting information area

NADR: Setting cancelled pk_cyh->cychdr Pointer for cyclic handler pk_cyh->cytime Time interval pk_cyh->cyhact Initial activation state

TCY_ON or TCY_INI Executes the cyclic handler

TCY_OFF Does not execute the cyclic initiation

handler



Input parameters: ADB:AH NADR (0): Releases cyclic initiation handler settingor ("0" is also set in ADB)

System call: scall def_cyc


• ZF 0: Error end Error code

cytimecychdr

ADB:AH+0+2+6

Address of cyclic handler setting information area (8 bytes) Time intervalStarting address (32-bits) of cyclic handler Initial activation status

TCY_ON (1) or TCY_INI (2) Executes the cyclic handler

TCY_OFF (0)Does not execute the cyclic initiation handler

Cyclic handler number (1 to maximum number of cyclic handlers registered)

cyhact+8

AL


<Error codes>

<Dispatch causes>


<Description>

This system call defines the specified cyclic handler. The cyclic handler is executed on the specified time interval on the basis of this definition. A cyclic handler program is executed at the non-task level, and is terminated by the ret_tmr system call. In addition, if "NADR" is specified for the cyclic handler setting information address, a previously set handler is released.

For the cyclic handler number, specify a number from 1 to the maximum number of cyclic handlers that can be registered. The maximum number of cyclic initiation handlers that can be registered is set in the Configurator.

The cyclic handler information that is set by this system call includes the cyclic handler start address, time interval, and the initial activation status.

Specify a number from 1 to 65,535 for the handler time interval, assuming one interval of the system clock as one count. If "0" is specified, "E_ILTIME" is returned.

For the initial activation status, specify whether the cyclic handler is to be executed or not once the cyclic handler has been defined. If it is, specify "TCY_ON" or "TCY_INI"; if not, specify "TCY_OFF". ("TCY_ON" and "TCY_INI" have the same meaning.) If the handler is not initialized, it is not executed until the activation status is set to "ON" by the "act_cyc" system call (which controls the activation of cyclic handlers).

The interrupt level (ILM value) of the cyclic handler is the interrupt level of the timer interrupt used for the system clock.


E_OKE_TNOSPTE_RSMDE_PARE_ILTIMEE_CTX

0-19-22-33-37-69

Normal end Timer not supported Activation status error Cyclic handler number error "0" was specified for cycle Context error (issued from non-task)

243


244

If this system call is issued from the non-task section, "E-CTX" is returned.

If the handler cycle was specified as "0", "E_ILTIME" is returned.

If the cyclic handler number that is specified exceeds the maximum value or is a negative value, "E_PAR" is returned.

If a value other than one defined as a label is specified for the initial activation status, "E_RSMD" is returned.

If the cyclic handler is not registered in the Configurator, "E_TNOSPT" is returned.

<Examples>



#include "scdef.h"#define CYH_NO 1T_CYH cyh_info = {0x0100, rotate_exec, TCY_ON} ;

TASK task1(){ def_cyc(CYH_NO, &cyh_info) ;

:}

#include scdef.inc.IMPORT def_cyc

CYH_NO .equ 1:

.SECTION T_DATA, DATA, ALIGN=2cyh_info .DATA.H h’00100

.DATA.L rotate_exe

.DATA.H TCY_ON


mov a, #BNKSYM(cyh_info) ; Sets the address where themov adb, a ; cyclic handler settingmovw a, #cyn_info ; information is to be storedmv a, #CYH_NO ; Cyclic handler numberscall def_cycbnz error

:

245

MEMO


246

4.8.4 act_cyc (Active Cyclic Handler)

This system call changes the cyclic handler activity status.-94 Task section Task independent section


Format: ER ercd = act_cyc(HNO cyhno, UINT cyhact);

Input parameters: cyhno Cyclic handler number cyhact Cyclic activation status

TCY_ON: Activates the cyclic handler (ON state)

TCY_OFF: Temporarily halts the execution of the cyclic handler (OFF state)

TCY_INI: Initial count



Input parameters: AL Cyclic handler number AH Activation status

TCY_ON: Activates the cyclic handler (ON state)

TCY_OFF: Temporarily halts the execution of the cyclic handler (OFF state)

TCY_INI: Initial count

System call: scall act_cyc



<Error codes>


E_OKE_TNOSPTE_RSMDE_PARE_NOEXSE_CTX

0-19-22-33-52-69

Normal end Timer not supported Activation status error Cyclic handler number error Cyclic handler undefined Context error (issued from non-task with TCY_INI specified)


<Dispatch causes>This system call does not create a dispatching situation.

<Description>This system call controls the activation status (ON/OFF state) of the specified cyclic handler. If "ON" is specified for the activation status, activation of the specified cyclic handler is resumed. If "OFF" is specified for the activation status, execution of the specified cyclic handler is temporarily halted. No error results if the specified activation status is the same as the current status.A temporary halt of cyclic execution simply means that the cyclic handler is not executed when the time interval arrives. Even when halted, the kernel's internal count is updated.

The kernel's internal count is not initialized by changing the activation status from OFF to ON.

When counter initialization ("TCY_INI") is specified, the kernel's internal count is cleared. Accordingly, the next cyclic handler call comes after the count specified by "def_cyc", once "act_cyc" is issued. If counter initialization ("TCY_INI") is specified by itself, the activation status (ON/OFF) does not change.This system call can be issued from the non-task section, but only with the "TCY_ON" or "TCY_OFF" specification. If issued with the "TCY_INI" specification, "E_CTX" is returned.

If this system call is issued for a cyclic handler that has not yet been defined, "E_NOEXS" is returned.

If the cyclic handler number that is specified exceeds the maximum value or is a negative value, "E_PAR" is returned.If a value other than one defined as a label is specified for the initial activation status, "E_RSMD" is returned.


<Examples>• C language interface


#include "scdef.h"#define CYH_NO 1

TASK task1(){ act_cyc(CYH_NO, TCY_ON) ;

:}

#include scdef.inc.IMPORT act_cyc

CYH_NO .equ 1:

mv a, #TCY_OFF ; Cyclic handler activation statusmv a, #CYH_NO ; Cyclic handler numberscall act_cycbnz error

:

247


248

4.8.5 cyh_sts (Get Cyclic Handler Status)

This system call references the status of a cyclic handler.-92 Task section Task independent section ×


Format: ER ercd = cyh_sts( T_CYHS ∗pk_cyhs, HNO cyhno);typedef struct t_cyhs { CY cytime ; CY lftime ; UINT cyhact ;} T_CYHS ;

Note: The structure "T_CYHS" is defined in the header file.

Input parameters: pk_cyhs Pointer for cyclic handler information storage area

cyhno Cyclic handler number

Output parameters: ercd Error code (E_OK: normal) pk_cyhs->cytime Cyclic time interval pk_cyhs->lftime Time until next execution pk_cyhs->cyhact Cyclic handler activation status

0: Stopped (TCY_OFF) 1: Running (TCY_ON)


Input parameters: ADB:AH Address of cyclic handler information storage area (6 bytes)

AL Cyclic handler number

System call: scall cyh_sts



cytimelftime

ADB:AH+0+2+4

Address for cyclic handler information storage Time interval Time until next execution

Cyclic handler activation status 0: Stopped (TCY_OFF) 1: Running (TCY_ON)

cyhact+6


<Error codes>

<Dispatch causes>


<Description>

This system call returns information on the specified cyclic handler. The cyclic handler information includes the defined time interval, the time until the next execution of the cyclic handler, and the activation status of the cyclic handler.

The "cyh_sts" system call cannot be issued from the non-task section. When issued, "E_CTX" is returned.


<Examples>• C language interface



E_OKE_TNOSPTE_PARE_NOEXSE_CTX

0-19-33-52-69

Normal end Timer not supported Cyclic handler number error Cyclic handler undefined Context error (issued from non-task)

#include "scdef.h"#define CYH_NO 1TASK task1(){ T_CYHS status ;

cyh_sts(&status, CYH_NO) ;:

}

#include scdef.inc.IMPORT cyh_sts

CYH_NO .equ 1.SECTION T_DATA, DATA, ALIGN=2

status .RES.B 6


mov a, #BNKSYM(status) ; Cyclic handler informationmov adb, a ; storage addressmovw a, #status mv a, #CYH_NO ; Cyclic handler numberscall cyh_stsbnz error

:

249


250

4.8.6 def_alm (Define Alarm Handler)

This system call defines a task-independent section handler that is executed after a fixed period of time.



Format: ER ercd = def_alm(HNO alhno, T_ALH ∗pk_alh);typedef struct t_alh { T_TIME time ; FP almhdr ; UINT tmode ;} T_ALH ;typedef struct t_time { UW ltime ; UH utime ;} T_TIME ;

Note: The structures "T_ALH" and "T_TIME" are defined in the header file.

Input parameters: alhno Alarm handler number pk_alh Pointer for alarm handler setting information area

NADR: Setting released pk_alh->time, ltime Execution time (low-order 32 bits) pk_alh->time, utime Execution time (high-order 16 bits) pk_alh->almhdr Alarm handler start address pk_alh->tmmode Time specification mode

(only TTM_ABS is valid)



Input parameters: ADB:AH NADR(0): Alarm handler setting cancellation or (also set "0" in ADB)

AL Alarm handler number

System call: scall def_alm


•ZF 0: Error end AL Error code

timealmhdr

ADB:AH+0+6

+10

Address of alarm handler setting information area (12 bytes)Execution time (48 bits)

Alarm handler start address Specification mode (only TTM_ABS is valid) tmmode

+12


<Error codes>

<Dispatch causes>


<Description>

This system call defines the specified alarm handler. This definition causes the alarm handler to be executed at the specified time. The alarm handler program is executed at the non-task level, and is terminated by the "ret_tmr" system call.

If NADR is specified for the alarm handler setting information area address, the alarm handler that has already been set is released.

For the alarm handler number, specify a number from 1 to the maximum number of alarm handlers that can be registered. The maximum number of alarm handlers that can be registered is set in the Configurator.

The alarm handler setting information includes the time at which the handler is executed and the starting address of the handler to be initiated. The starting time is specified in terms of a 6-byte system clock value. The handler address is specified as a 32-bit address, including the bank address.

For the time specification mode, specify the absolute time specification mode ("TTM_ABS"). Because Softune REALOS/907 does not support the relative time support function, "E_NOSPT" is returned if relative time specification mode ("TTM_REL") is specified.

The "def_alm" setting is released when the alarm handler is executed.

If the time that is set is in the past compared to the system clock's current time, "E_ILTIME" is returned.

The alarm handler interrupt level (ILM value) is the interrupt level of the timer interrupt being used by the system clock.

If the alarm handler number that is specified exceeds the maximum value or is a negative value, "E_PAR" is returned.

If a value other than one defined as a label is specified for the initial time specification mode, "E_RSMD" is returned.

If the alarm handler is not registered in the Configurator, or if the system clock is not supported, "E_TNOSPT" is returned.


E_OKE_TNOSPTE_NOSPTE_RSMDE_PARE_ILTIMEE_CTX

0-19-17-22-33-37-69

Normal end Timer not supported "TTM_REL" was specified (unsupported function) Label other than "TTM_ABS" and "TTM_REL" was specified Alarm handler number error Time that is already in past was specified Context error (issued from non-task)

251


252

<Examples>



#include "scdef.h"

T_ALH alm_info = { {0x12345678L, 0} , alarm, TTM_ABS} ;

TASK task1(){ def_alm(1, &alm_info) ; /∗ Alarm handler definition ∗/

:}#pragma register(1)__interrupt ALMHDR alarm() /∗ Alarm handler ∗/{

: ret_tmr() ;}#pragma noregister

#include scdef.inc.IMPORT def_alm, ret_tmr

ALH_NO .equ 1:

.SECTION T_DATA, DATA, ALIGN=2alm_info .DATA.H h’5678

.DATA.H h’1234

.DATA.H h’0000

.DATA.L alarm

.DATA.H TTM_ABS


mov a, #BNKSYM(alm_info) ; Address of alarm handler mov adb, a ; setting informationmovw a, #alm_infomv a, #ALH_NO ; Alarm handler numberscall def_almbnz error

:alarm: ; Alarm handler

:scall ret_tmr ; Terminates alarm handler

:

253

MEMO


254

4.8.7 alh_sts (Get Alarm Handler Status)

This system call references the status of an alarm handler.-91 Task section Task independent section ×


Format: ER ercd = alh_sts(T_TIME ]p_lftime, HNO alhno);typedef struct t_time { T_TIME time ; UWl time ; UHu time ;} T_TIME ;

Input parameters: p_lftime Pointer for area (6 bytes) storing the time remaining until the next handler execution

alhno Alarm handler number

Output parameters: ercd Error code (E_OK: normal) ∗p_lftime Time remaining until next handler execution p_lftime->ltime Low-order 4 bytes p_lftime->utime High-order 2 bytes


Input parameters: ADB:AH Pointer for area (6 bytes) storing the time remaining until the next handler execution

AL Alarm handler number

System call: scall alh_sts

Output parameters: •ZF 1: Normal end AL E_OK


<Error codes>


E_OKE_TNOSPTE_PARE_NOEXSE_CTX

0-19-33-42-69

Normal end Timer not supported Alarm handler number error Alarm handler undefined Issued from non-task section

ltimeutime

ADB:AH+0+4+6

Address where time remaining until the next handler execution is stored Low-order 4 bytes High-order 2 bytes


<Dispatch causes>


<Description>

This system call returns the time remaining until the specified alarm handler is executed. If the specified alarm handler is undefined, "E_NOEXS" is returned.

If this system call is issued from the non-task section, "E_CTX" is returned.

If the alarm handler number that is specified exceeds the maximum value or is a negative value, "E_PAR" is returned.

If the alarm handler is not registered in the configurator or the system clock is not set up, E_TNOSPT is returned.

This system call references the status of the specified alarm handler.

<Examples>



#include "scdef.h"

TASK task1() { T_TIME lftime ;

alh_sts(&lftime, 1) ;:

}

#include scdef.inc.IMPORT alh_sts


lftime .RES.H 3


mov a, #BNKSYM(lftime) ; Bank for address where remainingmov adb, a ; time is storedmovw a, #lftime ; Address where remaining time is storedmv a, #1scall alh_stsbnz error

:

255


256

4.8.8 ret_tmr (Return from Timer Handler)

This system call returns from a timer handler.Task section × Task independent section


Format: void ret_tmr(void) ;


Output parameters: Control does not return to source of call


Input parameters: SP State when timer handler started up

System call: scall ret_tmr

Output parameters: Control does not return to source of call

<Error codes>

None

Note: No error checking is performed.

<Dispatch causes>


<Description>

The "ret_tmr" system call is issued when terminating a timer handler (a cyclic handler or an alarm handler). Because "ret_tmr" terminates the interrupt processing itself, control does not return to the source of this system call. When terminating a timer handler, always issue "ret_tmr" not the "reti" instruction.

When writing the timer handler in assembly language, it is necessary, before issuing "ret_tmr", to restore the system stack pointer (SP) to its value that it had at the start of interrupt processing. For example, operation is not guaranteed if, as part of the interrupt processing, the "ret_tmr" system call is executed from inside a subroutine called by the "call" instruction or another such instruction. Before this system call is issued, the level of the stack must be restored to the level it had at the start of the timer handler. In addition, when the memory register was used as a work register, before this call is issued the memory register must also be restored to the value that it had.

When writing the timer handler in C, issue "ret_tmr()" within a function declared with the "__interrupt" qualifier. As a matter of fact, the "ret_tmr()" is replaced with the "return" statement. Issuing "ret_tmr()" from a function called by the timer handler creates a subroutine instruction to return to the timer handler. As a result, the timer handler is not terminated by the issuance of "ret_tmr()" from a function called by the timer handler.


The "ret_tmr" system call can only be issued from a cyclic handler or an alarm handler. It cannot be issued from the initialization handler, an interrupt handler, or a task.

The "ret_tmr" system call is replaced by equivalent processing during macro expansion in both assembly language and in C.

When a system call is issued in a timer handler and the task status is changed, the scheduling function passes execution authority to the task with the highest priority level. (The task that was running before the interrupt occurred is preempted.)

When this system call is executed, control does not return to the source of this call.

The "ret_wup" system call can also be used to terminate timer handlers.

<Examples>



#include "scdef.h"#defineWUP_TSK_ID 2

#pragma register(3)

__interrupt CYCHDR timer_hnd(){ wup_tsk(WUP_TSK_ID) ;

ret_tmr() ; /∗ Terminates a cyclic handler ∗/}#pragma noregister

#include scdef.inc.IMPORT wup_tsk, ret_tmr

WUP_TSK_ID .equ 2:

pushw rwl ; Changes the stack pointermv a, #WUP_TSK_IDscall wup_tsk

:popw rwl ; Restores the stack pointerscall ret_tmr ; Terminates the timer handler

257


4.9 System Management Function System Call

There is one system management function call:• get_ver

� System Management Function System Call

There is one system management function call:

� get_ver (Get Version No.)

This system call gets the ITRON version number.

258

259

MEMO


260

4.9.1 get_ver (Get Version No.)

This system call gets the ITRON version number.-16 Task section Task independent section


Format: ER ercd = get_ver(T_VER ∗pk_ver) ;struct t_ver{

UH maker ;UH id ;UH spver ;UH prver ;UH prno[4] ;UH cpu ;UH var ;

} T_VER

Note: The structure "T_VER" is defined in the header file.

Input parameters: pk_ver Pointer for area (20 bytes) where version information is to be stored

Output parameters: ercd Error code


Input parameters: ADB:AL Starting address of area (20 bytes) where version information is to be stored

System call: scall get_ver

Output parameters: •ZF 1: Normal end AL E_OK

OS manufacturer OS ID number Version number for ITRON, µITRON specifications OS product version number Product number, product control information CPU information Variation descriptor

makerid

spverprverprnocpuvar

Version number storage area + 0+2+4+6+8

+16+18+20

261

<Version information>

Organization

Settings

<Error codes>

Parameter Contents Setting Setting code

MAKER Manufacturer FUJITSU 9

ID OS identifier Softune REALOS/907 H’50

MAGIC TRON ID code µITRON 5

SpecVer µITRON version number to which version conforms µITRON Ver 2.01 h’201

MAJOR Kernel version numberV30LXX

30

MINOR Kernel version level XX

prno[0 to 3] Product control number ∗ ∗

CPU CPU ID code F2MC-16L/16LX/16/16H/16F series h’07

LEV Kernel specification level grouping µITRON 000

M Single-processor/multiprocessor Single processor 0

V Virtual memory support No support 0

P MMU support No support 0

FIL File specifications level No support 0

IO I/O specifications level No support 0

∗ : No fixed value


E_OK 0 Normal end

bit 15 bit 0

byte 20

024681012141618

makeridspverprverprno

cpuvar

0 0 0 0 0 0 0 0 MAKER

MAGIC

MAJOR MINOR

SpecVer

prno[0]

prno[1]

prno[2]

prno[3]

MAKER CPU

– – M V P – –LEV FIL – –IO

ID

262

<Dispatch causes>


<Description>

This system call returns information (20 bytes) on the OS version currently running.

<Example>



#include "scdef.h"

TASK task1(){ T_VER ver ;

: get_ver(&ver) ; if(ver.cpu != 0x907) {

: }

:}

#include scdef.inc.IMPORT get_ver


ver .RES.B 20


mov a, #BNKSYM(ver); Address of information storage areamov adb, amovw a, #verscall get_ver

:

APPENDIX

The appendices include lists of system calls, error codes, and function codes.

Appendix A System Call List

Appendix B Error Code List

Appendix C Function Code List

Appendix D C Language Interface Data Type List

Appendix E C Language Interface Parameter Name List

Appendix F C Compiler Extended Specifications

263

264

MEMO


265


This appendix lists the system calls for the assembler interface and the C interface.

A.1 Assembler Interface

A.2 C Interface

APPENDIX

A.1 Assembler Interface

The system calls for the assembler interface are listed in Table A.1a by function and are listed in Table A.1b alphabetically.

� Assembler Interface List (by Function)

Table A.1a Assembler Interface List (by Function)

Note: Numbers in parentheses indicate the size (in bytes) of the parameter.

Function System call name Inputs Outputs Description

sta_tsk AL tskid AL ercd Starts a task.

ext_tsk – – Terminates the current task.

ter_tsk AL tskid AL ercd Forcibly terminates another task.

chg_pri AL tskidAH tskpri AL ercd Changes the priority level of a task.

rot_rdq AL tskpri AL ercd Rotates the task ready queue.

get_tid – AL ercd Gets the current task's own ID number.

tsk_sts AL tskidADB:AH pk_tsks

AL ercd@ADB:AH+0 tskstat(1)@ADB:AH+1 tskpri(1)

Gets the task status.

sus_tsk AL tskid AL ercd Moves a task into the SUSPEND state.

rsm_tsk AL tskid AL ercd Resumes a task that was in the SUSPEND state.

frsm_tsk AL tskid AL ercd Forcibly resumes a task that was in the SUSPEND state.

slp_tsk – AL ercd Moves a task into the WAIT state.

wai_tsk AL tmout AL ercd Moves a task into the WAIT state for a certain period of time.

wup_tsk AL tskid AL ercd Wakes up a task in the WAIT state.

can_wup AL tskidAL p_wupcntAL ercd(if an error occurs)

Cancels a task wake-up request.

sig_sem AL semid AL ercd Semaphore signal operation.

wai_sem AL semid AL ercd Waits for a semaphore.

preq_sts AL semid AL ercd Gets a semaphore resource.

sem_sts AL semidADB:AH pk_sems

AL ercd@ADB:AH+0 semcnt(2)@ADB:AH+2 wtskid(2)

References the status of a semaphore.

set_flgAL flgid AL ercd Sets a 1-bit eventflag.

AL flgidAH setptn AL ercd Sets a 16-bit eventflag.

clr_flgAL flgid AL ercd Clears a 1-bit eventflag.

AL flgidAH clrptn AL ercd Clears a 16-bit eventflag.

Task

man

agem

ent

Task

dep

ende

ntsy

nchr

oniz

atio

n

Sync

hron

izat

ion/

Com

mun

icat

ions

Sem

apho

res

Eve

ntfla

gs

266


Table A.1a Assembler Interface List (by Function) (continued)



wai_flg

AL flgid AL ercd Waits for a 1-bit eventflag (and does not clear the flag).

AL flgidADB:AH pk_wflg@ADB:AH+0(2) waiptn@ADB:AH+2(2) wfmode

AL waiptn

AL ercd (if an error occurs)

Waits for a 16-bit eventflag.

cwai_flg AL flgid AL ercd Waits for a 1-bit eventflag (and clears the flag).

pol_flg

AL flgid AL ercd Gets a 1-bit eventflag (and does not clear the flag).

AL flgidADB:AH pk_wflg@ADB:AH+0(2) waiptn@ADB:AH+2(2) wfmode

AL waiptn

AL ercd (if an error occurs)

Gets a 16-bit eventflag.

cpol_flg AL flgid AL ercd Gets a 1-bit eventflag (and clears the flag).

flg_sts AL flgidADB:AH pk_flgs

AL ercd@ADB:AH+0 flgptn(2)@ADB:AH+2 wtskid(2)

References the status of a 1-bit/16-bit eventflag.

snd_msg AL mbxidADB:AH pk_msg AL ercd Sends a message to a mailbox.

rcv_msg AL mbxidADB:AL pk_msgAL ercd (if an error occurs)

Receives a message from a mailbox.

prcv_msg AL mbxidADB:AL pk_msgAL ercd (if an error occurs)

Waits to receive a message from a mailbox.

mbx_sts AL mbxidADB:AH pk_mbxs

AL ercd@ADB:AH+0 pk_msg(4)@ADB:AH+4 wtskid(2)

References the status of a mailbox.

ret_int SP – Returns from an interrupt handler.

ret_wup AL tskidSP – Returns from interrupt processing and wakes up

a task.

chg_ilv AL intnoAL intlv AL ercd Changes an interrupt level.

ilv_sts AL intnoAL intlvAL ercd (if an error occurs)

References an interrupt level.

get_blk AL mplidADB:AL blkAL ercd (if an error occurs)

Waits to get a fixed-length memory block.

pget_blk AL mplidADB:AL blkAL ercd (if an error occurs)

Gets a fixed-length memory block.

rel_blk AL mplidADB:AH blk AL ercd Releases a fixed-length memory block.

Sync

hron

izat

ion/

Com

mun

icat

ions Ev

entfl

ags

Mai

lbox

esIn

terr

upt m

anag

emen

tM

emor

ypoo

l m

anag

emen

t

267

APPENDIX

268

Table A.1a Assembler Interface List (by Function) (continued)



mpl_sts ALmplidADB:AH pk_mpls

AL ercd@ADB:AH+0 blksz (2)@ADB:AH+2 mplsz (2)@ADB:AH+4 frbcnt (2)@ADB:AH+6 wtskid (2)

References the status of a memorypool.

set_tim ADB:AL pk_time*@ADB:AL time (6) AL ercd Sets the system clock.

get_tim ADB:AL pk_time @ADB:AL time (6) Reads the system clock value.

def_cyc

ALcyhnoADB:AH pk_cyn@ADB:AH+0 cytime (2)@ADB:AH+2 cychdr (4)@ADB:AH+6 cyhact (2)

AL ercd Defines a cyclic handler.

act_cyc AL cyhnoAH cyhact AL ercd Controls the activation status of a cyclic handler.

cyh_sts AL cyhnoADB:AH pk_cyhs

AL ercd@ADB:AH+0 cytime (2)@ADB:AH+2 lftime (2)@ADB:AH+4 cyhact (2)

References the status of a cyclic handler.

def_alm

AL alhnoADB:AH pk_alh@ADB:AH+0 time (6)@ADB:AH+6 almhdr (4)@ADB:AH+10 tmmode (2)

AL ercd Defines an alarm handler.

alh_sts AL alhnoADB:AL pk_lftime

AL ercd@ADB:AH+0 lftime (6) References the status of an alarm handler.

ret_tmr SP – Returns from a timer handler.

get_ver ADB:AL pk_ver

@ADB:AH+0 maker (2)@ADB:AH+2 id (2)@ADB:AH+4 spver (2)@ADB:AH+6 prver (2)@ADB:AH+8 prno (8)@ADB:AH+10 cpu (2)@ADB:AH+12 var (2)

Gets the version number.

Mem

oryp

ool

man

agem

ent

Tim

e m

anag

emen

tSy

stem

man

agem

ent


� Assembler Interface List (in Alphabetical Order)

Table A.1b Assembler Interface List (in Alphabetical Order)


System call name Inputs Outputs Description

act_cyc AL cyhnoAL cyhact AL ercd Controls the activation status of a cyclic handler.

alh_sts AL alhnoADB:AH pk_lftime

AL ercd@ADB:AH+0 lftime (6) References the status of an alarm handler.

can_wup AL tskid AL ercd or AL p_wupcntAL ercd(if an error occurs) Cancels a task wake-up request.

clr_flg AL flgid AL ercd Clears a 1-bit eventflag.

clr_flg AL flgidAH clrptn AL ercd Clears a 16-bit eventflag.

chg_ilv AL intnoAH intlv AL ercd Changes an interrupt level.

chg_pri AL tskidAH tskpri AL ercd Changes the priority level of a task.

cpol_flg AL flgid AL ercd Gets a 1-bit eventflag (and clears the flag).

cyh_sts AL cyhnoADB:AH pk_cyhs

AL ercd@ADB:AH+0 cytime (2)@ADB:AH+2 lftime (2)@ADB:AH+4 cyhact (2)

References the status of a cyclic handler.

cwai_flg AL flgid AL ercd Waits for a 1-bit eventflag (and clears the flag).

def_alm

AL alhnoADB:AH pk_alh@ADB:AH+0 time (6)@ADB:AH+6 almhdr (4)@ADB:AH+10 tmmode (2)

AL ercd Defines an alarm handler.

def_cyc

AL cyhnoADB:AH pk_cyh@ADB:AH+0 cytime (2)@ADB:AH+2 cychdr (4)@ADB:AH+6 cyhact (2)

AL ercd Defines a cyclic handler.

ext_tsk – – Terminates the current task.

269

APPENDIX

270

Table A.1b Assembler Interface List (in Alphabetical Order) (continued)




AL ercd@ADB:AH+0 flgptn (2)@ADB:AH+2 wtskid (2)

References the status of a 1-bit eventflag.


AL ercd@ADB:AH+0 flgptn (2)@ADB:AH+2 wtskid (2)

References the status of a 16-bit eventflag.

frsm_tsk AL tskid Al ercd Forcibly resumes a task that was in the SUSPEND state.

get_blk AL mplid ADB:AL blkAL ercd (if an error occurs) Waits to get a fixed-length memory block.

get_tid – AL tskid Gets the current task's own ID number.

get_tim ADB:AL pk_time @ADB:AL time (6) Reads the system clock value.

get_ver ADB:AL pk_ver

@ADB:AH+0 maker (2)@ADB:AH+2 id (2)@ADB:AH+4 spver (2)@ADB:AH+6 orver (2)@ADB:AH+8 prno (8)@ADB:AH+10 cpu (2)@ADB:AH+12 var (2)

Gets the version number.

ilv_sts AL intno AL intlvAL ercd (if an error occurs) References an interrupt level.

mbx_sts AL mbxidADB:AH pk_mbxs

AL ercd@ADB:AH+0 pk_msg (4)@ADB:AH+4 wtskid (2)

References the status of a mailbox.

mpl_sts AL mplidADB:AH pk_mpls

AL ercd@ADB:AH+0 blksz (2)@ADB:AH+2 mplsz (2)@ADB:AH+4 frbcnt (2)@ADB:AH+6 wtskid (2)

References the status of a memorypool.

pget_blk AL mplid ADB:AL blkAL ercd (if an error occurs) Gets a fixed-length memory block.

pol_flg AL flgid AL ercd Gets a 1-bit eventflag (and does not clear the flag).

pol_flg

AL flgidADB:AH pk_wflg@ADB:AH+0 (2) waiptn@ADB:AH+2 (2) wfmode

AL waiptnAL ercd(if an error occurs) Gets a 16-bit eventflag (and does not clear the flag).





prcv_msg AL mbxid ADB:AL pk_msgAL ercd (if an error occurs) Receives a message from a mailbox.

preq_sem AL semid AL ercd Gets a semaphore resource.

rcv_msg AL mbxid ADB:AL pk_msgAL ercd (if an error occurs) Waits to receive a message from a mailbox.

rel_blk AL mplidADB:AH blk AL ercd Releases a fixed-length memory block.

ret_int SP – Returns from an interrupt handler.

ret_tmr SP – Returns from a timer handler.

ret_wup AL tskidSP Returns from interrupt processing and wakes up a task.

rot_rdq AL tskpri AL ercd Rotates the task ready queue.

rsm_tsk AL tskid AL ercd Resumes a task that was in the SUSPEND state.

sem_sts AL semidADB:AH pk_sems

AL ercd@ADB:AH+0 semcnt (2)@ADB:AH+2 wtskid (2)

References the status of a semaphore.

set_flg AL flgid AL ercd Sets a 1-bit eventflag.

set_flg AL flgidAH setptn AL ercd Sets a 16-bit eventflag.

set_tim ADB:AL pk_time@ADB:AL time (6) AL ercd Sets the system clock.

sig_sem AL semid AL ercd Semaphore signal operation.

slp_tsk – AL ercd Moves a task into the WAIT state.

snd_msg AL mbxidADB:AH pk_msg AL ercd Sends a message to a mailbox.

sta_tsk AL tskid AL ercd Starts a task.

sus_tsk AL tskid AL ercd Moves a task into the SUSPEND state.

ter_tsk AL tskid AL ercd Forcibly terminates another task.

tsk_sts AL tskidADB:AH pk_tsks

AL ercd @ADB:AH+0 tskstat (1)@ADB:AH+1 tskpri (1)

Gets the task status.

wai_flg AL flgid AL ercd Waits for a 1-bit eventflag (and does not clear the flag).

271

APPENDIX

272




wai_flg

AL flgidADB:AH pk_wflg@ADB:AH+0 (2) waiptn@ADB:AH+2 (2) wfmode

AL waiptnAL ercd (if an error occurs) Waits for a 16-bit eventflag.

wai_sem AL semid AL ercd Waits for a semaphore.

wai_tsk AL tmout AL ercd Moves a task into the WAIT state for a certain period of time.

wup_tsk AL tskid AL ercd Wakes up a task in the WAIT state.


273

A.2 C Interface

The system calls for the C interface are listed in Table A.2a by function and are listed in Table A.2b alphabetically.

� C Interface List (by Function)

Table A.2a C Interface List (by Function)

Function C interface Description

ER ercd = sta_stk(ID tskid) ; Starts a task.

void ext_tsk(void) ; Terminates the current task.

ER ercd = ter_tsk(ID tskid) ; Forcibly terminates another task.

ER ercd = chg_pri(ID tskid,TPRI tskpri) ; Changes the priority level of a task.

ER ercd = rot_rdq(TPRI tskpri) ; Rotates the task ready queue.

ER ercd = get_tid(ID ∗p_tskid) ; Gets the current task's own ID number.

ER ercd = tsk_sts(T_TSKS ∗pk_tsks, ID tskid); Gets the task status.

ER ercd = sus_tsk(ID tskid) ; Moves a task into the SUSPEND state.

ER ercd = rsm_tsk(ID tskid) ; Resumes a task that was in the SUSPEND state.

ER ercd = frsm_tsk(ID tskid) ; Forcibly resumes a task that was in the SUSPEND state.

ER ercd = slp_tsk(void) ; Moves a task into the WAIT state.

ER ercd = wai_tsk(TMO tmout) ; Moves a task into the WAIT state for a certain period of time.

ER ercd = wup_tsk(ID tskid) ; Wakes up a task in the WAIT state.

ER ercd = can_wup(INT ∗p_wupcnt, ID tskid) ; Cancels a task wake-up request.

ER ercd = sig_sem(ID semid) ; Semaphore signal operation.

ER ercd = wai_sem(ID semid) ; Waits for a semaphore.

ER ercd = preq_sem(ID semid) ; Gets a semaphore resource.

ER ercd = sem_sts(T_SEMS ∗pk_sems, ID semid) ; References the status of a semaphore.

ER ercd = set_flg(ID flgid) ; Sets a 1-bit eventflag.

ER ercd = set_flg(ID flgid, UINT setptn) ; Sets a 16-bit eventflag.

ER ercd = clr_flg(ID flgid) ; Clears a 1-bit eventflag.

ER ercd = clr_flg(ID flgid, UINT clrptn) ; Clears a 16-bit eventflag.

ER ercd = wai_flg(ID flgid) ; Waits for a 1-bit eventflag (and does not clear the flag).

ER ercd = wai_flg(UINT ∗p_flgptn, ID flgid, UINT waiptn, UINT wfmode) ;


ER ercd = cwai_flg(ID flgid) ; Waits for a 1-bit eventflag (and clears the flag).

ER ercd = pol_flg(ID flgid) ; Gets a 1-bit eventflag (and does not clear the flag).

Task

Man

agem

ent

Task

Dep

ende

ntSy

nchr

oniz

atio

n

Syn

chro

niza

tion/

Com

mun

icat

ions

Sem

apho

res

Even

tflag

s

APPENDIX

274

Table A.2a C Interface List (by Function) (continued)

Function C interface Description

ER ercd = pol_flg(UNIT ∗p_flgptn, ID flgid, UINT waiptn, UINT wfmode) ;


ER ercd = cpol_flg(ID flgid) ; Gets a 1-bit eventflag (and clears the flag).

ER ercd = flg_sts(T_FLGS ∗pk_flgs, ID flgid) ; References the status of a 1-bit/16-bit eventflag.

ER ercd = snd_msg(ID mbxid, T_MSG FAR ∗pk_msg) ;

Sends a message to a mailbox.

ER ercd = rcv_msg(T_MSG FAR ∗∗ppk_msg, ID mbxid) ;

Waits to receive a message from a mailbox.

ER ercd = prcv_msg(T_MSG FAR ∗∗ppk_msg, ID mbxid) ;

Receives a message from a mailbox.

ER ercd = mbx_sts(T_MBXS, ∗pk_mbxs, ID mbxid) ; References the status of a mailbox.

void ret_int(void) ; Returns from an interrupt handler.

void ret_wup(ID tskid) ; Returns from interrupt processing and wakes up a task.

ER ercd = chg_ilv(UINT intno, UINT intlv) ; Changes an interrupt level.

ER ercd = ilv_sts(UINT ∗p_intlv, UINT intno) ; References an interrupt level.

ER ercd = get_blk(void FAR ∗∗p_blk, ID mplid) ; Waits to get a fixed-length memory block.

ER ercd = pget_blk(void FAR ∗∗p_blk, ID mplid) ; Gets a fixed-length memory block.

ER ercd = rel_blk(ID mplid, void FAR ∗blk) ; Releases a fixed-length memory block.

ER ercd = mpl_sts(T_MPLS ∗pk_mpls, ID mplid) ; References the status of a memorypool.

ER ercd = set_tim(T_TIME ∗pk_time) ; Sets the system clock.

ER ercd = get_tim(T_TIME ∗pk_time) ; Reads the system clock value.

ER ercd = def_cyc(HNO cyhno, T_CYH ∗pk_cvh) ; Defines a cyclic handler.

ER ercd = act_cyc(HNO cyhno, UINT cyhact) ; Controls the activation status of a cyclic handler.

ER ercd = cyn_sts(T_CYHS ∗pk_cyhs, HNO cyhno) ; References the status of a cyclic handler.

ER ercd = def_alm(HNO alhno, T_ALH ∗pk_alh) ; Defines an alarm handler.

ER ercd = alh_sts(T_TIME ∗p_lftime, HNO alhno) ; References the status of an alarm handler.

void ret_tmr(void) ; Returns from a timer handler.

ER ercd = get_ver(T_VER ∗pk_ver) ; Gets the version number.

Sync

hron

izat

ion/

Com

mun

icat

io

Even

tflag

sM

ailb

oxes

Inte

rrupt

m

anag

emen

tM

emor

ypoo

lm

anag

emen

tTi

me

man

agem

ent

Syst

emm

anag

emen

t


� C Interface List (in Alphabetical Order)

Table A.2b C Interface List (in Alphabetical Order)

C interface Description

ER ercd = act_cyc(HNO cyhno, UINT cyhact) ; Controls the activation status of a cyclic handler.

ER ercd = alh_sts(T_TIME ∗p_lftime, HNO alhno) ; References the status of an alarm handler.

ER ercd = can_wup(INT ∗p_wupcnt, ID tskid) ; Cancels a task wake-up request.

ER ercd = chg_ilv(UINT intno, UINT intlv) ; Changes an interrupt level.

ER ercd = chg_pri(ID tskid,TPRI tskpri) ; Changes the priority level of a task.

ER ercd = clr_flg(ID flgid) ; Clears a 1-bit eventflag.

ER ercd = clr_flg(ID flgid, UINT clrptn) ; Clears a 16-bit eventflag.

ER ercd = pol_flg(ID flgid) ; Gets a 1-bit eventflag (and clears the flag).

ER ercd = cwai_flg(ID flgid) ; Waits for a 1-bit eventflag (and clears the flag).

ER ercd = cyh_sts(T_CYHS ∗pk_cyhs, HNO cyhno) ; References the status of a cyclic handler.

ER ercd = def_alm(HNO alhno, T_ALH ∗pk_alh) ; Defines an alarm handler.

ER ercd = def_cyc(HNO cyhno, T_CYH ∗pk_cvh) ; Defines a cyclic handler.

void ext_tsk(void) ; Terminates the current task.

ER ercd = flg_sts(T_FLGS ∗pk_flgs, ID flgid) ; References the status of a 1-bit/16-bit eventflag.

ER ercd = frsm_tsk(ID tskid) ; Forcibly resumes a task that was in the SUSPEND state.

ER ercd = get_blk(void FAR ∗∗p_blk, ID mplid) ; Waits to get a fixed-length memory block.

ER ercd = get_tid(ID ∗p_tskid) ; Gets the current task's own ID number.

ER ercd = get_tim(T_TIME ∗pk_time) ; Reads the system clock value.

ER ercd = get_ver(T_VER ∗pk_ver) ; Gets the version number.

ER ercd = ilv_sts(UINT ∗p_intlv, UINT intno) ; References an interrupt level.

ER ercd = mbx_sts(T_MBXS, ∗pk_mbxs, ID mbxid) ; References the status of a mailbox.

ER ercd = mpl_sts(T_MPLS ∗pk_mpls, ID mplid) ; References the status of a memorypool.

ER ercd = pget_blk(void FAR ∗∗p_blk, ID mplid) ; Gets a fixed-length memory block.

ER ercd = pol_flg(ID flgid) ; Gets a 1-bit eventflag (and does not clear the flag).

ER ercd = pol_flg(UINT ∗p_flgptn, ID flgid, UINT waiptn, UINT wfmode) ;


ER ercd = prcv_msg(T_MSG FAR ∗∗ppk_msg, ID mbxid) ; Receives a message from a mailbox.

ER ercd = preq_sem(ID semid) ; Gets a semaphore resource.

ER ercd = rcv_msg(T_MSG FAR ∗∗ppk_msg, ID mbxid) ; Waits to receive a message from a mailbox.

275

APPENDIX

276

Table A.2b C Interface List (in Alphabetical Order) (continued)

C interface Description

ER ercd = rel_blk(ID mplid, void FAR ∗blk) ; Releases a fixed-length memory block.

void ret_int(void) ; Returns from an interrupt handler.

void ret_tmr(void) ; Returns from a timer handler.

void ret_wup(ID tskid) ; Returns from interrupt processing and wakes up a task.

ER ercd = rot_rdq(TPRI tskpri) ; Rotates the task ready queue.

ER ercd = rsm_tsk(ID tskid) ; Resumes a task that was in the SUSPEND state.

ER ercd = sem_sts(T_SEMS ∗pk_sems, ID semid) ; References the status of a semaphore.

ER ercd = set_flg(ID flgid) ; Sets a 1-bit eventflag.

ER ercd = set_flg(ID flgid, UINT setptn) ; Sets a 16-bit eventflag.

ER ercd = set_tim(T_TIME ∗pk_time) ; Sets the system clock.

ER ercd = sig_sem(ID semid) ; Semaphore signal operation.

ER ercd = slp_tsk(void) ; Moves a task into the WAIT state.

ER ercd = snd_msg(ID mbxid, T_MSG FAR ∗pk_msg) ; Sends a message to a mailbox.

ER ercd = sta_stk(ID tskid) ; Starts a task.

ER ercd = sus_tsk(ID tskid) ; Moves a task into the SUSPEND state.

ER ercd = ter_tsk(ID tskid) ; Forcibly terminates another task.

ER ercd = tsk_sts(T_TSKS ∗pk_tskid) ; Gets the task status.

ER ercd = wai_flg(ID flgid) ; Waits for a 1-bit eventflag (and does not clear the flag).

ER ercd = wai_flg(UINT ∗p_flgptn, ID flgid, UINT waiptn, UINT wfmode) ;


ER ercd = wai_sem(ID semid) ; Waits for a semaphore.

ER ercd = wai_tsk(TMO tmout) ; Moves a task into the WAIT state for a certain period of time.

ER ercd = wup_tsk(ID tskid) ; Wakes up a task in the WAIT state.


277


Table B lists the error codes.

� Error Code List

Table B Error Code List

Error label Decimal code

Hexadecimal code Description

E_OKE_NOSPTE_TNOSPTE_RSMDE_RSIDE_PARE_IDOVRE_ILTIMEE_TPRIE_VECNE_SELFE_EXSE_NOEXSE_DMTE_NODMTE_NOSUSE_ILBLKE_CTXE_QOVRE_TMOUTE_PLFAIL

0-17-19-22-23-33-35-37-38-42-49-51-52-53-54-56-59-69-74-85-89

000FFEFFFEDFFEAFFE9FFDFFFDDFFDBFFDAFFD6FFCFFFCDFFCCFFCBFFCAFFC8FFC5FFBBFFB6FFABFFA7

Normal end Unsupported function is specified or specified object is not supportedTimer function not supported Reserved mode or reserved option specified Reserved ID specified Parameter error ID specified out of range Specified time is in error Task priority level specification error Illegal vector number specified Current task cannot be specified Object already exists Object does not exist Specified task is in DORMANT state Specified task is not in DORMANT state Specified task is not in SUSPEND state Bad memory block address Context error Queue overflow Terminated due to time-out Polling failure

APPENDIX


The function code assignments are listed in Table Ca, and the function codes are listed in Tables Cb and Cc.

� Function Code Assignment List

Table Ca Function Code Assignment List

+H’0 +H’4 +H’8 +H’C

H’FF30

-208 to -193

Polling function p p p c--- --- --- get rcv req pol pol--- --- --- blk msg sem flg flg

--- --- --- --- --- --- --- ------ --- --- --- --- --- --- ---

H’FFA0

-96 to -81

Timer handler

--- --- act ret cyh alh def def--- --- cyc tmr sts sts cyc alm

Time management

--- --- --- --- --- get set ------ --- --- --- --- tim tim ---

H’FFB0

-80 to -65

Memorypool management

--- rel --- get mpl --- --- ------ blk --- blk sts --- --- ---

Interrupt management

--- --- ret ret ilv chg --- ------ --- wup int sts ilv --- ---

H’FFC0

-64 to -49

Mailboxes

--- snd --- rdv mbx --- --- ------ msg --- msg sts --- --- ---

Semaphores

--- sig --- wai sem --- --- ------ sem --- sem sts --- --- ---

H’FFD0

-48 to -33

Eventflags cset clr wai wai flg --- --- ---flg flg flg flg sts --- --- ---

Task-dependent synchronization fcan wup slp wai rsm rsm --- suswup tsk tsk tsk tsk tsk --- tsk

H’FFE0

-32 to -17

Task management--- --- --- --- rot chg --- ter get sta --- ext tsk --- --- ------ --- --- --- rdg pri --- tsk tid tsk --- tsk sts --- --- ---

H’FFF0

-16 to -1

System managementget --- --- ---ver --- --- ---

Reserved--- --- --- --- --- --- --- --- --- --- --- ------ --- --- --- --- --- --- --- --- --- --- ---

278


� Function Code List

Table Cb Function Code List (by Function)

Function Label Decimal code Hexadecimal code

Task management

sta_takext_tskter_tskchg_prirot_rdqtsk_stsget_tid

-23-21-25-27-28-20-24

FFE9FFEBFFE7FFE5FFE4FFECFFE8

Task-dependent synchronization

sus_tskrsm_tskfrsm_tskslp_tskwai_tskwup_tskcan_wup

-33-35-36-38-37-39-40

FFDFFFDDFFDCFFDAFFDBFFD9FFD8

Synchronization/Communications

Semaphores

sig_semwai_sempreq_semsem_sts

-55-53-203-52

FFC9FFCBFF35FFCC

Eventflags

set_flgclr_flgwai_flgcwai_flgpol_flgcpol_flgflg_sts

-48-47-46-45-202-201-44

FFD0FFD1FFD2FFD3FF36FF37FFD4

Mailboxes

snd_msgrcv_msgprcv_msgmbx_sts

-63-61-204-60

FFC1FFC3FF34FFC4

Interrupt management

ret_intret_wup ∗chg_ilvilv_sts

-69-70-67-68

FFBBFFBAFFBDFFBC

∗ : Since this is implemented using the macro function, the function code equivalent to wup_tsk is returned to the exception handler information.

279

APPENDIX

280

Table Cb Function Code List (by Function) (continued)

Table Cc Function Code List (by Code)

Function Label Decimal code Hexadecimal code

Memorypool management

get_blkpget_blkrel_blkmpl_sts

-77-205-79-76

FFB3FF33FFB1FFB4

Time management

set_timget_timdef_cycact_cyccyh_stsdef_almalh_stsret_tmr

-83-84-90-94-92-89-91-93

FFADFFACFFA6FFA2FFA4FFA7FFA5FFA3

Version management get_ver -16 FFF0

Label Decimal code Hexadecimal code

pget_blkprcv_msgpreq_sempol_flgcpol_flgact_cycret_tmrcyh_stsalh_stsdef_cycdef_almget_timset_tim

-205-204-203-202-201-94-93-92-91-90-89-84-83

FF33FF34FF35FF36FF37FFA2FFA3FFA4FFA5FFA6FFA7FFACFFAD


Table Cc Function Code List (by Code) (continued)

Label Decimal code Hexadecimal code

rel_blkget_blkmpl_stsret_wup ∗ret_intilv_stschg_ilvsnd_msgrcv_msgmbx_stssig_semwai_semsem_stsset_flgclr_flgwai_flgcwai_flgflg_stscan_wupwup_tskslp_tskwai_tskfrsm_tskrsm_tsksus_tskrot_rdqchg_priter_tskget_tidsta_tskext_ststsk_stsget_ver

-79-77-76-70-69-68-67-63-61-60-55-53-52-48-47-46-45-44-40-39-38-37-36-35-33-28-27-25-24-23-21-20-16

FFB1FFB3FFB4FFBAFFBBFFBCFFBDFFC1FFC3FFC4FFC9FFCBFFCCFFD0FFD1FFD2FFD3FFD4FFD8FFD9FFDAFFDBFFDCFFDDFFDFFFE4FFE5FFE7FFE8FFE9FFEBFFECFFF0

∗: Being implemented with the macro function, ret_wup returns the same functional code as wup_tsk to the exception handler information.

281

APPENDIX


The C language interface data types are listed below.

� Data Types Concerning the Handling of Numeric Values

typedef signed char B ; Signed 8 bitstypedef signed short H ; Signed 16 bits

typedef signed long W ; Signed 32 bits

typedef unsigned char UB ; Unsigned 8 bitstypedef unsigned short UH ; Unsigned 16 bits

typedef unsigned long UW ; Unsigned 32 bits

typedef signed char VB ; Variable data type (8 bits)typedef signed short VH ; Variable data type (16 bits)

typedef signed long VW ; Variable data type (32 bits)

typedef void ∗VP ; Pointer for variable data type

typedef void FAR (∗FP)() ; Program start address

typedef H INT ; Signed integer

typedef UH UINT ; Unsigned integer

typedef INT BOOL ; Boolean value

� Data Types Concerning Specific Parameters

typedef H ID ; ID number

typedef B TPRI ; Task priority level

typedef INT ER ; Error codetypedef UB TSTA ; Task status code

typedef UH FPTN ; Eventflag

typedef UH SCNT ; Semaphore counttypedef UH MEMSZ ; Memory size

typedef UH BCNT ; Number of memory blocks

typedef UH CY ; Cycle counttypedef UH TMO ; Time-out specification

typedef INT FN ; Function code

typedef H HNO ; Handler numbertypedef void FAR CYCHDR ; Cyclic handler type

typedef void FAR ALMHDR ; Alarm handler type

typedef void FAR INIHDR ; Initialization handler type

typedef void FAR INTHDR; Interrupt handler typetypedef void FAR EXTHDR ; Exception handler type

typedef void TASK; Task type

282


� Data Types Concerning Packets

typedef struct t_tsks {TSTA tskstat ;TPRI tskpri ;

} T_TSKS ;

Task information Task status code Task priority level

typedef struct t_sems {SCNT semcnt ;ID wtskid ;

} T_SEMS ;

Semaphore information Semaphore count Waiting task ID

typedef struct t_flgs {FPTN flgptn ;ID wtskid ;

} T_FLGS ;

1-bit eventflag information 1-bit eventflag status Waiting task ID

typedef struct t_flgs {FPTN flgptn ;ID wtskid ;

} T_FLGS ;

16-bit eventflag information Flag bit pattern Waiting task ID

typedef struct t_mbxs {T_MSG FAR ∗pk_msg ;ID wtskid ;

} T_MBXS ;

Mailbox information Message Waiting task ID

typedef struct t_msg {UW _Wrsv_00 ;VB msgcont[2] ;

} T_MSG ;

Message Kernel management information Main body of message

283

APPENDIX

284

typedef struct t_mpls {MEMSZ blksz ;MEMSZ mplsz ;BCNT frbcnt ;ID wtskid ;

} T_MPLS ;

Memorypool information Block length Size of memorypool Number of available blocks Waiting task ID

typedef struct t_cyhs {CY cytime ;CY lftime ;UINT cyhact ;

} T_CYHS ;

Cyclic handler information Cycle Time remaining until next execution Activation status

typedef struct t_time {UW ltime ;UH utime ;

} T_TIME ;

System clock area Low-order four bytes High-order two bytes

typedef struct t_cyh {CY cytime ;FP cychdr ;UINT cyhact ;

} T_CYH ;

Cyclic handler setting information Cycle Handler address Activation status

typedef struct t_alh {T_TIME time ;FP almhdr ;UINT tmmode ;

} T_ALH ;

Alarm handler setting information Time Handler address Time specification mode


typedef struct t_ver {UH maker ;UH id ;UH spver ;UH prver ;UH prno[4] ;UH cpu ;UH var ;

} T_VER ;

Version information Manufacturer code OS identifier Specification version Product version Product management information CPU ID code Variation descriptor

typedef struct t_expt {INT ersc ;INT ercd ;INT erfg ;INT tskid ;T_EXPTRG reglist ;

} T_EXPT ;

Information from when exception processing was generated Function code Error code Error flag Task ID Registers from when exception was generated

typedef struct t_exptrg {UH usp_reg ;UH ssp_reg ;UB usb_reg ;UB ssb_reg ;UH ps_reg ;UH pc_reg ;UB pcb_reg ;UB dtb_reg ;UB adb_reg ;UB dpr_reg ;UH al_reg ;UH ah_reg ;

} T_EXPTRG ;

Register context from when exception processing was generated USP registerSSP registerUSB registerSSB registerPS registerPC registerPCB registerDTB registerADB registerDPR registerAL registerAH register

285

APPENDIX

286

typedef struct t_ditb {UB ccr ;UB bank:5 ;UB ilm:3 ;FP stadr ;UB dtb_reg ;TPRI tskpri ;B FAR ∗stack ;

} T_DITB ;

Task generation information Initial CCR value Initial RP valueInitial ILM value Task start address Initial DTB value Task priority level Initial stack pointer

typedef struct t_dimb {B FAR ∗start ;MEMSZ blksz ;BCNT blkcnt ;

} T_DIMB ;

Memorypool generation information Memorypool start pointer Block length Number of blocks


287


Table E lists the C language interface parameter names.

� C Language Interface Parameter Name List

Table E C Language Interface Parameter Name List

Parameter name Meaning Parameter

name Meaning

_Wrsv_00adb_regal_regah_regalhnoalmhdrbankblkblkcntblkszccrcpucychdrcyhactcyhnocytimedpr_regdtb_regercderfgerscflgidflgptnfrbcntidilmintlvintnolftimeltimemakermbxidmplidmplszmsgcontp_blkp_intlvp_tskid

Kernel management information ADB register AL register AH register Alarm handler number Alarm handler address Initial register bank pointer Memory block address Number of blocks Memory block length Initial CCR value CPU identification code Cyclic handler address Cyclic handler activation status Cyclic handler number Cycle DPR register DTB register Error code Error flag when an exception was generated System call function code when an exception was generated 1-bit/16-bit eventflag ID 1-bit/16-bit eventflag bit pattern Number of available memory blocks OS identifier Initial interrupt level mask value Interrupt level Interrupt number Time remaining until handler executionLow-order time bytes Manufacturer code Mailbox ID Memorypool ID Memorypool size Body of message Pointer for memory block address storage area Pointer for interrupt level storage area Pointer for task ID number storage area

p_wupcntpc_regpk_alhpk_cyhpk_flgspk_mbxspk_mplspk_msgpk_semspk_timepk_tskspk_verppk_msgprnoprverps_regreglistsemcntsemidspverssb_regssp_regstackstadrstarttimetmmodetmouttskidtskpritskstatusb_regusp_regutimevarwaiptnwfmodewtskid

Pointer for wakeup request count storage area PC register Alarm handler setting information packet Cyclic handler setting information packet 1-bit/16-bit eventflag information packet Mailbox information packet Memorypool information packet Message address Semaphore information packet Time packet Task information packet Version information packet Pointer for memory packet address storage area Product management information Product version PS register Register packet when exception was generated Semaphore count Semaphore ID Specifications version SSB register SSP register Initial stack pointer Start address Memorypool start pointer Time Time specification mode Time-out count Task ID Task priority level Task status code USB register USP register High-order time bytes Variation descriptor 16-bit eventflag waiting bit pattern 16-bit eventflag waiting mode Waiting task ID

APPENDIX


The C compiler extended specifications used in Softune REALOS/907 are described below.

� "__interrupt" Qualifier

This qualifier is used when writing an initialization handler, an interrupt handler, a cyclic handler, or an alarm handler. The "__interrupt" qualifier indicates that the specified task is in the task-independent section.

A function described with the "__interrupt" qualifier operates in the same manner as a function declared in the "#pragma interrupt" and "#pragma save_reg" declarations.

� #pragma interrupt

Defines the subsequently declared function as a handler (excluding exception handlers). This declaration is used when describing an initialization handler, an interrupt handler, a cyclic handler, or an alarm handler.

For a function for which this "pragma" declaration is valid, the interpretation of the "return" statement is as an interrupt return instruction. In addition, when the stack is accessed, code that accesses the system stack is output.

� #pragma nointerrupt

Disables "#pragma interrupt" for the subsequently declared function.

� #pragma except

Defines the subsequently declared function as an exception handler. This declaration is used when writing an exception handler.

An exception handler uses the user stack when it is called from a task. However, when called form a handler (excluding another exception handler), the exception handler uses the system stack. Accordingly, within the "#pragma except" declaration, the code that is output accesses the stack bank in accordance with the value of the stack flag. Because an exception handler is terminated with the subroutine return instruction, "#pragma except" must not be described within a "#pragma interrupt" declaration.

By using this "pragma" declaration, whether creating a function that will be called from the task section or from the task-independent section, the program that is created will be executed in accordance with the stack flag value.

288


� #pragma noexcept

Disables "#pragma except" for the subsequently declared function.

� #pragma register

The subsequently declared function uses the specified register bank. This declaration is used when describing the task-independent section.

In the function entry processing, code that switches the register bank pointer is output. The task has the register bank pointer value that is used in the task definition information. However, the task-independent section is assumed to continue using the register bank that was being used when the interrupt occurred. If the interrupt occurs while the OS was running, the registers that were being used by the OS are destroyed. Therefore, the register bank pointer must be set in the task-independent section. Set the register bank pointer value to a value not being used by the OS (a value other than "1").

� #pragma noregister

Disables "#pragma register" for the subsequently declared function.

� #pragma ssb

Outputs code that uses the system stack when the subsequently declared function manipulates the stack. This declaration is used in subroutine programs that are called from the task-independent section.

A function called from the task-independent section must use the system stack. Because normal programs (with the same type of output code as tasks) output code that uses the user stack, a clear distinction is required.

� #pragma nossb

Disables "#pragma ssb" for the subsequently declared function.

289

290

MEMO

INDEX

INDEX

The index follows on the next page.This is listed in alphabetic order.

291

INDEX

Index

Numerics

16-bit eventflag wait ...............................................511-bit eventflag wait .................................................51

A

act_cyc .................................................................246alarm handler processing.......................................73alarm handler specification number .......................80alh_sts..................................................................254alhno ......................................................................80AND waiting ...........................................................52AND waiting and OR waiting (16-bit eventflag) ......52application program structure.................................12assembler interface List (by function)...................266assembler interface list (in alphabetical order).....269

C

C compiler extended specifications......................288C interface list (by function)..................................273C interface list (in alphabetical order)...................275C language.............................................................89C language interface data type list .......................282C language interface parameter name list ...........287can_wup...............................................................164changing task priority level .....................................34changing the interrupt level ....................................69chg_ilv ..................................................................232chg_pri .................................................................142clear specification (16-bit eventflag).......................52clr_flg............................................................178, 190communication .......................................................45context data............................................................17CPU exception handler and system call exception

handler .........................................................83cyclic handler control..............................................78cyclic handler processing .......................................72cyh_sts .................................................................248

D

data type used in REALOS/907 ...........................130def_alm ................................................................250def_cyc.................................................................242definition of alarm handler......................................80definition of cyclic handler ......................................76

describing a task program in assembly language.. 95describing a task program in C .............................. 95describing a timer handler program in assembly

language.................................................... 108describing a timer handler program in C.............. 108describing an exception handler in assembly

language.................................................... 112describing an exception handler in C................... 112describing the initialization handler program in

assembly language.................................... 100describing the initialization handler program in C

................................................................... 100describing the interrupt handler program in assembly

language.................................................... 104describing the interrupt handler program in C...... 104DORMANT state.................................................... 20

E

error code list ....................................................... 277event ............................................................ 9, 16, 50event-driven ....................................................... 9, 16eventflag creation................................................... 46eventflag type......................................................... 50example of a task program described in assembly

language...................................................... 99example of a task program described in C ............ 96example of a timer handler program described in

assembly language.................................... 111example of a timer handler program described in C

................................................................... 109example of an exception handler program described

in assembly language................................ 117example of an exception handler program described

in C ............................................................ 115example of an initialization handler program

described in assembly language ............... 103example of an initialization handler program

described in C............................................ 101example of an interrupt handler program described in

assembly language.................................... 107example of an interrupt handler program described in

C ................................................................ 105exception handler address..................................... 86exception handler definition ................................... 86exception handler execution .................................. 25exception handler processing ................................ 84

292

INDEX

ext_tsk.................................................................. 138external interrupt .................................................... 66

F

field of application for REALOS/907 ........................ 8FIFO................................................................. 54, 62flg_sts........................................................... 184, 200flow of memory pool management function ........... 58forced termination of other task ............................. 33frsm_tsk ............................................................... 156function code assignment list............................... 278function code list .................................................. 279

G

get_blk ................................................................. 216get_tid .................................................................. 146get_tim ................................................................. 240get_ver ................................................................. 260getting a task’s own ID number.............................. 36getting memory block............................................. 62getting memory from a memory pool by polling ..... 63getting the version number .................................... 82

H

handler ................................................................... 88handler entry name .............................................. 112handler number (timer handler number) .............. 133

I

ilv_sts ................................................................... 234information included in the TCB............................. 18initialization handler execution ............................... 22internal interrupt ..................................................... 66interrupt.................................................................. 66interrupt and interrupt handler................................ 66interrupt handler definition ..................................... 68interrupt handler execution .................................... 23interrupt handler processing .................................. 66interrupt management function system call ... 66, 227issuing sta_tsk in assembly language.................... 94issuing sta_tsk in C ................................................ 93issuing system call in assembly language ....... 90, 94issuing system call in C.......................................... 90

K

kernel ....................................................................... 9

L

list of system call ..................................................126

M

mailbox creation .....................................................46mbx_sts ................................................................210memory block ...................................................61, 62memory pool...........................................................58memory pool creation .............................................60memory pool system call ........................................58memorypool management task state transition......59mpl_sts .................................................................224

N

nest.........................................................................42note on hardware......................................................5note on programming ...............................................2note on using the debugger macro...........................4

O

object ID number ....................................................46object ID number (ID number other than task ID

number) ......................................................132operation of 16-bit eventflag ...................................50operation of 1-bit eventflag .....................................50OR waiting ..............................................................52organization of the REALOS/907 module.................9overview of application program.............................12

P

P instruction............................................................44parameter .....................................................130, 132parameter passed to the exception handler .........114pget_blk ................................................................220placing into the WAIT state.....................................40placing to the SUSPEND state ...............................42pol_flg ...........................................................182, 196polling a 16-bit eventflag.........................................51polling a 1-bit eventflag...........................................51polling message from a mailbox .............................55polling of semaphore ..............................................49prcv_msg ..............................................................208preq_sem..............................................................172priority level ............................................................16priority ranking ........................................................16program ..................................................................89program processing execution attribute .................13program type ..........................................................88

293

INDEX

Q

queue .....................................................................52

R

rcv_msg................................................................206reading the system clock........................................74READY state ..........................................................20REALOS/907 function ............................................10real-time OS .............................................................9receiving message from a mailbox.........................55referencing the interrupt level.................................69referencing the memory pool status.......................64referencing the status of a cyclic handler...............79referencing the status of a mailbox ........................57referencing the status of a semaphore...................56referencing the status of an alarm handler.............81referencing the status of an eventflag ....................56register status when a task is initiated (before issue of

sta_tsk) ........................................................98register status when a timer handler is executed.110register status when an exception handler is executed

...................................................................116register status when the initialization handler is

executed ....................................................102register status when the interrupt handler is executed

...................................................................106registration in the interrupt vector (CPU exception

handler only) ..............................................112rel_blk...................................................................222relationship between tmout and actual time.........134releasing memory block .........................................62releasing the definition of a cyclic handler..............72releasing the definition of an alarm handler ...........73resource .................................................................48resuming task in the SUSPEND state....................43ret_int ...................................................................228ret_tmr..................................................................256ret_wup ................................................................230rot_rdq..................................................................144rsm_tsk.................................................................154RUN state...............................................................20

S

scheduling ..............................................................14sem_sts................................................................174semaphore creation ...............................................46sending message ...................................................54sending message to a mailbox...............................54set_flg...........................................................176, 188

set_tim ................................................................. 238setting the system clock......................................... 74sig_sem................................................................ 168signal operation on a semaphore........................... 48size......................................................................... 61slp_tsk.................................................................. 158snd_msg .............................................................. 202sta_tsk.................................................................. 136standard interrupt processing ................................ 66state of started task................................................ 32state of task defined through the configurator........ 30sus_tsk................................................................. 152SUSPEND state..................................................... 20synchronization...................................................... 45synchronization/communication function system call

................................................................... 166system call description......................................... 128system call for synchronization/communication object

..................................................................... 44system call function in-line expansion.................... 92system call used for time management ................. 70system clock and actual time................................. 71system clock data .................................................. 71system clock handler ........................................... 120system clock handler interface............................. 122system clock handler program............................. 121system management function system call ..... 82, 258system reference clock .......................................... 71

T

task ........................................................................ 88task creation........................................................... 28task dispatching ..................................................... 17task execution........................................................ 15task ID number............................................... 28, 132task management function system call .......... 26, 135task management transition................................... 26task operating under REALOS/907........................ 14task priority level .................................................. 133task ready queue rotation ...................................... 35task scheduling and execution sequence .............. 16task section............................................................ 13task start address................................................... 28task starting............................................................ 32task state................................................................ 20task state transition.......................................... 21, 45task state transition diagram (figure 2.4.5)............. 21task status referencing........................................... 36task termination...................................................... 33

294

INDEX

task-dependent synchronization function system call............................................................. 38, 150

task-dependent synchronization task state transition..................................................................... 39

task-independent section ................................. 13, 66TCY_INI ................................................................. 78TCY_OFF............................................................... 78TCY_ON ................................................................ 78ter_tsk .................................................................. 140time management function..................................... 70time management function system call ................ 236time-out error ......................................................... 75time-out specification ........................................... 134timeout specification .............................................. 40time-out time .......................................................... 75timer handler execution.......................................... 24tmout ...................................................................... 40tsk_sts.................................................................. 148type of exception.................................................... 83

U

user stack size........................................................29

V

V instruction............................................................44

W

wai_flg ..........................................................180, 192wai_sem ...............................................................170wai_tsk..................................................................160wait operation on a semaphore ..............................49WAIT state..............................................................20WAIT-SUSPEND state ...........................................20wakeup request cancellation ..................................41wakeup request queuing ........................................41waking up task from the WAIT state.......................40when a time-out is specified .................................134when providing a user-defined idle task .................95wup_tsk ................................................................162

295

INDEX

296

CM42-00324-2E

FUJITSU SEMICONDUCTOR • CONTROLLER MANUAL

SOFTUNE REALOS/907

October 2002 the second edition

Published

Edited

FUJITSU LIMITED Electronic Devices

Standardization Promoting Dept.

F2MC-16L/16LX/16/16H/16F

KERNEL MANUAL

µITRON 2.01 SPECIFICATIONS COMPLIANT

µitron 2.01 specifications compliant softune realos… · use this manual as a reference when...

Documents