******************************************************************************
*                          uITRON 3.0 Specification                          *
*                                                                            *
*                        General Editor: Ken Sakamura                        *
*                                                                            *
*                          Document number: I-01-02E                         *
*                         Version number: Ver 3.02.00                        *
*                                                                            *
*                              TRON ASSOCIATION                              *
*    Katsuta Building 5F, 3-39 Mita 1-chome, Minato-ku, Tokyo 108, JAPAN     *
*                            Tel. +81-3-3454-3191                            *
******************************************************************************
                                  Note: "u" of "uITRON" represents Greek "mu"
                                        and is read as "micro".

******************************************************************************
*              Copyright (C) 1993,1994,1995 by TRON ASSOCIATION              *
*                                                                            *
*      The copyright of this document is reserved by TRON ASSOCIATION.       *
******************************************************************************



******************************************************************************
*                             LICENSE AGREEMENT                              *
*                                                                            *
*   Permission to receive, use, and/or reproduce the SPECIFICATIONS which    *
*   follow is granted only under the following terms and conditions.         *
*   Acceptance of receipt of the SPECIFICATIONS constitutes your agreement   *
*   with such terms and conditions.  If you do not agree with such terms     *
*   and conditions, do not retrieve the SPECIFICATIONS.                      *
*                                                                            *
*   SECTION #1  COPYRIGHT AND OTHER PROPRIETARY RIGHTS                       *
*   1.1  All copyright and other proprietary rights relating to or in        *
*        connection with the SPECIFICATIONS belong to solely the TRON        *
*        ASSOCIATION.                                                        *
*                                                                            *
*   SECTION #2  LIMITATION OF REPRODUCTION                                   *
*   2.1  The SPECIFICATIONS may be reproduced in their entity but any        *
*        reproduction in part is strictly prohibited.                        *
*                                                                            *
*   SECTION #3  COPYRIGHT NOTICES                                            *
*   3.1  In no event may the copyright notices or the terms and conditions   *
*        of this LICENSE AGREEMENT and "Fundamental Concepts Governing the   *
*        TRON Project" described on the SPECIFICATIONS be deleted.           *
*   3.2  When you reproduce the SPECIFICATION, in no event may the           *
*        copyright notices or the terms and conditions of this LICENSE       *
*        AGREEMENT and "Fundamental Concepts Governing the TRON Project"     *
*        on any copy of the SPECIFICATIONS be deleted.                       *
*                                                                            *
*   SECTION #4  RESTRICTION OF MODIFICATIONS                                 *
*   4.1  Any modification of the SPECIFICATIONS is strictly prohibited.      *
*                                                                            *
*   SECTION #5  RESTRICTION OF REDISTRIBUTION                                *
*   5.1  Redistributing the SPECIFICATIONS upon receipt of payment of        *
*        consideration therefor without written consent from the TRON        *
*        ASSOCIATION prior to such distribution is strictly prohibited.      *
*                                                                            *
*   SECTION #6  NO WARRANTIES                                                *
*   6.1  The TRON ASSOCIATION disclaims all warranties with regards to the   *
*        SPECIFICATIONS, including all implied warranties of                 *
*        merchantability and fitness.                                        *
*   6.2  In no event shall the TRON ASSOCIATION be liable for any special,   *
*        indirect or consequential damage or any damages or disputes         *
*        whatsoever arising out of or in connection with the use of the      *
*        SPECIFICATIONS.                                                     *
******************************************************************************

******************************************************************************
*              Fundamental Concepts Governing the TRON Project               *
*                                                                            *
* 1. The computer architecture TRON originated by Dr. Ken Sakamura is an     *
*    open computer architecture.  The TRON Specifications are made           *
*    publicly available to anyone in the world.                              *
*                                                                            *
* 2. Copyrights to the TRON Specifications belong to the TRON ASSOCIATION.   *
*    Anyone is entitled to utilize the TRON Specifications in developing     *
*    and merchandising products conforming to the TRON Specifications.       *
*                                                                            *
* 3. The TRON ASSOCIATION has been established as the core organization for  *
*    the purpose of preparing the TRON Specifications, conducting            *
*    conformance testing, and otherwise promoting the TRON Project.          *
*    Membership in the TRON ASSOCIATION is open to anyone in the world who   *
*    shares in the objectives of the TRON Project and agrees to observe      *
*    the TRON ASSOCIATION's rules.                                           *
*                                           The TRON ASSOCIATION             *
******************************************************************************

The contents of this document may be revised without prior notice.
Although the contents in this document have been carefully reviewed and is
believed to be reliable, TRON ASSOCIATION is not assuring its contents nor
assuming any liability of problems caused by this document.

TRON   is an abbreviation of The Real-time Operating system Nucleus.
BTRON  is an abbreviation of Business TRON.
CTRON  is an abbreviation of Communication and Central TRON.
ITRON  is an abbreviation of Industrial TRON.
MTRON  is an abbreviation of Macro TRON.

****************************************************************************
***    Preface to the uITRON 3.0 Specifiction                            ***
****************************************************************************

Since the beginning, the ITRON subproject has been the most heavily promoted
of all the subprojects within the TRON Project.  The ITRON specification
operating system faithfully realizes the promise of the real-time operability
that is the basis of the TRON Project.  The major feature of ITRON
specification is its adaptability which can be implemented even on compact
hardware systems having extremely limited amounts of memory.  Since it is
therefore being used in industrial applications, including embedding in
machines, controlling robots and controlling factory plants, its adaptability
has grown greatly to the point that it has grown into a real-time OS used
as the standard in many fields.  Since the ITRON specification delivers an
operating system which can be optimized for the application, it has evolved
into a series of specifications for various applied fields.  Specifications
of ITRON1, ITRON2, uITRON and ITRON/FILE have now been released.  If you want
details on the specific nature of each of these specifications, please see
the "ITRON Standard Guidebook '92 to '93" (Published by Personal Media
Corporation in Japanese).

Including new features and strengthened specifications, uITRON 3.0
specification described in this document is based on 10 years of TRON
project experience and represents the latest version of the ITRON
specification.  In addition to the characteristic of compactness and
robustness of the conventional uITRON specification, uITRON 3.0 specification
includes network support functions for loosely-coupled distributed processing.
Combined with recent reductions in the prices of microprocessors, the number
of microprocessors required by applications has grown rapidly resulting in
a growing need to configure distributed systems by networking many separate
processors.  uITRON 3.0 specification is intended as the platform for
building such distributed systems.

Such distributed systems have many requirements.  Not only must the operating
system provide the ability to perform real-time processing and ensure
transparency between nodes, but also it must be adaptable to various size
systems and low cost systems in particular.  Specifically, it must be
adaptable to many different communication media and network topologies, and
workable in environments where available memory on each node may be extremely
small.  uITRON 3.0 specification has been designed to meet all of these
requirements.  Rather than merely crowning the specification with the latest
technical fads, uITRON 3.0 specification is a confident work that reflects
both industry opinion and many years of experience.  The editor fully
expects that uITRON 3.0 specification will be effectively utilized in many
embedded network systems.

This document is an official ITRON standard specification prepared by
the ITRON Technical Committee of the TRON Association.  I wish to express my
sincere gratitude to the many people without whose cooperation this book would
not have been possible.

                                                              June, 1993
                                                            Ken Sakamura
                                            TRON Project, Project Leader

****************************************************************************
***    Table of Contents                                                 ***
****************************************************************************

  Chapter 1 Basic Philosophy of the ITRON and uITRON 3.0 Specification
      1.1 The TRON Project
      1.2 TRON Subprojects
      1.3 Multitasking, Real-time Operating Systems
      1.4 History of ITRON Specification and Planned Future Developments
      1.5 Features of ITRON Specification
      1.6 The Basic ITRON Concept
            Tasks
            Resources
            Task State and Operation
            Task Scheduling
            System State During Non-Task Portion Execution
            Task-Independent and Quasi-Task Portions
            Objects
            Concepts of Standardization and Compatibility
                    in ITRON Specification
      1.7 uITRON 3.0 Specification Overview
            Position of uITRON 3.0 Specification
            Levels of uITRON 3.0 Specification
      1.8 Implementation-Dependent Functions
            Issuing System Calls from Task-Independent Portions
            Implementation-Dependent System Call Names
            Implementation-Dependent Error Names

  Chapter 2 The Connection Function of uITRON 3.0 Specification
      2.1 Connection Function in Practical Use
            Concept the Connection Function in Application
            Example Using A MessageBuffer
            Scope of the Connection Function Specification
            Connection Function Response Wait State
      2.2 Significance and Background of the Connection Function
            The Relationship to IMTRON specification
            The Relationship with Other Network Systems
            The Relationship between Conventional ITRON Specification
            and Connection Functions
      2.3 The Meaning of ID Numbers and the Object Location Table
            How Objects on other Nodes are Accessed
            Problems Concerning Return Parameters

  Chapter 3 System Calls of uITRON 3.0 Specification
      3.1 Task Management Functions
      3.2 Task-Dependent Synchronization Functions
      3.3 Synchronization and Communication Functions
      3.4 Extended Synchronization and Communication Functions
      3.5 Interrupt Management Functions
      3.6 Memorypool Management Functions
      3.7 Time Management Functions
      3.8 System Management Functions
      3.9 Network Support Functions

  Chapter 4 Connection Function Communication Protocol
      4.1 Overview of Communications Protocols
            Position of Communications Protocols
            Design Concept for the Connection Interface
            Packet Types
            Configuration of the Connection Interface
            Bit Length of Data in Packets
            Specific Packet Flow
      4.2 Communication Packet in Practice
            Packet Structure Contents
            Level X Information
            Connection Function-Related Errors
            TC Packet
            Packet Flow When Using Rendezvous

  Chapter 5 Standard Interfaces
      5.1 The Assembler Interface
            How Parameters are Passed
            Flag Value Changes in the PSW after System Calls have Executed
            Function Code
      5.2 C Language Interface and Mnemonics
            Mnemonics
            Data Types
            High-Level Language Support Routines
      5.3 Error Codes

  Chapter 6 References
      6.1 System Call Support Level Categories
      6.2 System Calls
      6.3 Function Codes
      6.4 Data Types
            General-Purpose Data Types
            Data Types Dependent on ITRON Specification
      6.5 C Language Interfaces
      6.6 Common Constants and Data Structure Packet Formats
      6.7 Error Codes

  Chapter 7 Appendices
      7.1 Maker Codes and CPU Codes
            Maker Codes
            CPU Codes
      7.2 Specification Maintenance System
            Assigning Version Numbers
            Who to Contact with Questions Regarding Specifications
      7.3 Bibliography of the TRON Project and ITRON Specification

****************************************************************************
***    Index of Figures and Tables                                       ***
****************************************************************************

    Figure 1  -------- Development of the ITRON Specification
    Figure 2  -------- System Call Naming Conventions in ITRON Specification
    Table 1  --------- Abbreviations Used in Naming Conventions of ITRON
                       Specification
    Table 2  --------- Distinction of System Calls Acting on the Issuing Task
                       or Another Task and Associated State Transitions
    Figure 3  -------- Task State Transition Diagram in ITRON Specification
    Figure 4(a)  ----- Beginning State of the Ready Queue
    Figure 4(b)  ----- State of the Ready Queue After Task A Enters the WAIT
                       State
    Figure 5  -------- System States in ITRON Specification
    Figure 6  -------- Interrupt Nesting and Delayed Dispatching
    Figure 7  -------- Connecting CPUs with uITRON 3.0 Specification OS
    Figure 8  -------- Accessing Objects on Other Nodes
    Figure 9  -------- Specification Defined for the Connection Function
    Figure 10  ------- tskatr Format
    Table 3  --------- Results of Executing ter_tsk on Tasks in Various States
    Figure 11(a)  ---- Ready Queue Before Executing rot_rdq
    Figure 11(b)  ---- Ready Queue After Executing rot_rdq(tskpri=2)
    Table 4  --------- Results of Executing rel_wai on Tasks in Various States
    Table 5  --------- tskwait and wid Values
    Figure 12  ------- Message Format Used by Mailboxes
    Figure 13  ------- sematr Format
    Figure 14  ------- flgatr Format
    Figure 15  ------- The Multiple Task Wait Feature of Eventflags
    Figure 16  ------- mbxatr Format
    Figure 17  ------- Rendezvous Operation and Changes in Task Status
    Figure 18  ------- mbfatr Format
    Figure 19  ------- Synchronous Communications Using a MessageBuffer of
                       bufsz = 0
    Figure 20  ------- poratr Format
    Figure 21(a)  ---- ADA Program Sample Using the select Statement
    Figure 21(b)  ---- Implementing the ADA select Feature Using the
                       Rendezvous Function of ITRON Specification
    Figure 22  ------- Server Task Operation Using fwd_por
    Figure 23  ------- intatr Format
    Table 6  --------- State Transitions Related to dis_dsp and loc_cpu
    Table 7  --------- System Status when loc_cpu has Executed Versus Task-
                       Independent Portions
    Figure 24  ------- Typical Hardware Model for Considering Interrupt
                       Processing
    Figure 25  ------- mplatr Format
    Figure 26  ------- mpfatr Format
    Figure 27  ------- cycatr Format
    Figure 28  ------- almatr Format
    Figure 29(a)  ---- maker Format
    Figure 29(b)  ---- id Format
    Figure 29(c)  ---- spver Format
    Figure 29(d)  ---- prver Format
    Figure 29(e)  ---- prno Format
    Figure 29(f)  ---- cpu Format
    Figure 29(g)  ---- var Format
    Figure 30  ------- svcatr Format
    Figure 31  ------- excatr Format
    Figure 32  ------- Position of Communications Protocols
    Figure 33  ------- Configuration of the Connection Interface
    Figure 34  ------- Packet Flow for sig_sem and wai_sem
    Figure 35  ------- Packet Flow for psnd_mbf and rcv_mbf
    Table 8  --------- Connection Function Error Codes and Packet Flow
    Figure 36  ------- The Two Types of EN_PAR Error
    Figure 37  ------- How TC Packets are Used
    Figure 38  ------- Packet Flow When cal_por Immediately Establishes a
                       Rendezvous
    Figure 39  ------- Packet Flow When cal_por Does Not Immediately Establish
                       a Rendezvous
    Figure 40  ------- Packet Flow When a Rendezvous is Forwarded to Another
                       Node
    Figure 41  ------- Packet Flow When tcal_por Results in a Timeout
    Figure 42  ------- Packet Flow When pcal_por Establishes a Rendezvous
    Figure 43  ------- Packet Flow When pcal_por Does Not Establish a
                       Rendezvous
    Figure 44  ------- Operation of a High-Level Language Support Routine
    Figure 45  ------- Error Code Formats
    Figure 46  ------- Format of maker Returned by get_ver
    Figure 47  ------- Format of cpu Returned by get_ver

****************************************************************************
***    System Call Description Conventions                               ***
****************************************************************************

Each system call described in the system call description sections of this
specification document is described in the following manner.


========================================================================
|| [Level] || - System Call Name - || - English Description -
========================================================================
  System Call Name:  English Origin of Name

  * The letters used in [Level] indicate the support level required by the
    implementation to support the given system call.  In order of least to
    most strict support level, this is expressed by 'R', 'S' and 'E'.

  * System calls for [Level] suffixed with 'N' represent system calls which
    can support the connection function (network function).

[Parameters]

  - This section lists system call parameters, and gives a description of
    information passed to the OS when the system call is issued. -

[Return Parameters]

  - This section lists system call return parameters, and gives a description
    of information returned from the OS when the system call completes
    execution. -

[C Language Interface]

  - This section gives the C language interface of the system call. -

[Description]

  - This section describes the function of the system call. -

  * When several values may be selected for system call parameters, a
    description like that given below is included regarding the options
    available.

        ( x || y || z ) --- Indicates that one of x, y or z must be selected
        x | y           --- Indicates both x and y may be specified
                            simultaneously (x and y, if specified at a time,
                            are ORed)
        [ x ]           --- Indicates x may or may not be freely specified

    Example:
        If wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR], any of the following
        four options can be specified for wfmode:
                TWF_ANDW
                TWF_ORW
                (TWF_ANDW | TWF_CLR)
                (TWF_ORW | TWF_CLR)

[Supplemental Information]

  - This section gives supplemental information describing special points of
    interest or points to be aware of. -

[Error Codes]

  - This section gives a description of errors which may occur when the system
    call is issued. -

  * The description of each of the following error codes is not included for
    every system call, even though it is possible that they may be detected
    upon the execution of any system call.
        E_SYS, E_NOSPT, E_RSFN, E_MACV

  * A description is given for the E_CTX error code for those system calls
    only when the conditions of the error detected are known (such as for
    system calls which may result in a WAIT state).  Note, however, that
    the E_CTX error may be detected even on other system calls due to
    implementation restrictions.  The E_CTX error code is not listed in this
    section when it occurs depending on implementation.

  * The description of following error codes, detected when the connection
    function is used, is not included in this section for every such system
    call, even though they may be detected upon the execution of any system
    call which supports the connection function (system calls of [level RN],
    [level SN], or [level EN]).
        EN_NOND, EN_PROTO, EN_RSFN, EN_COMM, EN_RLWAI, EN_EXEC

[Differences from uITRON 2.0 and ITRON2 Specifications]

  - This section describes differences between uITRON 3.0 specification
    and uITRON (Ver. 2.0) or ITRON2 specification. -

[Rationale]

  - This section describes reasons for specifications which may be unclear. -

****************************************************************************
***    System Call Index                                                 ***
****************************************************************************

This index lists all system calls of uITRON 3.0 specification described in
this document in alphabetical order.

        acp_por [E]     Accept Port for Rendezvous
        act_cyc [E]     Activate Cyclic Handler
        cal_por [EN]    Call Port for Rendezvous
        can_wup [SN]    Cancel Wakeup Request
        chg_iXX [C]     Change Interrupt Mask (Level or Priority)
        chg_pri [SN]    Change Task Priority
        clr_flg [SN]    Clear Eventflag
        cre_flg [EN]    Create Eventflag
        cre_mbf [EN]    Create MessageBuffer
        cre_mbx [E]     Create Mailbox
        cre_mpf [E]     Create Fixed-Size Memorypool
        cre_mpl [E]     Create Variable-Size Memorypool
        cre_por [EN]    Create Port for Rendezvous
        cre_sem [EN]    Create Semaphore
        cre_tsk [EN]    Create Task
        def_alm [E]     Define Alarm Handler
        def_cyc [E]     Define Cyclic Handler
        def_exc [C]     Define Exception Handler
        def_int [C]     Define Interrupt Handler
        def_svc [C]     Define Extended SVC Handler
        del_flg [EN]    Delete Eventflag
        del_mbf [EN]    Delete MessageBuffer
        del_mbx [E]     Delete Mailbox
        del_mpf [E]     Delete Fixed-Size Memorypool
        del_mpl [E]     Delete Variable-Size Memorypool
        del_por [EN]    Delete Port for Rendezvous
        del_sem [EN]    Delete Semaphore
        del_tsk [EN]    Delete Task
        dis_dsp [R]     Disable Dispatch
        dis_int [C]     Disable Interrupt
        dly_tsk [S]     Delay Task
        ena_dsp [R]     Enable Dispatch
        ena_int [C]     Enable Interrupt
        exd_tsk [E]     Exit and Delete Task
        ext_tsk [S]     Exit Issuing Task
        frsm_tsk [EN]   Forcibly Resume Suspended Task
        fwd_por [E]     Forward Rendezvous to Other Port
        get_blf [E]     Get Fixed-Size Memory Block
        get_blk [E]     Get Variable-Size Memory Block
        get_tid [S]     Get Task Identifier
        get_tim [S]     Get System Clock
        get_ver [R]     Get Version Information
        loc_cpu [R]     Lock CPU
        nget_nod [SN]   Get Local Node Number
        nget_ver [SN]   Get Version Information of another Node
        nrea_dat [SN]   Read Data from another Node
        nwri_dat [SN]   Write Data to another Node
        pacp_por [E]    Poll and Accept Port for Rendezvous
        pcal_por [EN]   Poll and Call Port for Rendezvous
        pget_blf [E]    Poll and Get Fixed-Size Memory Block
        pget_blk [E]    Poll and Get Variable-Size Memory Block
        pol_flg [SN]    Wait for Eventflag (Polling)
        prcv_mbf [EN]   Poll and Receive Message from MessageBuffer
        prcv_msg [S]    Poll and Receive Message from Mailbox
        preq_sem [RN]   Poll and Request Semaphore
        psnd_mbf [EN]   Poll and Send Message to MessageBuffer
        rcv_mbf [EN]    Receive Message from MessageBuffer
        rcv_msg [S]     Receive Message from Mailbox
        ref_alm [E]     Reference Alarm Handler Status
        ref_cfg [C]     Reference Configuration Information
        ref_cyc [E]     Reference Cyclic Handler Status
        ref_flg [EN]    Reference Eventflag Status
        ref_iXX [C]     Reference Interrupt Mask (Level or Priority)
        ref_mbf [EN]    Reference MessageBuffer Status
        ref_mbx [E]     Reference Mailbox Status
        ref_mpf [E]     Reference Fixed-Size Memorypool Status
        ref_mpl [E]     Reference Variable-Size Memorypool Status
        ref_por [EN]    Reference Port Status
        ref_sem [EN]    Reference System Status
        ref_sys [E]     Reference Semaphore Status
        ref_tsk [EN]    Reference Task Status
        rel_blf [E]     Release Fixed-Size Memory Block
        rel_blk [E]     Release Variable-Size Memory Block
        rel_wai [SN]    Release Wait of Other Task
        ret_int [R]     Return from Interrupt Handler
        ret_tmr [E]     Return from Timer Handler
        ret_wup [E]     Return and Wakeup Task
        rot_rdq [S]     Rotate Tasks on the Ready Queue
        rpl_rdv [E]     Reply Rendezvous
        rsm_tsk [SN]    Resume Suspended Task
        set_flg [SN]    Set Eventflag
        set_tim [S]     Set System Clock
        sig_sem [RN]    Signal Semaphore
        slp_tsk [R]     Sleep Task
        snd_mbf [EN]    Send Message to MessageBuffer
        snd_msg [S]     Send Message to Mailbox
        sta_tsk [SN]    Start Task
        sus_tsk [SN]    Suspend Other Task
        tacp_por [E]    Accept Port for Rendezvous with Timeout
        tcal_por [EN]   Call Port for Rendezvous with Timeout
        ter_tsk [SN]    Terminate Other Task
        tget_blf [E]    Get Fixed-Size Memory Block with Timeout
        tget_blk [E]    Get Variable-Size Memory Block with Timeout
        trcv_mbf [EN]   Receive Message from MessageBuffer with Timeout
        trcv_msg [E]    Receive Message from Mailbox with Timeout
        tslp_tsk [E]    Sleep Task with Timeout
        tsnd_mbf [EN]   Send Message to MessageBuffer with Timeout
        twai_flg [EN]   Wait on Eventflag with Timeout
        twai_sem [EN]   Wait on Semaphore with Timeout
        unl_cpu [R]     Unlock CPU
        wai_flg [SN]    Wait on Eventflag
        wai_sem [RN]    Wait on Semaphore
        wup_tsk [RN]    Wakeup Other Task

****************************************************************************
*****                                                                  *****
*****  Chapter 1 Basic Philosophy of the ITRON and uITRON 3.0          *****
*****            Specification                                         *****
*****                                                                  *****
****************************************************************************

****************************************************************************
***    1.1 The TRON Project                                              ***
****************************************************************************

The first microprocessor was born early in 1970's, but advances have been
rapid and it is used increasingly in many fields.  One day countless
microprocessors will surround us in our everyday lives, communicating with
each other and performing distributed processing, thereby helping to provide a
more comfortable living environment for us all.

Unfortunately, it is hard to say that today's computer technology meets
these demands.  This is largely due to the fact that even today's
computer architecture continues to use designs from a period when hardware
resources were insufficient, such that many computer subsystems are now being
strained to their limit.  If semiconductor technology continues to advance at
its present rate, the gap between computer resources and architecture will
continue to grow even greater, with the fear that it will eventually
become impossible to utilize full hardware performance.  Computer
systems are becoming highly unbalanced under the increasing demands from
applied fields for greater top-down capabilities, despite the bottom-up
improvements to performance gained through advances in semiconductor
technology, all because of the old architecture that exists in between.  There
is a need for a new computer architecture targeted for the 1990's and early
21st century which utilizes the most advanced VLSI technology to respond to the
growing demands of application fields.

The TRON Project, begun in June 1984, is intended to resolve the current
problems associated with computer architecture by starting over to produce a
completely new computer design integrated at every level from microprocessors
to applications.  The TRON Project advocates a completely new architecture
free from the restriction of compatibility with conventional architectures -
an architecture designed based on predicted advances in VLSI technology
through the 1990's into the early 21st century with the demands of future
computer users and application fields in mind.  This architecture design
emphasizes real-time computing, is built based on the most advanced VLSI
technology available and utilizes distributed processing as much as possible.
It is intended as an industry standard for the 1990's and early 21st century.

The TRON Project expands the definition of "architecture" set forth by G.M.
Amdahl to mean system attributes at all levels including the operating system
(OS) and human-machine interface, not just hardware specifications used by
programmers.

The fundamental concept behind the TRON Project is as follows:

  - To develop a design assuming the technological standard of the 1990s
    through the early 21st century.
        Most computer architectures of today are held back by having to remain
        compatible with systems of the past, and are not able to fully meet
        the demands of new application fields in which computers are being
        used.   The TRON Project aims at producing a standard which can be
        used into the future, by giving emphasis on compatibility with future
        systems rather than past systems.

  - To emphasize the concept of open architecture.
        The result of the TRON Project is made publicly available in the
        form of specification documents so that anyone may freely use the
        information.  The concept of "open architecture" is very important
        for projects to make a standard specification.   On the other hand,
        the rights of the various products which may be developed based on
        this standard belong to the product developers.

  - To presume real-time processing.
        The method of using conventional computers, which often use batch
        processing or TSS processing, is such that the user waits for the
        computer.  However, as computers work their way into our everyday
        lives many will be used to control our external environment to make
        our lives more comfortable.  In this case the computer will have to
        wait for the user (or for some other stimulus from the external
        environment).  This is the essence of real-time processing.  The real-
        time element is vital in other applications such as distributed
        processing and communications as well.  The TRON Project presumes that
        real-time processing is vital, and the rest of the design proceeds
        from there.

  - To achieve a total architecture by designing all layers of computer
    systems simultaneously.
        Under the TRON Project, a unified architecture is designed
        simultaneously for all levels, from the microprocessor to applications.
        This makes it possible to utilize broad-based design feedback such
        that new microprocessor instructions can be implemented when
        bottlenecks are found in the OS, or to add system calls to the OS when
        it is found they are required during the development of an application.
        Because whole computer system is tuned across layers in this way at
        the design stage, it is possible to greatly increase the performance
        of the application program and this is the most important requirements.

****************************************************************************
***    1.2 TRON Subprojects                                              ***
****************************************************************************

Many subprojects are being worked on simultaneously within the overall TRON
Project.  These subprojects can be classified into two main types: fundamental
subprojects related to research and development of the components necessary to
construct a computer system, and application subprojects for clarifying the
demands of application fields.

The lowest layer of the fundamental subprojects is work on the TRON-
specification microprocessor to be designed using advanced architecture
presuming the state of the art in semiconductor technology.  The TRON-
specification microprocessor is intended as the best microprocessor for
running applications and operating systems of the 1990's and early 21st
century.  Three operating system specifications are developed for different
application fields: ITRON (Industrial TRON)--a real-time OS for embedded
systems, BTRON (Business TRON)--an OS for personal computers and workstations,
and CTRON (Communication and Central TRON)--an OS for large mainframes
handling large-scale data processing and communications control.  The reason
for dividing the OS into three based on application requirements was
because it is considered to be impossible for a single OS to meet all the
requirements of embedded OS computers, personal computers/workstations, and
large mainframes.  In addition to these three operating systems, there is also
MTRON (Macro TRON) which allows the dynamic networking of multiple ITRON,
BTRON and CTRON-based machines, and provides an interface with the external
environment in which we humans live.  At the highest layer, MTRON provides
a standardized user interface.  Note that the TRON Project is not just limited
in scope to computers, but also seeks to standardize the operation of all
electronic devices.

In the application subprojects of TRON Project, the prototype of living
environment managed by high-level computer control is actually build.
Subprojects for building intelligent house, intelligent building, and
intelligent city are being conducted so as to closely investigate the
requirements of such a system.

A major feature of the TRON Project is that architecture and implementation
have been separated from each other.  Making this clear division gives the
advantage that even if an implementation below a given layer needs to be
completely changed, higher level specifications can continue to be used
without modification.  In other words, compatibility is maintained at each
separate layer.  Another important aspect of the TRON Project is that while
specifications concerning architecture are prescribed, none are prescribed
concerning implementation or performance.  This is left to be decided through
free-market competition among developers.  From a user's standpoint, products
will all appear to operate in the same manner, but differ in terms of their
performance.  This will make many levels of products available depending on
differences among manufacturers and differences in development cycles.  In
essence, the TRON Project provides common ground for fair technological
competition through standardization.

****************************************************************************
***    1.3 Multitasking, Real-time Operating Systems                     ***
****************************************************************************

Computers built around a microprocessor, called microcomputers, are making in-
roads into new computer applications, replacing various control equipment, by
virtue of their being small and inexpensive.  For example, they are
increasingly being used to replace all kinds of control devices, in other
words, it has become possible for a small computer to replace control devices
formerly made up of relays, mechanical parts and analog circuits.
Specifically, many products from telephone switching devices, industrial robots
and NC machine tools, to home appliances such as air conditioners, washers and
televisions use microcomputer control.

The microcomputers used as control devices are not intended to be used inside
of standard computers such as mainframes, personal computers or workstations.
The control computers are characterized by their use as a single part in a
larger system.  For this reason they are called "embedded computer systems",
or "embedded systems" in short.

In general, embedded systems have the ability to detect various external
stimuli or changes in the environment using sensors and then initiate an
operation in response, or to initiate periodic operations so as to affect the
outside environment.  An air conditioner, for example, uses sensors to detect
external temperature and humidity and controls its output level and wind
direction in response.  Embedded system programs must perform their control
by following time-varying changes in the external environment without delay.
It is this point that makes them essentially different from typical data
processing programs.

In order to increase the productivity of embedded system programs and
reduce the manufacturing cycle required, the programs themselves are not
written directly using processor instructions, but rather are written using a
shared management program, or OS.  Application programs written for a given
system are then placed on top of this OS.  The OS itself differs from
operating systems of the type used in a general-purpose computers.  The main
purpose of these operating systems is protection among users and file system
management, whereas embedded operating systems are designed to make it easier
to program applications using concurrent processing and interrupts for
synchronization with external events.

In general, computers, and the programs which run on them, are sequential in
nature.  They cannot do two things at once.  Embedded systems on the other
hand are often required to monitor the outputs from sensors concurrently.
If there are two sensors requiring monitoring, it is intuitive for the
program to be divided into two parts.  These parts can be thought of as
running concurrently, thus making the task of programming simpler.  The
approach that arose from this type of application is the basis of the concept
of multitasking.  All processing is divided into separate tasks each of which
are parallel in flow.  Programs can be produced more quickly and made easier
to understand when divided into tasks in this way.  Of course, a processor
alone is left only with the ability to execute instructions sequentially, so
multitasking is implemented through time-sharing at the OS level.  The OS
having the multitasking capability is called multitasking OS, which is very
useful for embedded systems.

The operating systems used in general-purpose computers are also multitasking
in the sense that they execute multiple jobs (processes, tasks) based on time-
sharing.  In the case of general-purpose computers, however, jobs (processes,
tasks) are highly likely to be unrelated to each other.  In the sense that one
person may be using the computer for document processing, while another is
using it for compiling a program, and yet another is using a text editor, the
computer is in fact multitasking.  But each user is only interested in the job
(program) he or she is executing.  They are not in the least concerned with
what kind of concurrent processing may be going.  In this case, the reason for
using multitasking is mainly for improved cost performance.  In short, even
though it would be ideal for each user to have his or her own computer, it is
necessary for them to share a single computer because there aren't enough to
go around.  The result is multitasking.

In embedded systems, on the other hand, a job having a single purpose is
divided into multiple tasks to make the program easier to write.  Furthermore,
these tasks do not just run in total isolation, but rather have a very
complicated relationship with each other.  In the case of an embedded system,
the operation of any given task and its mutual relationship to other tasks is
controlled by the designer of the overall system, and each of the individual
tasks cooperate to achieve a single goal.  In this sense, the multitasking
used in a general-purpose computer is quite different from that used in an
embedded system.

Another important point about operating systems used in embedded systems is
that they operate in real time.  In abstract terms, real-time operation means
that the computer processing follows changes in external states.  Specifically,
the time required for the output of results is constrained.  In simplest terms,
worst-case response time is predictable.

With conventional computers which use batch or time-sharing processing, the
user waits for the computer.  In this case, the fact that the computer is
computing is a goal in itself, and the computer is unrelated to any other
systems.  Accordingly, no matter how long processing takes, everything will
come out all right in most cases as long as the user waits.  True, the faster
the processing, the better; however, there will be no fatal effects even if it
takes a long time.

In the case of embedded systems, on the other hand, computation itself is not
the goal.  The goal is controlling other equipment based on the results of
computation.  The demand for fast processing is high.  If processing is
delayed, results may be meaningless by the time they are available.  Take the
safety control equipment of a train for example.  If the brakes are not applied
within a set amount of time when something wrong is detected, an accident will
result.  Or, let's say the spark plug timing of an automobile engine is
controlled by an embedded system.  Results must be output before engine
rotation reaches a certain point or the calculation will be useless.  In other
words, it is not only important what happens to the results of processing, when
they are obtained is also important.  Outputting late results is the same as
not outputting any results at all.

In order to meet the strict demands on processing times, the computer must
wait for stimulus from the external environment.  This means the time the
computer is in operation is reduced.  In other words the computer is being
used relatively seldom.  This extravagant use of computers has only become
possible recently, thanks to the popularity of general-purpose computer
helping to reduce prices.  And that is the reason real-time, embedded
computers are a relatively recent application of computer technology.

During programming, one may refer to the algorithm, data structure, or the
efficiency of execution or the amount of calculations, but the absolute
execution time required is rarely discussed.  But in applications intended for
embedded systems, it is often critical to know ahead of time the amount of
execution time required by a program.  And this does not just refer to the CPU
time required by each program (job, process, task).  It is necessary to
estimate the absolute execution time required including the overall load on
the system down to the execution status of other tasks.  This is an extremely
difficult thing to do, and is just plain impossible under a complex OS like
those used in large machines, because unless the OS itself is fairly simple,
it will be impossible to accurately estimate OS overhead.

Operating systems used in embedded systems are greatly different from
operating systems used for typical data processing or those used for software
development.  An OS intended for an embedded system must be capable of both
multitasking and real-time operation.

****************************************************************************
***    1.4 History of ITRON Specification and Planned Future Developments **
****************************************************************************

ITRON (Industrial - The Real-time Operating system Nucleus) is a real-time,
multitasking OS specification intended for use in industrial embedded systems.

Work on the ITRON specification began in 1984 with the start of the TRON
Project, and the first specification was released in 1987.  That specification
is called the ITRON1 specification.  As an OS specification standardized
mainly for 16-bit microprocessors, ITRON1 specification was standardized for
the major 16-bit microprocessors of that time.  Several operating systems
have been implemented based on the ITRON1 specification.  These operating
systems made invaluable contributions to the evaluations of the ITRON
specification.

After this, work was conducted on the uITRON specification (Ver. 2.0), for use
mainly on smaller 8-bit MCUs, and the ITRON2 specification, for use on higher
performance 32-bit microprocessors.  Both specifications were made public in
1989.  uITRON specification is a highly condensed version of ITRON
specification.  System calls are divided into five levels depending on
their importance.  uITRON specification operating systems have been
implemented not only on 8-bit microcontrollers (MCUs), but also on 16 and
32-bit microprocessors.  There have been over 20 implementation examples of
uITRON-based operating systems running on a variety of processors being
reported.  The ITRON2 specification, which is based on ITRON1 specification,
with many high level functions added, has mainly been implemented on TRON-
specification microprocessors.

In parallel with the above work on OS specifications, work has progressed on
the standardization of external I/O used in conjunction with ITRON operating
systems.  The ITRON/FILE specification, a specification for a file management
system under ITRON and uITRON specification kernel, was released in 1992.

uITRON 3.0 specification is a version upgrade of the uITRON specification
based on user feedback and experience in implementing ITRON1, ITRON2 and
uITRON (Ver. 2.0) specification OS.  The ITRON2 and uITRON specifications
have been unified by adding object creation/deletion functions and some of
the extended features of ITRON2 specification to uITRON specification.
Support for distributed systems has also been made available by
adding functions for the loosely-coupled networking of ITRON specification
computers.  Distributed systems supported under uITRON 3.0 specification
have the restriction that node configuration does not change dynamically.

As the future perspective for the ITRON specification, work is progressing on
the ITRON-MP specification for application in tightly-coupled multiprocessor
systems.  There are also plans to develop an IMTRON specification which will
allow operation even in an environment where the node configuration of a
distributed system does change dynamically.

In the rest of this document, "uITRON (Ver. 2.0)" will be written as
"uITRON 2.0".


1st        : 2nd Generation  :   3rd Generation
Generation :                 :
           :                 :                                    ==========
           :                 :                                    |        |
           :                 :    ==============   ============   |        |
           :     ==========  :    |            |   |          |   |        |
           : +-->| ITRON2 |------>|            |-->| ITRON-MP |-->|        |
           : |   |  Spec. |  :    |            |   |   Spec.  |   |        |
========== : |   \--------+  :    |            |   |          |   | IMTRON |
| ITRON1 |---+ Intended for  :    | uITRON 3.0 |   \----------+   |  Spec. |
|  Spec. |---+ 32-bit MPUs   :    |    Spec.   |                  |        |
\--------+ : | such as TRON- :    |            |                  |        |
Intended   : | specification : +->|            |----------------->|        |
for        : | microprocessors |  |            |                  |        |
general-   : |               : |  |            |                  |        |
purpose    : |   ==========  : |  \------------+                  \--------+
16-bit MPUs: +-->| uITRON |----+
           :     |(Ver2.0)|  :
           :     |  Spec. |  :
           :     \--------+  :
           : Intended for    :
           : small scale,    :
           : single-chip     :
           : microcomputer   :
           : based systems   :
           :                 :

               Figure 1 Development of the ITRON Specification

****************************************************************************
***    1.5 Features of ITRON Specification                               ***
****************************************************************************

One of the main features of ITRON specification operating systems is the fact
that although implementation on various types of processors is possible, no
more standardization or virtualization than necessary are made so that higher
processing performance may be achieved.  Another main feature is that although
the operating systems provide many functions, thought has been given to
adaptability such that actual object code can be made very compact.

From the standpoint of software compatibility and ease of learning, it is
desirable to virtualize microprocessor architectures as much as possible and
provide a high level of standardization, but this has the negative impact of
decreasing basic performance.  And although it may be desirable for an OS to
include lots of functions from the standpoint of making programming easier and
raising the performance of certain types of applications, there is again a
negative impact in that object code size grows too large.  In designing an OS,
these two considerations must be kept in balance.  One solution to this
tradeoff is ITRON specification.  The basic concept of "loose" standardization
which underlies the entire TRON Project can be said to have been concretely
realized in the field of real-time operating systems.

Features of ITRON specification are brought together below.


  - Processor architecture is not virtualized.
        ITRON specification is intended for OS implementation on many
        different processors. However, specific implementation and design is
        carried out independently for each processor.

        The first thing that comes to mind when creating a standard OS is to
        assume the common virtual architecture and then design the ITRON
        specification on that architecture.  With this approach,
        consequently, the gap between the native architecture of the processor
        and the virtualized architecture is directly tied to reduced
        performance.  Architecture which takes full advantage of processor is
        required to maximize performance of the real-time OS.  The
        virtualization in the machine or OS must be kept to a minimum.
        Furthermore, the need for object code compatibility in the case of
        embedded systems is relatively low.  On the other hand, the need for
        compatibility in terms of uniformity of naming of system calls or
        their function is very important from a learning standpoint.  We
        therefore investigated which OS specifications should and should not
        be standardized under ITRON specification.  We clearly isolated
        specifications which were common to all processors and those which
        were processor-dependent. Specifications which were difficult to
        standardize were left alone, so as to prevent loss in performance
        due to excessive standardization and processor virtualization.

  - ITRON specification provides many functions.
        ITRON specification provides many system calls possessing various
        useful functions.  For example, ITRON specification provides almost
        every synchronization mechanism imaginable: eventflags, semaphores,
        and mechanisms accompanying individual tasks (the system calls slp_tsk
        and wup_tsk).  This allows for the selection of the mechanism best
        suited to the application and should lead to better performance and
        greater ease in programming.

  - High-speed response is possible.
        What can really affect response times in a real-time application are
        the part that handles task switching (dispatching) and the part that
        invokes the interrupt handler.  As discussed later in conjunction with
        its adaptability, ITRON specification allows registers to be swapped
        out at dispatch time to be specified to achieve high-speed dispatching.
        Furthermore, it is possible to cause a user-defined interrupt handler
        to run any time an external interrupt occurs, without having to go
        through the OS.  The overhead required here is practically zero.
        However, any registers used by the interrupt handler must be saved by
        the user.

  - ITRON specification has built-in adaptability.
        ITRON specification, an OS architecture, has been designed as a highly
        flexible and adaptable architecture with application in embedded
        systems specifically in mind.  The high level of freedom provided to
        the user through choices such as system call selection, specification
        of registers to be swapped out during dispatching, a low power
        consumption mode when there are no running or ready tasks, and the
        ability to turn off error checking that is done in each system call
        for a highly flexible and adaptable OS.

        For example, let's say there is a parameter which defines a memory
        address.  The overhead in executing a system call is fairly high if
        the software has to check whether a memory-related error such as a
        segmentation error or bus error may occur.  On the other hand, there
        is no reason to expect the parameter to cause an error if the
        parameter specifying the memory address is static and the program has
        been written correctly.

        The best policy under these conditions is to make a thorough error
        checking even with the penalty of some overhead during debugging, and
        then remove all error checking once debugging is complete.  This is
        made possible under the architecture of ITRON specification where
        there is provided a very high degree of freedom in error check on/off.

  - Runs on many hardware platforms.
        There is a series of ITRON specification operating systems operating
        on many hardware platforms from 8-bit MCUs to 32-bit high-performance
        microprocessors.  While it is true that object compatibility of all
        programs is not possible given different CPU sizes and bit widths,
        the fact that a family of ITRON specification operating systems can be
        implemented on various processors is very advantageous in improving
        efficiency by allowing a standardized development process and
        uniformity in learning.

        Furthermore, uITRON 3.0 specification has new functions (connection
        functions) for distributed systems connected with a loosely-coupled
        network.  Even simple serial lines may be used to implement these
        communication functions.  Consideration has been given not just to
        the CPU, but to the entire network and peripheral devices for support
        of hardware of any scale.

        Being able to run on many hardware platforms makes the system highly
        applicable from the standpoint of costs.  On the low-end, the uITRON
        specification may even be used as a very inexpensive control system
        embedded in an electrical appliance.  On the high-end, the ITRON-MP
        specification may be used in a high-performance, tightly-coupled
        multiprocessor system.

  - Serious consideration has been given to ease of learning.
        One aspect of the design concept of ITRON specification is that
        serious consideration has been given to learning process because
        uniformity in its learning is considered one of the important assets
        of a system.

        System call names and functions of ITRON specification are
        systematically defined according to uniform naming conventions which
        make them easy to remember.  All system calls of ITRON specification
        are seven or eight characters long and of the form 'xxx_yyy' or
        'zxxx_yyy' respectively, where 'xxx' represents the method of
        operation, and 'yyy' the object of the operation (Figure 2).  The 'z'
        used in eight-letter system calls represents system calls which are
        derived from the seven-letter system calls excluding 'z'.  Table 1
        shows the specific abbreviations and what they stand for in xxx, yyy
        and z forms.

        Since ITRON specification operating systems run on more than one type
        of processor, learning process in understanding the operating system
        can be made consistent even if more than one type of processor are
        used.  This is a great advantage when it comes to actual program
        development.



         +---------+---------+---------+
         | cre_tsk | del_tsk | sus_tsk | <------ Task
         +---------+---------+---------+
         | cre_sem | del_sem | sig_sem | <------ Semaphore
         +---------+---------+---------+
         | cre_flg | del_flg | set_flg | <------ Eventflag
         +---------+---------+---------+
              ^         ^         ^
              |         |         |
         Creation  Deletion  Other Operations

 Note: System call names of ITRON specification follow the form 'xxx_yyy',
       where 'xxx' is a three-letter abbreviation representing the type of
       operation, and 'yyy' is a three-letter abbreviation representing the
       type of object on which the operation is to be performed.

        Figure 2 System Call Naming Conventions in ITRON Specification


 Table 1  Abbreviations Used in Naming Conventions of ITRON Specification

 +-----------------------------------+--------------------------------+
 |   xxx (operation) Abbreviations   |           Description          |
 +-----------------------------------+--------------------------------+
 |                cre                | Create                         |
 |                del                | Delete                         |
 |                ref                | Refer                          |
 |                def                | Define                         |
 |                ret                | Return                         |
 |                dis                | Disable                        |
 |                ena                | Enable                         |
 |                get                | Get                            |
 |                set                | Set                            |
 |                snd                | Send                           |
 |                rcv                | Receive                        |
 |                can                | Cancel                         |
 |                rel                | Release                        |
 |                wup                | Wakeup (also used in yyy form) |
 |                wai                | Wait (also used in yyy form)   |
 |                chg                | Change                         |
 +-----------------------------------+--------------------------------+


 +-----------------------------------+--------------------------------+
 |    yyy (object) Abbreviations     |           Description          |
 +-----------------------------------+--------------------------------+
 |                tsk                | Task                           |
 |                flg                | Eventflag                      |
 |                sem                | Semaphore                      |
 |                mbx                | Mailbox                        |
 |                mbf                | MessageBuffer                  |
 |                por                | Port                           |
 |                mpl                | MemoryPool                     |
 |                mpf                | Fixed-size MemoryPool          |
 +-----------------------------------+--------------------------------+
 |                int                | Interrupt, Interrupt Handler   |
 |                cyc                | Cyclic Handler                 |
 |                alm                | Alarm Handler                  |
 +-----------------------------------+--------------------------------+
 |                msg                | Message                        |
 |                rdv                | Rendezvous                     |
 |                blk                | Memory Block                   |
 |                blf                | Fixed-size Memory Block        |
 |                tim                | Time                           |
 |                dsp                | Dispatch                       |
 |                cpu                | CPU                            |
 |                dat                | Data                           |
 |                ver                | Version Information            |
 +-----------------------------------+--------------------------------+

 +-----------------------------------+--------------------------------+
 | z (derivation type) Abbreviations |           Description          |
 +-----------------------------------+--------------------------------+
 |                t                  | with Timeout                   |
 |                p                  | Poll                           |
 |                f                  | Force                          |
 |                n                  | Node, coNNection, Network      |
 |                i                  | task Independent, Interrupt    |
 +-----------------------------------+--------------------------------+

****************************************************************************
***    1.6 The Basic ITRON Concept                                       ***
****************************************************************************

***  Tasks *****************************************************************

Under ITRON specification the term "task" refers to a unit of concurrent
processing.  While programs inside a single task are executed sequentially,
programs of different tasks are executed concurrently.  However, this refers
to the way an application programmer (or OS user) looks at things.  At the
physical level, tasks are actually executed under the control of the OS using
time sharing.

The task being executed by the processor is switched by the issue of a
system call or interrupt which causes the task's state to change.  The act of
switching the task being executed by the processor is called "dispatching".
The mechanism in the OS which executes this is called the "dispatcher".

When there is more than one executable task, it is necessary to determine
order of task execution using some sort of algorithm.  The OS act of
controlling the order of task execution is called "task scheduling".  ITRON
specification uses priority-based scheduling based on a priority level
assigned to each task. The smaller the priority value, the higher the priority
level.  The priority level of an ITRON specification task has absolute
weighting: as long as a task of higher priority is executing, no tasks of
lower priority are allowed to execute.  This means that among all executable
tasks, only the task having the highest priority will execute.  No other tasks
will execute unless higher priority task becomes unexecutable for some reason
such as blocking.  In this respect, ITRON specification entirely differs from
a TSS (Time Sharing System) which attempts to divide time among multiple tasks
(or processes) to execute them as equally as possible.  This fundamental
concept that task priority level is absolute remains true even on
multiprocessor-based systems where it is possible for multiple tasks to
execute simultaneously on more than one processor.

ITRON specification uses a number, called a task ID, to designate a task.
The maximum number of tasks which can exist simultaneously depends on the
implementation of ITRON specification and/or hardware configuration as well
as contents of the configuration table of the target system.

Information used for managing tasks must be maintained somewhere in order for
ITRON specification OS to control the execution of many tasks and achieve
multitasking.  This location is called the task control block (TCB).  In
principle, the contents of the TCB are not visible to the user.  Settings and
changes to values inside the TCB are handled by the ITRON specification OS
through system calls.  In the case of ITRON specification, the following type
of information is commonly found inside the TCB.  Note however that this can
be implementation dependent.

  - A group of flags indicating the states of the task
  - Task priority level
  - A storage region for program counter, general-purpose registers and
    stack pointer used by the task
  - Task start address

***  Resources *************************************************************

Elements necessary for the execution of a task are called "resources".  Common
resources include hardware such as the processor, memory and I/O devices, and
software such as files and programs.  Most resources cannot be used by more
than one task at a time, so the OS must exclusively assign the limited
resources of the system to those tasks which are executing concurrently.
ITRON specification provides many synchronization and communication functions
for exclusively assigning resources.

***  Task State and Operation **********************************************

Figure 3 shows task states and the system calls which cause transitions
between those states in ITRON specification.  There are five task states in
ITRON specification:

[1] RUN state

    This state indicates the task is currently executing.

[2] READY state

    This state indicates that the task is ready to execute, but cannot because
    a task of higher priority (sometimes same priority) is already executing.
    Note that a task may execute at any time once the processor becomes
    available.  If there is more than one task in the READY state, they will
    form a queue to wait for the processor.  This queue is called the "ready
    queue".

[3] (General) Wait state

    This state indicates that the task cannot execute because conditions
    necessary for execution have not yet been met.  In other words, the task
    is waiting for these conditions to be met.  After a task wakes up from the
    general wait state, execution will restart from the location it was
    previously suspended.  Information representing the state of program
    execution (called "context") such as the contents of the program counter
    and registers are recalled from their previous state.  In general wait
    state, a task keeps the resources (except for processor) such as
    semaphores occupied.  General wait state can be further classified into
    three types:

    [3.1] (Specific) WAIT state

        This state differs from SUSPEND state [3.2], in that the task
        suspends execution due to a system call it has issued itself.

    [3.2] SUSPEND state

        This indicates a state where a task has been forcibly made to suspend
        execution by another task.

    [3.3] WAIT-SUSPEND state

        This state indicates that the conditions of both WAIT state [3.1],
        and SUSPEND state [3.2], apply.

    Under ITRON specification the difference between WAIT state and SUSPEND
    state is very clear: a task cannot put itself in SUSPEND state.  Note that
    when the term "WAIT state" is used it usually means the specific WAIT
    state described in [3.1].

[4] DORMANT state

    This state indicates the task is not yet executing or has already exited.
    Newly created tasks always begin in this state.  This state differs from a
    general wait state in several respects: all resources are free; the
    contexts of registers and program counter are initialized when the task
    starts; and any task management system calls (wup_tsk, ter_tsk, sus_tsk,
    chg_pri, etc.) issued to a task in this state will result in an error.

[5] NON-EXISTENT state

    This indicates a virtual state where the task in question does not exist
    on the system because it has not yet been created or has already been
    deleted.

Note that it is implementation dependent whether or not uITRON specification
OS supports SUSPEND state [3.2], WAIT-SUSPEND state [3.3], DORMANT state [4],
and NON-EXISTENT state [5].

One feature of ITRON specification is that system calls used by a task to
control itself and those used by a task to control other tasks have been
clearly divided (Table 2), in order to clarify task state transitions and
simplify the understanding of system calls.  Saying that system calls are
classified into those which act on an issuing task itself and those which act
on another task is another way of saying that the state transition resulting
from each system call is clearly classified as to whether the transition
begins from RUN state or another state.


        Table 2 Distinction of System Calls Acting on the Issuing Task
               or Another Task and Associated State Transitions

 +--------------------+---------------------------+-----------------------+
 |                    |System Calls Acting on the |System Calls Acting on |
 |                    |Issuing Task               |Another Task           |
 |                    |(state transition from RUN |(state transition from |
 |                    |state)                     |other state than RUN   |
 |                    |                           |state)                 |
 +--------------------+---------------------------+-----------------------+
 | Transition of a    |         slp_tsk           |        sus_tsk        |
 | Task to Wait State |        RUN state          |  READY or WAIT state  |
 | (including SUSPEND |            |              |           |           |
 | state)             |            v              |           v           |
 |                    |        WAIT state         |       SUSPEND or      |
 |                    |                           |   WAIT-SUSPEND state  |
 +--------------------+---------------------------+-----------------------+
 | Task Exit or       |         ext_tsk           |        ter_tsk        |
 | Termination        |        RUN state          |  READY or WAIT state  |
 |                    |            |              |           |           |
 |                    |            v              |           v           |
 |                    |      DORMANT state        |     DORMANT state     |
 +--------------------+---------------------------+-----------------------+
 | Task Deletion      |         exd_tsk           |        del_tsk        |
 |                    |        RUN state          |     DORMANT state     |
 |                    |            |              |           |           |
 |                    |            v              |           v           |
 |                    |    NON-EXISTENT state     |   NON-EXISTENT state  |
 +--------------------+---------------------------+-----------------------+

 Note: For the purpose of clarifying task state transitions and simplifying
       the understanding of system calls, system calls under ITRON
       specification are clearly divided into those which act on the issuing
       task itself and those which act on another task.  Specifically, this
       means that system calls are divided into groups based on whether they
       cause a transition from RUN state or from other state.



+-------------+ ---------------- dispatch ---------------> +-----------+  -+
| READY state | <--------------- preempt  ---------------- | RUN state |   !
+-------------+ <--+ Wait Condition    Wait Condition +--- +-----------+   !
  | ^ ^ |          | is Satisfied                     |            | |   (*1)
  | | | |          |         +------------+           |            | |     !
  | | | |          +-------- | WAIT state | <---------+            | |     !
  | | | |                    |            | Forcibly Terminate     | |     !
  | | | |                    +------------+ --------------+        | |    -+
  | | | |                        |  ^       (ter_tsk)     |        | |
  | | | |                        |  |                     |        | |
  | | | |              Suspend   |  | Resume              |        | |
  | | | |              (sus_tsk) v  | (rsm_tsk, frsm_tsk) |        | |
  | | | |                   +--------------+ Forcibly     |        | |
  | | | |             +---> | WAIT-SUSPEND | Terminate    |        | |
  | | | |             |     |    state     | -------------+        | |
  | | | |             +---- +--------------+ (ter_tsk)    |        | |
  | | | |                          |                      |        | |
  | | | |                          | Cancel Wait          |        | |
  | | | |                          |                      |        | |
  | | | | Suspend                  v                      |        | |
  | | | | (sus_tsk)           +----------+ Forcibly       |        | |
  | | | +-------------------> | SUSPEND  | Terminate      |        | |
  | | +---------------------- |  state   | ---------------+        | |
  | |  Resume                 +----------+ (ter_tsk)      |        | |
  | |  (rsm_tsk, frsm_tsk)      |      ^                  |        | |
  | |                           |      |                  |        | |
  | |                           +------+                  |        | |
  | |                                       Forcibly      |        | |
  | | Start (sta_tsk)         +----------+  Terminate     |        | |
  | +------------------------ | DORMANT  | <--------------+        | |
  +-------------------------> |  state   | <-----------------------+ |
Forcibly Terminate (ter_tsk)  +----------+ Exit (ext_tsk)            |
                                ^      |                             |
                                |      |                             |
                         Create |      | Delete                      |
                      (cre_tsk) |      v (del_tsk)                   |
                            +--------------+                         |
                            | NON-EXISTENT | Exit and Delete         |
                            |    state     | (exd_tsk)               |
                            +--------------+ <-----------------------+

         (*1) Task states mandatory for uITRON specification OS

 Note: It is implementation dependent whether or not uITRON specification
       OS supports SUSPEND state, WAIT-SUSPEND state, DORMANT state, and
       NON-EXISTENT state.

       This state transition diagram is only intended to illustrate typical
       state transitions.  Depending on the implementation, state transitions
       not shown here may occur as well.

        Figure 3 Task State Transition Diagram in ITRON Specification

***  Task Scheduling *******************************************************

Under ITRON specification, task scheduling is conducted based on task priority.
If there are some tasks of the same priority scheduling is conducted on "first
come, first served" (FCFS) basis.  Figure 4 shows examples of how scheduling
is done.

Figure 4(a) shows the state of the ready queue after Task A (priority 1),
Task E (priority 3), and Tasks B, C and D (all of priority 2), have started
in the order given.  Conceptually, the ready queue includes not only tasks in
the READY state, but the task in the RUN state as well.



   Head of the Ready Queue
   +-----------------+
   |          --------------+
   +-----------------+      |
                            |
 Priority                   |
   High     <Priority 1>    +---> [Task A] --->---+
    ^                                             |
    |                       +---------------------+
    |                       |
    |       <Priority 2>    +---> [Task B] ---> [Task C] ---> [Task D] ---+
    |                                                                     |
    |                       +---------------------------------------------+
    |                       |
    |       <Priority 3>    +---> [Task E] --->
    v
   Low

                Figure 4(a) Beginning State of the Ready Queue


   Head of the Ready Queue
   +-----------------+
   |          -------------+
   +-----------------+     |
                           |
  Priority                 |
   High     <Priority 1>   |
    ^                      |
    |                      |
    |                      |
    |       <Priority 2>   +---> [Task B] ---> [Task C] ---> [Task D] ---+
    |                                                                    |
    |                      +---------------------------------------------+
    |                      |
    |       <Priority 3>   +---> [Task E] --->
    v
   Low

   Figure 4(b) State of the Ready Queue After Task A Enters the WAIT State


Since the task in RUN/READY state having the highest priority is Task A,
only Task A is executed.  Priority under ITRON specification is absolute, so
all tasks having a priority lower than Task A must wait while Task A is
executing (except on multiprocessor systems).

If Task A enters the specific WAIT state issuing a system call,
the state of the ready queue becomes like that shown in Figure 4
(b).  At this point, there are three tasks all having the same priority: Tasks
B, C and D.  Under ITRON specification, the task which entered RUN/READY state
first is executed first when there are more than one task having the same
priority.  So, in this example, Task B is executed next.  This is called
"first come, first served" (FCFS) scheduling.  Under ITRON specification,
FCFS scheduling is used for tasks having the same priority.

If an external interrupt occurs at this time, tasks will be re-scheduled
when the interrupt handler is finished.  Even so, Task B will
continue executing even after the return from the interrupt handler unless a
task having higher priority than B has transited to READY state.  In other
words, Task B does not lose execution privileges due to the occurrence of an
interrupt.

If Task X having a priority higher than Task B were to transit to READY state
in the interrupt handler, Task B would be moved from RUN to READY state.  In
this case, we say "Task B was preempted".  Even if this happens, Task B's
position in the ready queue does not change: it does not move to the end of
the ready queue.  Once Task X exits, Task B will be re-executed, not Task C or
D.  The reason for this specification is that there is no direct relationship
between external interrupt or task which manage the interrupt and
task which are executing during the occurrence of the interrupt
(those which are interrupted).

On the other hand, a task which has entered specific WAIT state and then
returns to READY state will be placed at the end of the ready queue
corresponding to its priority.

It is implementation dependent where a task which has been forced to enter
SUSPEND state and is later resumed by the rsm_tsk system call will enter the
ready queue among tasks of corresponding priority (including those in RUN
state).

It is possible to dynamically change the priority of a task using the chg_pri
system call.  The user of uITRON 3.0 specification OS can specify at least
1 through 8 as task priority levels.

ITRON specification provides the rot_rdq system call for rotating tasks having
the same priority on the ready queue.  This system call may be used to
explicitly move Task B in the previous example to the end of the ready queue.
The user can implement round robin scheduling of same priority tasks (a method
under which execution of the next task takes place after a given time has
elapsed) when this method is preferred over FCFS scheduling.  Specifically,
round robin scheduling may be implemented by using an interrupt handler
invoked by timer interrupt periodically, or using a cyclic handler, to issue
the rot_rdq system call.

***  System State During Non-Task Portion Execution ************************

When programming tasks which will run on an ITRON specification operating
system, one need only look at a task transition diagram and follow changes in
each task's state.  But sometimes the user will need to program at some other
level closer to the kernel than tasks, such as an interrupt handler or an
extended SVC handler.  In such cases, it is necessary to know the system state
during the execution of non-task portions in order to program correctly.  This
section describes system states of ITRON specification.

System states of ITRON specification can be classified as shown in Figure 5.

Of the states shown in Figure 5, the "transitional state" corresponds to OS
execution (system call execution).  It is very important from the user's
perspective that each system call issued by the user program is executed
indivisibly.  The internal state during system call execution cannot be seen
by the user.  The system state during OS execution is considered to be
"transitional state" in which all internal processing handled within a black
box.   There is an exception however.  System calls used to implement the
connection function (allowing the objects to be operated across nodes) of
uITRON 3.0 specification OS are not executed indivisibly because the calls
are communicated over the network during execution.



                                        +-- Transitional state
                                        |   such as executing the OS
                                        |
                                        +-- Task-independent portions
                                        |   such as the interrupt handler
                                        |
 System State --+-- Non-task portions  -+
                |                       |
                |                       +-- Quasi-task portions
                |                           (implementation dependent)
                |                           such as the extended SVC handler
                |                           (OS extension)
                |
                +-- Task portions

                Figure 5 System States in ITRON Specification


"Task-independent portions" and "quasi-task portions" correspond to the system
state during handler execution.  Handlers which include task context are
called "quasi-task portions", while those having contexts independent of any
task are called "task-independent portions".  Specifically, the extended SVC
handler, used to process extended system calls defined by user, is a quasi-
task portion, while the interrupt handler and timer handler, started by
external interrupt, are task-independent portions.  Quasi-task portions
follows the concept of the same state transitions associated with a
task, and they may even issue system calls to enter WAIT state.  It is
implementation dependent whether or not quasi-task portions are available
under uITRON 3.0 specification OS.

Under ITRON specification, the transitional state, task-independent portions
and quasi-task portions are referred to collectively as "non-task portions".
All other states where task programs are being executed normally fall into the
category "task portions".

***  Task-Independent and Quasi-Task Portions ******************************

The main feature of the task-independent portion (the interrupt handler and
timer handler) is that it is meaningless to specify the task which was
executing just before the task-independent portion began.  In other
words, there is no concept of an "issuing task".  Accordingly, system calls for
entering WAIT state and those which implicitly specify the issuing task
itself cannot be issued from the task-independent portion.  Since the
currently executing task cannot be specified from the task-independent
portion, no task dispatching is performed here.  Even if dispatching is
required, it is delayed until the task-independent portion has finished.
This is the rule of what is called "delayed dispatching".

If dispatching were required within the interrupt handler, which is a
task-independent portion, problems could potentially occur in the case of
nested interrupts.  That is to say, the task to be started were allowed to
execute before the rest of the interrupt handler.  This is shown in Figure 6.

In Figure 6, Interrupt X has occurred during the execution of Task A, and
another Interrupt Y, having an even higher priority,  has occurred inside the
associated interrupt handler.  In this case, if Task B is dispatched
immediately after the return from Interrupt Y (1), the execution from (2) to
(3) for Interrupt X will be left over after Task B, and will not be started
until Task A enters RUN state.  This means there is a chance that a low
priority interrupt handler, such as for Interrupt X, may be preempted not
only by a higher priority interrupt, but even by a task, such as Task B,
started by that interrupt.  This situation would make it impossible to
guarantee that interrupt handlers have priority of execution over tasks.
This would make it impossible to write interrupt handlers.  This is the
reason that delayed dispatching is used under ITRON specification.

The main feature of quasi-task portions is that they may specify the task
(issuing task) which was executing just before entering the quasi-task
portion.  The task states are defined here as they are in the task portions. It
is even possible to enter WAIT state inside a quasi-task portion.  Obviously,
dispatching occurs inside a quasi-task portion just as it does during
execution of a task.  As a result, even though they are considered non-task
portions, quasi-task portions such as OS extensions do not necessarily always
execute with priority over task portions.  This contrasts greatly with the
situation with interrupt handlers which always execute with priority over all
of the tasks.



           | : Task-independent portion
           ! : Task portion

        Task A            Task B          Interrupt X         Interrupt Y
    (low priority)   (high priority)    (low priority)      (high priority)
           !
           !
 Interrupt +--------------------------------->+
                                              |
                                              |
                                   Nested     +------------------->+
                                   interrupt                       |
                                                                   |
                                                                wup_tsk B
                                                                   |
                                                                   |
                                          (2) +<----------------ret_int (1)
                                              |
                                              |
                                           wup_tsk C
                                              |
                                              |
                      (4) +<---------------ret_int (3)
                          !
                          !

       Note: If dispatching were performed at (1), the rest of the
             Interrupt X handler (from (2) to (3)) would not execute
             until after Task B suspended.

              Figure 6 Interrupt Nesting and Delayed Dispatching


The next two examples illustrate the differences between task-independent
portions and quasi-task portions.

  - An interrupt occurs during the execution of Task A, which has priority 8
    (low).  The associated interrupt handler (a task-independent portion)
    issues a wup_tsk system call on Task B, which has priority 2 (high).
    However, due to delayed dispatching Task B is not dispatched at this point.
    The rest of the interrupt handler is allowed to execute after wup_tsk
    is invoked.  After ret_int is called at the end of the interrupt handler,
    dispatching is performed and Task B is executed.

  - An extended system call is executed from Task A, which has priority
    8 (low).  The associated extended SVC handler (a quasi-task portion)
    issues a wup_tsk system call on Task B, which has priority 2 (high).
    Since delayed dispatching is not applied here, Task B is dispatched
    immediately by wup_tsk.  Within the quasi-task portion, Task A enters
    READY state, while Task B enters RUN state.  Accordingly Task B executes
    before the rest of the extended SVC handler does.  The rest of the
    extended SVC handler executes after Task A is re-dispatched and enters RUN
    state.

***  Task States During a Dispatch Delay ***********************************

Dispatching of tasks in ITRON specification may be temporarily disabled, due to
delayed dispatching, or when a system call is issued that disables dispatching.
During that time, task states are as explained below.

During the time dispatching is disabled, even if a situation occurs that would
normally call for a running task to be preempted, the task that would preempt
it is not dispatched.  The dispatching of the latter task is delayed until
dispatch disabled state is cleared.  While the dispatch is delayed, the running
task remains in RUN state, and the task to be executed after dispatch disabled
state is cleared is treated as in READY state.  As for the order of tasks in
RUN state in the ready queue during a dispatch delay, this is an
implementation-dependent matter.

If, while dispatching is disabled, sus_tsk call is issued for the running task
to put it in SUSPEND state, or if ter_tsk is issued to put it in DORMANT state,
the task transition is delayed until dispatch disabled state is cleared.
During this time, the running task is considered to be in a transient state,
with the specific handling of this status an implementation-dependent matter.
Here too, the task to be executed after dispatch disabled state is cleared is
treated as in READY state.

***  Objects ***************************************************************

Under ITRON specification, an object is any item (such as a task) which is
handled by system call and identified by an ID number.  In addition to tasks,
objects include synchronization and communication mechanisms such as memory
pools, semaphores, eventflags and mailboxes.  The OS provides an object
management table (task control block (TCB) in the case of tasks) for each type
of object.

***  Concepts of Standardization and Compatibility in ITRON Specification **

ITRON specification is intended for a standard operating system implemented
on various processors.  However, to prevent the degradation in performance
caused by standardization and processor virtualization, room for variation is
allowed in a specification so that the architecture of each target processor
may be utilized to its fullest potential.  Since the execution environment
under ITRON specification OS will be widely varied depending on the hardware
of the target system, it is difficult to guarantee object level compatibility
even if strict OS specifications are given.  The idea is therefore to
loosen OS specifications so that performance can be enhanced for each
implementation.  For this reason, there is no complete guarantee of
compatibility under ITRON specification in cases where the target processor or
the implementation of operating system differs.

The ITRON specification provides the following as standard specifications.

  - System call functions and names
  - Parameter types and names
  - Error code classes, names and values
  - Function code (numbers for identifying system calls)
  - Protocol and packet format for implementing the connection function (for
    networking systems)

Due to their close relation to processor architecture, the standard
specification says nothing regarding items such as how parameters are passed,
the bit length of parameters or how system calls are invoked.  These parts of
the specification are left processor and implementation dependent.

While the ITRON specification gives no guarantee of complete compatibility, the
following facts remain true regarding ITRON as a real-time OS specification.

  - Using standardized system call names and terminology, its understanding
    and learning can be simplified.

  - Parts of programs requiring modification during porting can be made clear
    by the ITRON specification OS implementor indicating differences from the
    standard specification.

  - Standardizing communication protocol specifications for implementation of
    the connection function under uITRON 3.0 specification allows connecting
    different implementations of the OS.

****************************************************************************
***    1.7 uITRON 3.0 Specification Overview                             ***
****************************************************************************

This section gives a description of a new member of the ITRON specification
family: uITRON 3.0 specification.

***  Position of uITRON 3.0 Specification **********************************

uITRON 3.0 specification is based on the following design concept and
features.

(a) Main ITRON specifications have been brought together

uITRON 3.0 specification is a version upgrade based on feedback from
experience with ITRON1, ITRON2 and uITRON 2.0 specifications.  ITRON2 and
uITRON 2.0 specifications are unified under uITRON 3.0 specification by
including object creation and deletion functions (cre_??? and del_???) and
messagebuffer and rendezvous functions of ITRON2 specification not found in
uITRON 2.0 specification.  Several other system calls such as dis_dsp
(disable dispatch) and ref_sys (reference system) have also been added.

(b) A connection function has been added

A connection function for supporting the loosely-coupled networking of ITRON-
based machines have been added to uITRON 3.0 specification.  Specifically,
with CPUs implementing uITRON 3.0 specification OS being connected, system
calls can directly control objects (such as tasks and semaphores) which exist
on other nodes.

The ITRON specification supporting a connection function was originally called
ITRON-N specification during the research stage; uITRON 3.0 specification came
to subsume the ITRON-N specification because work on the version upgrade of
uITRON specification was being carried out at the same time.  The 'N' in
ITRON-N specification can be taken to stand for Network, Node or coNNection.

(c) Enhanced standardization and adaptability

The conventional ITRON specification, particularly uITRON 2.0 specification,
included many implementation-dependent parts.  Implementation-dependent
specifications have been cleaned up under uITRON 3.0 specification as much as
possible under the condition that the benefit for system adaptability not be
compromised.  Furthermore, the number of system call levels has been reduced
for increased application compatibility.

[Rationale]

Under uITRON 3.0 specification, the function which allows the control of
objects on other nodes is called the "connection function".  The connection
function is sometimes called network function for convenience.  The reason
they are not called "communications functions" is so that they may be
distinguished from synchronization and communication mechanisms such as
mailboxes.

Choice of the term "node" is used to suggest that systems are not so tightly-
coupled (for example, their address space is kept separate), and that embedded
systems are being referred to.  While the terms "machine", "host" and "site"
may also be conceivable, these terms convey a sense of a larger system, and
seem removed from the typical image of an embedded one.  The term "processor"
also could be used, but it would become more difficult to make a clear
distinction from a tightly-coupled network.

***  Levels of uITRON 3.0 Specification ************************************

uITRON 3.0 specification is divided into fewer system call levels than was the
previous uITRON 2.0 specification.  There are now just three levels: Level R
(Required), Level S (Standard) and Level E (Extended).  In addition to these
three levels, there is also Level C for CPU-dependent system calls.

  - [level R] (Required)
        The functions in this level are mandatory for all implementations of
        uITRON 3.0 specification.  This includes basic functions for achieving
        a real-time, multitasking OS.  These functions can be implemented even
        without a hardware timer.  This level corresponds to Levels 1 and 2
        of uITRON 2.0 specification.

  - [level S] (Standard)
        This includes basic functions for achieving a real-time, multitasking
        OS.  This level corresponds to Levels 3 and 4 of uITRON 2.0
        specification.

  - [level E] (Extended)
        This includes additional and extended functions.  This corresponds to
        functions not included in uITRON 2.0 specification (functions of
        ITRON2 specification).  Specifically, this level includes object
        creation and deletion functions, rendezvous functions, memorypools
        and the timer handler.

  - [level C] (CPU dependent)
        This level provides implementation-dependent functions required due to
        the CPU or hardware configuration.

The support level of the connection function is indicated by appending an 'N'
to the end of the level.  For example, connectivity supported at [level S]
would be referred to as [level SN].  The support level for functions which
can only send requests for operations on other nodes but offer no system call
processing on the issuing node itself are indicated by the lower case letter
's' or 'e'.

Support level under uITRON 3.0 specification can thus be symbolically
indicated as follows.

  No connection functions                         x    (x = R, S, E)
  Connection functions supported                  xN   (x = R, S, E)
  Connection functions supported (requests only)  xNy  (x = R, S; y = s, e)

    [Examples]

        ** [level SN] **
          - Level [R], [S], [RN] and [SN] system calls may be used if the
            node which is the target of the system call is the issuing node
            itself.
          - If the node which is the target of the system call is a node other
            than the issuing node, the following is true.
                Level [RN] system calls may be used if the target node's level
                is [level RN].
                Level [RN] and [SN] system calls may be used if the target
                node's level is [level SN] or [level EN].
          - If this node is the target of a system call issued by another node,
            the following is true.
                Level [RN] system calls may be used if the level of node
                issuing the system call is [level RN].
                Level [SN] system calls may be used if the level of node
                issuing the system call is [level SN] or [level EN].

        ** [level SNe] **
          - If the node which is the target of the system call is a node other
            than the issuing node, the following is true.
                Level [RN] system calls may be used if the target node level
                is [level RN].
                Level [RN] and [SN] system calls may be used if the target
                node's level is [level SN].
                Level [RN], [SN] and [EN] system calls may be used if the
                target node's level is [level EN].
          - All other cases are the same as for [level SN].

An EN_RSFN error will result if a system call of a level not supported by the
target node is issued using the connection function.  For example, an EN_RSFN
error will result if a Level [EN] system call is issued to a [level SN] node.

A table showing the support level classification of each system call is given
in Chapter 6 "Reference".

The support levels outlined above indicate the level whether each system call
is supported.  It is sometimes possible, however, to introduce extended
features into some system calls for which no compatibility is guaranteed.
These functions are called "[level X]" functions.  [level X] functions
include the following.

  - Task priority attributes for semaphore and mailbox queues
  - Multiple task wait for eventflags
  - Added information for ref_tsk
  - A function for nesting sus_tsk calls
  - A function for queuing more than two wup_tsk calls
  - A function for specifying initial values and upper limit values for
    semaphores

In order to maintain compatibility under uITRON 3.0 specification, support
of system calls of level [R] and higher is required.  The following conditions
must therefore be met for implementation of uITRON 3.0 specification to be
compliant.

   1) The implementation must provide at least the three task states: RUN,
      READY and WAIT.  (uITRON specification is that of multitasking OS.)
      An implementation may also support other task states (such as DORMANT
      and SUSPEND) as necessary.

   2) Interrupt handlers may be defined.  A means must be available for waking
      up tasks from an interrupt handler by issuing some sort of system
      call.  (uITRON specification is that of real-time OS.)
      Interrupt handlers may be defined statically (during system
      initialization) or by using the def_int system call.

   3) All level [R] and [RN] system calls are available.
      The connection function does not need to be supported.  Level [RN]
      system calls (such as sig_sem) can only be used provided that all
      the functions are available except for connectivity functions.

[Differences from uITRON 2.0 and ITRON2 Specifications]

Although system call support was divided into five levels under uITRON 2.0
specification, this was mainly to emphasize educational compatibility.  The
level classification itself was no more than a guideline.  Under uITRON 3.0
specification, the meaning of level classifications has been revised to be
much more rigid. Furthermore, support of level [R] and [RN] system calls is
now mandatory.

****************************************************************************
***    1.8 Implementation-Dependent Functions                            ***
****************************************************************************

The uITRON 3.0 specification allows the introduction of implementation-
dependent functions to make it more adaptable to various processors,
implementations and systems, and the guidelines have been prepared.  This
section describes the implementation-dependent functions of uITRON 3.0
specification.

***  Issuing System Calls from Task-Independent Portions *******************

Under uITRON 3.0 specification, the types of system calls which may be issued
from task-independent portions are implementation dependent.  However, a
method must be provided for waking up tasks (releasing the task's WAIT state)
from an interrupt handler by issuing some sort of system call.

Under uITRON 3.0 specification, system calls which can be issued from task-
independent portions (interrupt handlers and timer handlers) may be completely
separated from those which can be issued from tasks so that OS performance
may be increased by avoiding the overhead associated with determining context
within the OS.  The lower case letter 'i', standing for "independent" or
"interrupt", is therefore prefixed to the names of system calls which may be
issued from a task-independent portion.  This results in names of the form
i???_???.

For example, the system call named wup_tsk, used for waking up tasks, may be
used with its name unchanged when issued from the task portion.  In contrast,
depending on the implementation, either wup_tsk or iwup_tsk may be used when
issuing the system call from an interrupt handler.  It is probably best in
terms of reducing the load on the OS and increasing the speed of processing
system calls, to separate iwup_tsk from wup_tsk using iwup_tsk when issuing
the system call from task-independent portions and wup_tsk when issuing the
system call from task portions.  On the other hand, it is more convenient from
the user's perspective to use the common wup_tsk system call from both the
task and task-independent portions.  Note that iwup_tsk system call doesn't
provide more functions than wup_tsk which can be issued from task-independent
portions.  Both specifications are provided under uITRON 3.0 specification;
for increased adaptability to various processors and applications, which
specification is used is left up to the implementation.

***  Implementation-Dependent System Call Names ****************************

In addition to implementation-dependent system call names of the form i???_???,
there are also names of the form v???_???.  We recommend that system call
names of this form be used as much as possible when using implementation-
dependent system calls not covered by this standard specification.  As long
as you use names of the form v???_??? there will be no possibility of
contradiction with standard system calls of ITRON specification which may be
added in the future.

***  Implementation-Dependent Error Names **********************************

Use error names of the form EV_???? as a mnemonic for implementation-dependent
errors.  We recommend that error names of this form be used as much as
possible when using implementation-dependent errors not covered by this
standard specification.  As long as you use names of the form EV_???? there
will be no possibility of collision with standard errors of ITRON
specification which may be added in the future.

****************************************************************************
*****                                                                  *****
*****  Chapter 2 The Connection Function of uITRON 3.0 Specification   *****
*****                                                                  *****
****************************************************************************

This chapter describes the connection function support added to uITRON 3.0
specification.


****************************************************************************
***    2.1 Connection Function in Practical Use                          ***
****************************************************************************

***  Concept the Connection Function in Application ************************

A connection function has been added to uITRON 3.0 specification to support
the loosely-coupled networking of ITRON-based computers.  This section
describes the anticipated use of this connection function.

Let's consider as an example a system in which ITRON specification OS is used
to control a robot (Figure 7).  Node A controls the head and face, Node B
controls the hands and arms, while Node C controls the legs and feet.  Control
is divided among Nodes A through C because these are the locations where local
control of devices (such as motors) and processing of information for each the
head, hands and feet are concentrated.

In Figure 7, suppose Node A, controlling the head, wants to start Task e on
Node C, the node controlling the feet.  This could be done as follows without
using the connection function.

   1) The user (application programmer of ITRON specification OS) writes a
      communication program for Nodes A through C.

   2) A message saying "I want you to start Task e" is sent from Node A to
      Node C using this communication program.

   3) Node C receives this message and starts a program (task) which will
      start Task e.



         Node A                   Node B                   Node C
   +-----------------+      +-----------------+      +-----------------+
   | Task a : Task b |      | Task c : Task d |      | Task e : Task f |
   |- - - - - - - - -|      |- - - - - - - - -|      |- - - - - - - - -|
   |   uITRON 3.0    |      |   uITRON 3.0    |      |   uITRON 3.0    |
   |specification OS |      |specification OS |      |specification OS |
   |- - - - - - - - -|      |- - - - - - - - -|      |- - - - - - - - -|
   |  CPU, Hardware  |<---->|  CPU, Hardware  |<---->|  CPU, Hardware  |
   +-----------------+      +-----------------+      +-----------------+

          Figure 7 Connecting CPUs with uITRON 3.0 Specification OS

If the connection function are used instead, it is possible for a program
(task) on Node A, to send out a single system call which directly causes Task e
on Node C to execute.  All the processing represented by steps 1) and 3) above
are handled automatically within the uITRON 3.0 specification OS itself.  As
for step 2), the user does not send a message, but rather issues a system call
(sta_tsk) to start the desired task.  In other words, it is possible to start
tasks on other nodes using the same procedure for starting tasks within the
local node.  This is the result of the connection function of uITRON 3.0
specification.

***  Example Using A MessageBuffer *****************************************

This subsection will describe how the messagebuffer of uITRON 3.0
specification (offering the same function as the messagebuffer of ITRON2
specification) operates when it includes connection function support.

The send messagebuffer (snd_mbf) and receive messagebuffer (rcv_mbf)
specifications are as follows.

        ER ercd = snd_mbf (ID mbfid, VP msg, INT msgsz)
        ER ercd = rcv_mbf (VP msg, INT *p_msgsz, ID mbfid)
                mbfid:    MessageBuffer ID
                msg:      Message address (packet of message)
                msgsz:    Message size
                p_msgsz:  Pointer to memory storing returned message size

No task ID specification is made by the messagebuffer.  Only a messagebuffer
ID is specified.  The only thing that needs to be added to these system calls
to achieve connection function support is the information representing which
node the target messagebuffer exists on.  Since the system call interface
will change if a new parameter representing this information is added, it is
difficult to retain compatibility with old ITRON specifications.

Under uITRON 3.0 specification, therefore, information specifying the node is
included as part of mbfid.  If mbfid is specified as a particular value, that
indicates that it represents a messagebuffer on another node.  Specifically,
a conversion table has been introduced for all system call parameters which
specify ID numbers so that the node number on which objects exist may be found
based on their ID number.  This allows objects on other nodes to be accessed.
This is illustrated in Figure 8.  This conversion table is called an "object
location table", and is specified upon the configuration of each node.

Messagebuffers including connection function support operate as follows.

(A) Message send

  A1. If the messagebuffer specified upon sending exists on the issuing node,
      the message is transferred within the node.  In this case, the operation
      is identical to snd_mbf of ITRON2 specification.

  A2. If the messagebuffer specified upon sending exists on another node, the
      message to be sent is transferred to the node on which the message
      buffer exists, and then waits to be received in that messagebuffer.  If
      the send message cannot be sent at this time because the messagebuffer
      is full, the task sending the message will enter the send queue of the
      messagebuffer on the other node.




         ID No.      Node A      Node B      Node C      Node D
           ||          ||          ||          ||          ||
           \/          \/          \/          \/          \/
                    +------+    +------+    +------+    +------+
                    |  **  |    |  **  |    |  **  |    |  **  |
                    +------+    +------+    +------+    +------+
                                      ...
                    +------+    +------+    +------+    +------+
          M+5       |  **  |    |  **  |    |  **  |    |  **  |
                    +------+    +------+    +------+    +------+
                    +------+    +------------------+    +------+
          M+4       |  **  |    |  **          <=  |    |  **  |
                    +------+    +------------------+    +------+
                    +------------------+    +------------------+
          M+3       |  =>          **  |    |  **          <=  |
                    +------------------+    +------------------+
                    +------------------+    +------------------+
          M+2       |  =>          **  |    |  =>          **  |
                    +------------------+    +------------------+
                    +------------------------------+    +------+
          M+1       |  =>          =>          **  |    |  **  |
                    +------------------------------+    +------+
                    +------------------------------------------+
           M        |  =>          =>          **          <=  |
                    +------------------------------------------+
                                      ...

 Note: Each box depicted above represents a single object.  "=>" and "<="
       indicate that the target object is on another node and is accessed
       using an object location table.  "**" indicate that the target object
       exists on that node.

                  Figure 8 Accessing Objects on Other Nodes


(B) Message receive

  B1. If the messagebuffer specified upon receiving exists on the issuing
      node, the message is read from the messagebuffer within the node.  In
      this case, the operation is identical to rcv_mbf of ITRON2 specification.

  B2. If the messagebuffer specified upon receiving exists on another node,
      the message is read from the messagebuffer on the other node.  In this
      case, the message is first transferred from the node on which the
      messagebuffer exists to the node on which the task receiving the
      message exists.  If the message receive comes before the message send,
      the task receiving the message will enter the receive queue of the
      messagebuffer on the other node.

Actual message transfer may take place in any of the following in combinations:
A1-B1, A1-B2, A2-B1 or A2-B2.  The feature described in B2, where messages are
received from messagebuffers on other nodes, is useful when the destination
node of a message cannot be determined.


***  Scope of the Connection Function Specification ************************

The connection function of uITRON 3.0 specification is not just concerned with
a standardized system call interface.  It is designed for connections between
OS implementations on different hardware and/or from different manufacturers.
For this reason, both communication protocol and packet format have been
standardized outside the OS specification (system call specification) itself
in hierarchical form.



              Node A                               Node B
 +-------------------------------+    +-------------------------------+
 |          Application          |    |          Application          |
 |               :               |    |               :               |
 |    Task a     :    Task b     |    |    Task c     :    Task d     |
 |- - - [A] - - - - - - [A] - - -|    |- - - [A] - - - - - - [A] - - -|
 |                               |    |                               |
 |    uITRON 3.0 Spec. Kernel    |    |    uITRON 3.0 Spec. Kernel    |
 |                               |    |                               |
 |         + - - - - - - - - - - |    |         + - - - - - - - - - - |
 |         : Connection Function |    |         : Connection Function |
 |         :     Server Task     |    |         :     Server Task     |
 |         + - - - - - - - - - - |    |         + - - - - - - - - - - |
 |         : Connection Function |    |         : Connection Function |
 |         :     I/O Driver      |    |         :     I/O Driver      |
 |- - - - - - - - - - - - - - - -|    |- - - - - - - - - - - - - - - -|
 |   CPU,           I/O          |    |   CPU,           I/O          |
 |               Hardware <--------+  |               Hardware <--------+
 +-------------------------------+ |  +-------------------------------+ |
                                   |                                    |
                                   +-[B]---------------------------[B]--+

        Figure 9 Specification Defined for the Connection Function


Figure 9 shows a hierarchic representation of the connection function under
uITRON 3.0 specification.

  [A] System call specification providing connectivity with other nodes
        This specification is concerned with functions provided for
        applications by the OS.  For example, it gives specifications for
        system calls starting tasks on other nodes.  This part of the
        specification is visible to the application programmer.

  [B] Packet specification for communications between nodes
        This specification is concerned with how communication is implemented
        (the protocol and packet format used).  This part of the specification
        is unrelated to the application programmer; only those implementing
        the connection function of uITRON 3.0 specification need to know it.
        It is however necessary to provide a standard specification so that
        different implementations of uITRON 3.0 specification may be connected.
        Since it may often be possible to implement communications at the
        physical and data link layers using an existing protocol implemented
        in hardware (peripheral chips), this layer is mainly concerned with
        the standardization of packet format.

Because uITRON 3.0 specification isolates system call layer from communication
protocol layer, uITRON 3.0 specification OS can adapt to any method of
connection without any changes to system call specifications.  No mention is
therefore made concerning the method of connecting CPUs (closely-coupling or
loosely-coupling, communication methods, protocols and topology).

There is no particular restriction on how the connection function is
implemented.  However, since the kernel should be kept as small as possible to
improve performance as a real-time system, actual network communication
function should be implemented as service tasks (daemons).  The specification
itself can also be implemented in this way.

[Supplementary Notes]

The uITRON 3.0 specification of connection function presumes that
address space need not be shared.  While the connection function of
uITRON 3.0 specification may be used on tightly-coupled multiprocessor
systems, the assets of such tightly-coupled systems to share address space
cannot be utilized to its fullest potential.  It is the ITRON-MP specification
that provides this type of high performance, high level functions that allow
the maximum use of tightly-coupled systems with shared address space.

***  Connection Function Response Wait State *******************************

In order to implement the connection function, it is necessary to communicate
with other nodes via a network.  Accordingly, the execution of system calls
which use the connection functions is time-consuming in general, thus making
it necessary to perform other processing concurrently with communications.
This means that from the user's perspective the execution of system calls
which use the connection function is not executed indivisibly.

The state in which one node waits for another node (the target node) to
respond during communications is handled as a type of WAIT state and is called
the "connection function response wait state".  If ref_tsk is issued on a task
waiting for a response from another node with a system call issued using the
connection function, tskstat will be returned as TTS_WAI (WAIT state).  If the
system implementation allows ref_tsk to return tskwait (reason for task wait),
tskwait will be returned as TTW_NOD (connection function response wait).  Note
however that this return may not always be available because functions which
return tskwait are extended functions [Level X] for whom compatibility and
connection are not guaranteed.

In the case of system calls which actually enter WAIT state such as wai_sem,
which waits for semaphores, the "connection function response wait" state will
continue until the first response from the other node is returned (until the TA
packet is returned).  After that, the task state will become "semaphore wait"
until the WAIT state ends with another task issuing sig_sem.  Since it is
unknown whether or not the system call enters the WAIT state until the first
response is returned (because semaphore wait state does not occur unless the
semaphore count value is positive), the state during this time should be
considered as "connection function response wait" state rather than as
"semaphore wait" state.

****************************************************************************
***    2.2 Significance and Background of the Connection Function        ***
****************************************************************************

***  The Relationship to IMTRON Specification ******************************

IMTRON is an OS intended for implementing Highly Functional Distributed
Systems (HFDS), one of the final goals of the TRON project.  The scale of
IMTRON is very large.  Under IMTRON, computer networks are conceptually
divided into "open networks" and "closed networks".

  - Closed networks
        A human specifies the configuration.
        Network configuration changes little after startup.
        The entire network operates under a single goal.  It is suitable for
        large-scale data processing such as file sharing.
        No distinction is made between local and remote resources, and
        transparency of the network is important.

  - Open networks
        Configuration is set automatically.
        Network configuration changes constantly.
        The purpose of the network is multifold, and all purposes are not
        necessarily known at the outset.  Environment control is also one of
        the purposes, in addition to the sharing of resources.  For example,
        using a sensor network laid out in a room, the ringing of a telephone
        may cause the volume of audio/video equipment to be lowered
        automatically.

IMTRON is greatly different from a conventional LAN (Local Area Network).
A conventional LAN is closer to a closed network, while the IMTRON concept is
closer to an open network.  There are several problems which must be resolved
in order to implement an open network.  For example, it is necessary to
research various algorithms just for the purpose of assigning unique network
addresses to each node.

By the way, it is necessary to first implement a closed network before
trying to implement an open network.  It is therefore necessary to add network
support functions to existing ITRON specification.  This is the connection
function of uITRON 3.0 specification.  A multiprocessor version of ITRON
(ITRON-MP) specification is being researched in addition to the uITRON 3.0
specification of connection function.  The following is a list of differences
among ITRON-MP specification, connection function of uITRON 3.0 specification,
and IMTRON specification.

 (a) ITRON-MP specification
    - Multiprocessor version of ITRON specification.
    - Runs on multiple CPUs for improved performance and fault tolerance.
    - Supports shared memory (tightly-coupled CPUs), providing mailboxes and
      memory pools which are shared among the processors.
    - There is no need for a "connection function response wait" state.

 (b) Connection function of uITRON 3.0 specification
    - A version of ITRON specification supporting the ability to control
      objects on other nodes.
    - Does not support shared memory (loosely-coupled CPUs).
    - Enhances communication abilities by connecting several ITRON-based nodes.
    - The user has to be aware of processor differences.
      For example, the ID number of objects such as tasks and semaphores is
      independently assigned for each processor.  A task on Processor A which
      has ID equal to 1, is a different object than one on Processor B which
      also has ID equal to 1.  Since there is no shared memory, the same can
      be said for memory addresses.

 (c) IMTRON specification
    - A version of ITRON specification in order to implement an open network,
      extending the connection function of uITRON 3.0 specification to support
      HFDS.
    - Low level functions are similar to uITRON 3.0 specification.  Additional
      specifications for high level protocols and operations dependent on
      the use of the network application and the method of reconfiguration
      (such as network registration, assignment of network addresses,
      requests for necessary information and time synchronization) are
      included.
    - The concept is completely different from that for existing LANs.

***  The Relationship with Other Network Systems ***************************

A representative example of a real-time operating system operating on a local
area network (LAN) is TCP/IP support on an Ethernet.  A real-time OS
which supports LAN such as TCP/IP and Ethernet has a merit of connectivity
with development systems using UNIX.

However, a CSMA/CD LAN system such as Ethernet cannot guarantee the execution
time regarding communications with other nodes.  In other words, there is a
problem in that real-time processing across nodes cannot be guaranteed.
Furthermore, a program close to 100 KB in size is necessary just to implement
full TCP/IP functions, making it unsuitable for use in low cost, compact
embedded systems.

So, although LANs using TCP/IP and Ethernet are very convenient for some
applications, they cannot cover all applications.  In particular, because
they must meet the standardized specifications of transceivers, communication
media (wires), and protocols which needs large program to process, the minimum
cost of such a system is determined.  So it is often difficult to apply LANs
using TCP/IP and Ethernet to embedded system.

At the same time, advances in semiconductor technology have led to continual
decreases in price, increases in speed and higher levels of integration for
processors.  For this reason, the demand for distributed processing is growing.

Considering these facts, the uITRON 3.0 specification of connection function
is designed under the concept that it doesn't need low level protocol with
many functions such as TCP/IP, while still introducing an adaptable
specification for internode communications.  In order to build a low cost
computer network using single-chip microcomputers and serial lines, the
protocol layers are also be simplified.  Although it is also possible to
implement the connection function of uITRON 3.0 specification on TCP/IP,
we put emphasis on the possibility that simpler and lower cost communication
paths can be used.  The use of connection function includes communication
between a electronic appliance and remote control box for it, and
communication between the microcomputers in a robot's head and the
microcomputers in its arms.

Under HFDS proposed by the TRON Project, all types of computers embedded in
devices around us (such as household appliances, furniture and the house
itself) will exchange information for the purpose of making a more comfortable
living environment.  The connection function of uITRON 3.0 specification is
the basis of the technology that will make this possible.  Since the computer
network that will be used for this purpose must be of very low cost, existing
LAN technology such as that of TCP/IP and Ethernet will not be enough to meet
these requirements.

***  The Relationship between Conventional ITRON Specification
                                             and Connection Functions ******

The following are the two types of conceivable situations in which systems
may use the connection function of uITRON 3.0 specification.

 A. Newly connecting two nodes which were designed and had been used
    independently.  New functions for communication and exchanging
    information between these nodes are added.

 B. Dividing what had been designed as a single node into several nodes
    (processors) and improving performance by the use of multiple processors.

Although ITRON-MP specification (tightly-coupled, multiprocessor ITRON
specification) can be used in situation B, the connection function of
uITRON 3.0 specification is also suitable as long as most processing is done
locally (shared memory among separated nodes are not used), and functions are
distributed.

There is also a conceptual difference between A and B above in terms of
compatibility.  Since, in the case of A, the connection function (the
capability to operate on objects on other nodes) is merely an extension of
existing capabilities, there is little problem in terms of compatibility
between old functions and those supporting the connection function.  The
compatibility of existing functions other than the connection function is
important.  On the other hand, in the case of B, since processing that was
once handled within a single node must now be handled through the connection
function, the compatibility between existing functions and the connection
function becomes important.  In other words, in order to use added processors,
operations that were once performed on objects on the same node will have to
be performed on objects that are now on different nodes.  Since these
operations will be done through connection functions, the compatibility
between connection functions and their existing counterparts is critical.

The difference of the situations noted above must be considered when the
term of compatibility is discussed.

****************************************************************************
***    2.3 The Meaning of ID Numbers and the Object Location Table       ***
****************************************************************************

***  How Objects on other Nodes are Accessed *******************************

Under existing ITRON specifications which did not support a connection
function, objects on each system (node) had to be identified by a unique ID
number.  In contrast, all objects on a network nodes with uITRON 3.0
specification OS are uniquely identified by a combination of node location
number and object number.  The "object number" is a number which identifies
objects on each node.  The object number therefore corresponds conceptually
to the ID number used under ITRON1, ITRON2 and uITRON 2.0 specification.
Under uITRON 3.0 specification, each ID number included in parameters to a
system call is converted into a pair of node location number and object number
using an object location table (or location table).  This pair is then used
to access objects on each node (local or remote) of the network.  Location
tables exist independently for each type of object.  Note that IDs and object
numbers represent informations in different layers.  An object number can be
interpreted as a type of access address (pointer to a control block of the
object).  The information included in the connection function communication
packet is an object number, not a ID number.

A location table is a collection of mappings of the following type.

                                  f
        (access environment, ID) |-> (node location number, object number)
         env                 id       nod                   objno

 Note: The "access environment" is a definition scope of the ID numbers.
       Under uITRON 3.0 specification, each access environment corresponds
       to each node.

The mapping described above is many-to-one, not one-to-one.  It is therefore
possible that different ID numbers in different access environments
(different nodes) may actually represent the same object.

The concepts outlined above will be applied to IMTRON specification as well.
Note however that the following restrictions are introduced into the mapping
scheme of connection functions of uITRON 3.0 specification.

  (1) The location table is set up when each node is configured, and its
      contents are static.

  (2) There is a one-to-one correspondence of access environments to nodes.
      In other words, the access environment is determined by the node
      location number on which the task issuing a system call exists.  So
      if there are two tasks on the same node, their access environment is
      also the same.

  (3) If there are two mappings of the form (env1, id1) |-f-> (nod1, objno1)
      and (env2, id2) |-f-> (nod1, objno1), then id1 and id2 must be equal.
      In other words, every object must be represented by the same ID number
      regardless of the access environment (or node) from which the object
      is accessed (if the object can be accessed).

Finally, the following operational guideline is introduced into uITRON 3.0
specification.

  (4) The absolute value of ID numbers specifying objects on other nodes
      should be kept as small as possible.

Of the above restrictions, (3) is intended to make programs running across
more than one node (environment) easier to write, and make programs which used
to run on a single node (environment) easier to migrate to run across more
than one node (environment).  However, it may become difficult to introduce
the restriction of (3) into IMTRON specification, large distributed systems
and HFDS in the future, due to the increased necessity for dynamic
configuration.  For this reason, (3) is not an absolute restriction and may
be removed upon future extensions to IMTRON specification.

Also, without restriction (2), it would be possible to establish more than one
environment on a single node, and run different programs using the same ID
simultaneously.  Although this feature is not supported in uITRON 3.0
specification, it may be introduced in a future extension.  For example, as
the number of nodes increases and the scale of the entire system becomes
larger, it becomes difficult for a single system designer to manage all the
objects (tasks, semaphores, etc.) on the entire system (all nodes) and assign
them all appropriate ID numbers.  Under these circumstances, it would be
convenient to design systems separately at the node level, and integrate them
into a single system later.  The technique to establish more than one
environment per node may be used for this purpose.

Guideline (4) is intended to keep the size of location tables as small as
possible.

***  Problems Concerning Return Parameters *********************************

The following problem arises when trying to apply the concept of location
tables (mapping) used in IMTRON specification.

Since mapping is many-to-one, object names (ID numbers) are varied depending
on the environment they are accessed from.  In other words, the object names
(ID numbers) of tasks and other objects are not absolute, but rather relative
depending on the access environment in which the objects exist.  For example,
Object X may be accessed by ID = 5 when accessed from Node A, while accessed
by ID = 8 when accessed from Node B.

When an object ID is returned as a return parameter, the access environment
must also be specified as a parameter for the ID to have any unique meaning.
Since location table mapping is many-to-one, object IDs are not absolute,
but rather be varied depending on which environment they are accessed from.

This problem does not arise under uITRON 3.0 specification, however, due to
the restriction (3) mentioned previously.  Each object must have the same ID
regardless of the access environment from which it is accessed.  No parameter
indicating access environment is therefore required when an ID is returned as
a return parameter.

System calls which return an ID as a return parameter include get_tid and
ref_tsk.  These system calls are interpreted as omitting a parameter to
specify access environment.  Specifically, the return parameter of get_tid
returns the task ID accessed from the access environment of the task which
issued the get_tid system call.  In short, the task ID as seen from that
task's own access environment is returned.  The parameter wid returned
with ref_tsk also returns the object ID as seen from the access environment
which the target task of ref_tsk belongs to.

Depending on the implementation, the task ID of the waiting task is returned
as a return parameter for system calls of the form ref_??? (??? != "tsk").
In this case, the task ID is returned as seen from the access environment
which the target object of ref_??? belongs to.

Because of the restriction (3) introduced into uITRON 3.0 specification, the
ID number of an object must be the same if the object can be accessed from
other environments (nodes).  ID numbers obtained by get_tid and ref_tsk can
therefore be used as parameters to system calls issued from other
environments (other nodes).  This means that if an application program using
get_tid and running on a single node were distributed to run on several nodes,
compatibility could still be maintained as long as restriction (3) were
in effect.

Note however that this use of get_tid and ref_tsk will not be possible under
IMTRON specification as restriction (3) is expected to be removed.  Under
IMTRON specification, new system calls providing parameters which specify
access environment will be introduced.  Compatibility of programs using
get_tid will be lost when restriction (3) is removed for the extension to
IMTRON specification in the future.  We therefore recommend that the use of
get_tid should be avoided in cases where a program may be migrated to IMTRON
specification OS later.

Under IMTRON specification OS and HFDS, the pair of node location number and
object number can be used as an absolute object name.  However, it is
difficult to give a unique node number to each intelligent object in practice.
One possible approach is to assign node ID numbers by software to intelligent
objects which do not have native (hardware) unique ID numbers.  Under this
approach, names (ID numbers) should be considered relative, and may be varied
depending on the environment from which they are accessed.

****************************************************************************
*****                                                                  *****
*****  Chapter 3 System Calls of uITRON 3.0 Specification              *****
*****                                                                  *****
****************************************************************************

This chapter gives detailed descriptions of system calls supported under
uITRON 3.0 specification.  System calls for all levels of support, Required
[R], Standard [S] and Extended [E] are included.


****************************************************************************
***    3.1 Task Management Functions                                     ***
****************************************************************************

"Task management functions" are used to directly control and access the state
of tasks.

Included among these are functions for creating, deleting, starting and
terminating tasks, for releasing the WAIT state of tasks, for enabling/
disabling task dispatching, for changing task priority levels, for rotating
tasks on the ready queue, and for accessing task state.


========================================================================
|| [EN] || cre_tsk || Create Task
========================================================================
  cre_tsk:        Create Task

[Parameters]
  ID      tskid   Task ID
  T_CTSK *pk_ctsk Packet to Create Task
 -(pk_ctsk members)-
  VP      exinf   ExtendedInformation
  ATR     tskatr  TaskAttribute
  FP      task    TaskStartAddress
  PRI     itskpri InitialTaskPriority
  INT     stksz   StackSize (in bytes)
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = cre_tsk ( ID tskid, T_CTSK *pk_ctsk ) ;

[Description]

This system call creates the task specified by tskid.  Specifically, a TCB
(Task Control Block) is allocated for the task to be created, and initialized
according to accompanying parameter values of itskpri, task, stksz, etc.  A
stack area is also allocated for the task based on the parameter stksz.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

User tasks have positive ID numbers, while system tasks have negative
ID numbers.  User tasks cannot access system objects (objects
having negative ID numbers).  An E_OACV error will result if a user task
issues a system call on a system object, but error detection is
implementation dependent.

Tasks having ID numbers from -4 through 0 cannot be created.  An E_ID error
will result if a value in this range is specified for tskid.

The new task created by this system call will be put in DORMANT state.

Itskpri specifies the initial priority level of the task when it starts.
Under uITRON 3.0 specification, at least any value of 1 through 8 can be
specified as task priority.  The smaller the value, the higher the priority.
Priority levels -4 through 0 are reserved, and they may not be used.
Priority levels outside this range (including negative values) may also
be specified depending on the implementation; this is considered an
extended function [level X] for which compatibility and connectivity are
not guaranteed.  In general, negative priority levels are reserved for
use by the system.

Exinf may be used freely by the user for including extended information about
the task to be created.  Information set here may be accessed by ref_tsk.
If a larger region is desired for including user information, or if the user
wishes to change the contents of this information, the usr should allocate
memory area and set the address of this memory packet to exinf.  The OS
does not take care of the contents of exinf.

The lower bits of tskatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attributes part of
tskatr may be specified as follows.

        tskatr := (TA_ASM || TA_HLNG)
                | [TA_COP0] | [TA_COP1] | [TA_COP2] | [TA_COP3]
                | [TA_COP4] | [TA_COP5] | [TA_COP6] | [TA_COP7]

        TA_ASM  The task to be created is written in assembler
        TA_HLNG The task to be created is written in a high-level language
        TA_COPn The task to be created uses the n'th coprocessor
                (including floating point coprocessors)
                If only one coprocessor is available, use TA_COP0(=TA_COP).

The implementation-dependent attribute part can be used to indicate that the
task is to be debugged or to specify a debug mode (DB) value for TRON-
specification chips.  The rest of the system attribute part is reserved for
future specifications regarding multiprocessor attributes, etc.

The format of tskatr is shown in Figure 10.



   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          | (CO-PROCESSOR) - - - - - - - H|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - H|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - H|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           tskatr is 16 bits or less.
        2. If the bit length of tskatr is 16 bits and a coprocessor
           specification is needed, the implementation-dependent attributes
           part is used.
        3. H=1 indicates the task in question is written in a high-level
           language (TA_HLNG).

                           Figure 10 tskatr Format


[Supplemental Information]

An EN_PAR error will result if the number of bits used on the requesting node
is larger than that used on the target node, and if a range of values not
supported by the target node is specified for exinf, tskatr, task, itskpri or
stksz.

Although the standard packet format of pk_ctsk (the order and number of bits
associated with each member) is as stated above, it may be changed as
necessary for implementation on various systems as long as restriction
on compatibility and connectivity with other systems is not a problem.
On a 16-bit data, 32-bit address system, for example, it may be more
convenient in terms of packet alignment to exchange the order of task
and tskatr.

When TA_HLNG is specified, a high-level language environment setting
program (a high-level language support routine) is called before branching
to the task address.  The least significant bit (LSB) of the system
attribute bits is used for this specification.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block and/or user stack
            cannot be allocated)
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_RSATR   Reserved attribute (tskatr was invalid or could not be used)
  E_OBJ     Invalid object state (a task of the same ID already exists)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (pk_ctsk, task, itskpri and/or stksz is invalid)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for exinf, tskatr, task,
            itskpri and/or stksz)

[Differences from uITRON 2.0 and ITRON2 Specifications]

cre_??? parameters have been made into packets for the following reasons.

  - Parameter contents strongly depend on implementation and CPU, making
    standardization of the system call interface difficult.
        Coprocessor's availability, multiple stack specifications (stacks
        for each ring, etc.), space IDs on introducing MMUs are all CPU
        dependent.
        The number of parameters should be reduced in uITRON specification.

  - It is possible to improve extensibility by putting parameters into packets.
        This makes it easy to add hook routines and others.

Extended information (exinf) has been added.

  - This allows the user to include additional information about task
    attributes.
        If a larger region is desired for including user information,
        the user should allocate memory area and set the address of the
        memory packet to exinf.

The data type TPRI has been changed to PRI.

The parameter name stadr has been changed to task.

The bit locations of TA_HLNG and TA_COPn have been changed.
        This was done in order so the same format could be used for both 8-bit
        and 16-bit versions of tskatr.


========================================================================
|| [EN] || del_tsk || Delete Task
========================================================================
  del_tsk:        Delete Task

[Parameters]
  ID      tskid   TaskID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = del_tsk ( ID tskid ) ;

[Description]

This system call deletes the task specified by tskid.  Specifically, it
changes the state of the task specified by tskid from DORMANT into
NON-EXISTENT (a virtual state not existing on the system), and then clears
the TCB and releases stack. An E_OBJ error results if this system call is
used on a task which is not DORMANT.

After deletion, another task having the same ID number can be created.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

A task cannot delete itself by this system call.  An E_OBJ error will
result if a task specifies itself, since such a task cannot be DORMANT.
Use the exd_tsk system call rather than this one when a task needs to delete
itself.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_OBJ     Invalid object state (the target task is not in DORMANT state)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion


========================================================================
|| [SN] || sta_tsk || Start Task
========================================================================
  sta_tsk:        Start Task

[Parameters]
  ID      tskid   TaskID
  INT     stacd   TaskStartCode

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = sta_tsk ( ID tskid, INT stacd ) ;

[Description]

This system call starts the task specified by tskid.  Specifically, it changes
the state of the task specified by tskid from DORMANT into RUN/READY.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Stacd can be used to specify parameters to be passed to the task when it is
started.  This parameter can be read by the task being started, and may be
used for transmitting simple messages.

The task priority on starting the task is given by the initial task priority
parameter (itskpri) specified when the task was created.

Start request is not queued in this this system call.  In other words, if
this system call is issued when the target task is not in DORMANT state,
the system call will be ignored, and an E_OBJ error returned to the issuing
task.

If cre_tsk [level EN] is not implemented on a system, tasks are
created statically when the system is started.  Parameters required for
creating a task, such as task starting address (task) and initial task
priority (itskpri) are also specified statically at system startup.

[Supplemental Information]

An EN_PAR error will result if the number of bits used on the requesting node
is larger than that used on the target node, and if a range of values not
supported by the target node is specified for stacd.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_OBJ     Invalid object state (the target task is not in DORMANT state)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for stacd)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The stacd parameter was added according to the ITRON2 specification.


========================================================================
|| [S] || ext_tsk || Exit Issuing Task
========================================================================
  ext_tsk:        Exit Task

[Parameters]
  None

[Return Parameters]
  Not returned to the context issuing the system call.

[C Language Interface]
  void ext_tsk ( ) ;

[Description]

This system call causes the issuing task to exit, changing the state of the
task into the DORMANT state.

[Supplemental Information]

When a task exits due to ext_tsk, that task does not automatically release all
the resources (memory blocks, semaphores, etc.) which it had obtained prior to
the system call.  It is the user's responsibility that all resources are
released beforehand.

Ext_tsk is a system call which does not return to the issuing context.
Accordingly, even if an error code is returned on detection
of some error, it is normal for tasks making this system call not to perform
any error checking, and it is in fact possible that a program could run out of
control.  For this reason, even if an error is detected upon issuing this
system call, the error is not returned to the task which issued the system
call.  If information on detected errors is required it should be left in
a messagebuffer used as an error log.

In principle, information concerning a task recorded in the TCB, such as task
priority, is reset whenever a task is placed in DORMANT state.  For example,
its task priority after being restarted would be reset to the initial task
priority (itskpri) specified by cre_tsk when it was first created, even if
a task's priority was changed using chg_pri, then that task exits using
ext_tsk, but later started by sta_tsk.  Task priority does not return to
what it was when ext_tsk was executed.

Under uITRON 3.0 specification, all system calls which do not return to their
issuing contexts are named ret_???, ext_??? or exd_???.

[Error Codes]
  * System call may detect the following error.  The error is not returned to
    the context issuing the system call.  Error codes therefore cannot be
    returned directly as a return parameter of the system call.  The behavior
    on error detection is implementation dependent.

  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)


========================================================================
|| [E] || exd_tsk || Exit and Delete Task
========================================================================
  exd_tsk:        Exit and Delete Task

[Parameters]
  None

[Return Parameters]
  Not returned to the context issuing the system call.

[C Language Interface]
  void exd_tsk ( ) ;

[Description]

This system call causes the issuing task to exit and then delete itself.  In
other words the state of the issuing task changes into the NON-EXISTENT
(a virtual state not existing on the system).

[Supplemental Information]

When a task exits with exd_tsk, that task does not automatically release all
the resources (memory blocks, semaphores, etc.) which it had secured prior to
the call.  It is the user's responsibility to see to it that all resources are
released beforehand.

Exd_tsk is a system call which does not return any parameters to the original
issuing context.  Accordingly, even if an error code is returned on detection
of some error, it is normal for tasks making this system call not to perform
any error checking, and it is in fact possible that a program could run out of
control.  For this reason, even if an error is detected upon making this
system call, it is supposed that the error is not returned to the task which
issued the system call.  If information on detected errors is required it
should be left in a messagebuffer used as an error log.

[Error Codes]
  * System call may detect the following error.  The error is not returned to
    the context issuing the system call even.  Error codes therefore cannot be
    returned directly as a return parameter of the system call.  The behavior
    on error detection is implementation dependent.

  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)


========================================================================
|| [SN] || ter_tsk || Terminate Other Task
========================================================================
  ter_tsk:        Terminate Task

[Parameters]
  ID      tskid   TaskID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = ter_tsk ( ID tskid ) ;

[Description]

This system call forcibly terminates the task specified by tskid.  That is, it
changes the state of the task specified by tskid into DORMANT.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Even if the target task is in wait state (including SUSPEND state), its wait
state will be released and then it will be terminated.  If the target task is
on a queue of some sort (such as waiting for a semaphore), it will be removed
from that queue by ter_tsk.

A task cannot specify the issuing task in this system call.  An E_OBJ error
will result if a task specifies itself.

There is an intermediate state waiting for the response (TR packet or TA
packet) from the target node after executing the system call to access the
other node and making a request (sending a TP packet) to the node. This state
is called the "connection function response wait (TTW_NOD)" state.
The ter_tsk system call may specify tasks which are in the connection
function response wait state.  Tasks which are waiting for objects (such as
a semaphore) on another node may also be specified to this system call.
In such cases, ter_tsk will halt any system calls accessing other nodes
which have been issued by the task to be terminated.

Table 3 lists the result of executing ter_tsk on tasks in various states.



       Table 3 Results of Executing ter_tsk on Tasks in Various States

 +-----------------------------+--------------+---------------------+
 |      Target Task State      | ter_tsk ercd |     Processing      |
 +-----------------------------+--------------+---------------------+
 | RUN and READY states        | E_OK         | Forcibly terminated |
 |(other than issuing task)    |              |                     |
 | RUN state                   | E_OBJ        | Does nothing        |
 |(issuing task)               |              |                     |
 | Connection function         | E_OK         | Forcibly terminated |
 | response wait state         |              |                     |
 | WAIT state                  | E_OK         | Forcibly terminated |
 |(on same node objects)       |              |                     |
 | WAIT state                  | E_OK         | Forcibly terminated |
 |(on other node objects)      |              |                     |
 | DORMANT state               | E_OBJ        | Does nothing        |
 |                             |              |                     |
 | NON-EXISTENT state          | E_NOEXS      | Does nothing        |
 |                             |              |                     |
 +-----------------------------+--------------+---------------------+


[Supplemental Information]

When a task is terminated by ter_tsk, that task does not automatically release
all the resources (memory blocks, semaphores, etc.) which it had obtained
prior to the call.  It is the user's responsibility to see to it that all
resources are released beforehand.

In principle, information concerning a task recorded in the TCB, such as task
priority, is reset whenever a task is placed in DORMANT state.  For example,
its task priority after being restarted would be reset to the initial task
priority (itskpri) specified by cre_tsk when it was first created, even if
a task's priority was changed using chg_pri, then that task is terminated
by ter_tsk, but later started by sta_tsk.  Task priority does not return to
what it was when ter_tsk was executed.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_OBJ     Invalid object state (the target task is already in DORMANT state
            or a task invalidly specified itself)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion

[Differences from uITRON 2.0 and ITRON2 Specifications]

The exccd parameter has been eliminated according to the uITRON 2.0
specification.


========================================================================
|| [R] || dis_dsp || Disable Dispatch
========================================================================
  dis_dsp:        Disable Dispatch

[Parameters]
  None

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = dis_dsp ( ) ;

[Description]

This system call disables task dispatching.  Dispatching will remain disabled
after this call is issued until a subsequent call to ena_dsp is issued.
The status of the issuing task will not be allowed to be changed to READY from
the RUN.  It cannot be changed into WAIT, either.  However, since external
interrupt is not disabled, interrupt handlers are allowed to run even when
dispatching has been disabled.  While an executing task may be preempted by an
interrupt handler with dispatching disabled, there is no possibility that it
will be preempted by another task.

The following operations occur during the time dispatching is disabled.

  - Even in a situation where normally a task issuing dis_dsp should be
    preempted by a system call issued by an interrupt handler or by the task
    issuing dis_dsp, the task that should normally be executed is not
    dispatched.  Instead, dispatching of this task is delayed until dispatch
    disabled state is cleared by ena_dsp.

  - If an interrupt handler invoked during dispatch disabled state issues
    sus_tsk for a running task (one that executed dis_dsp) to put it in SUSPEND
    state, or ter_tsk to put it in DORMANT state, the task transition is
    delayed until dispatch disabled state is cleared.

  - An E_CTX error will result if the task which has executed dis_dsp issues
    any system calls (such as slp_tsk or wai_sem) capable of putting an
    issuing task into WAIT state.

  - An EN_CTXID error will result if a task which has executed dis_dsp
    attempts to operate on objects on another node (that is, if the ID
    parameter of the system call issued refers to an object on another node).

  - TSS_DDSP will be returned as sysstat if system status is referenced using
    ref_sys.

No error will result if a task already in dispatch disable state issues
dis_dsp.  It only keeps dispatch disabled state.  No matter how many times
dis_dsp has been issued, a single ena_dsp enables dispatching again.  It is
therefore for the user to determine what to do with nested pairs of dis_dsp
and ena_dsp.

An E_CTX error will result if dis_dsp is issued when both interrupt and
dispatching are disabled with loc_cpu.  (For details, see the description of
loc_cpu.)

[Supplemental Information]

A running task cannot enter DORMANT or NON-EXISTENT state while
dispatching is disabled.  An E_CTX error will result if an running task issues
either ext_tsk or exd_tsk while interrupt and dispatching are disabled.  Note
however that since both ext_tsk and exd_tsk are system calls which do not
return to their original contexts, error notification using return parameters
of these system calls is not possible.  If information on detected errors is
required it should be left in a messagebuffer used as an error log.

Only if the system is not a multiprocessor configuration, system can take
advantage of the dispatch disabled state for exclusive inter-task control.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_CTX     Context error (issued from task-independent portions or
            issued after execution of loc_cpu)

[Differences from uITRON 2.0 and ITRON2 Specifications]

This is a new system call.

[Rationale]

It is possible to achieve the state closest to the disabled dispatch by setting
the task priority to the highest.  However, this system call for disabling
dispatching was added so that implementations could achieve the same results
at higher speed and with less CPU burden than when using chg_pri.


========================================================================
|| [R] || ena_dsp || Enable Dispatch
========================================================================
  ena_dsp:        Enable Dispatch

[Parameters]
  None

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = ena_dsp ( ) ;

[Description]

This system call enables task dispatching, that is, it finishes dispatch
disabled state caused by the execution of dis_dsp.

No error will result if a task which is not in dispatch disabled state issues
ena_dsp.  In this case, dispatching will just remain enabled.

An E_CTX error will result if ena_dsp is issued when both interrupt and
dispatching are disabled with loc_cpu.  (For details, see the description of
loc_cpu.)

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_CTX     Context error (issued from task-independent portions or
            issued after execution of loc_cpu)

[Differences from uITRON 2.0 and ITRON2 Specifications]

This is a new system call.


========================================================================
|| [SN] || chg_pri || Change Task Priority
========================================================================
  chg_pri:        Change Task Priority

[Parameters]
  ID      tskid   TaskID
  PRI     tskpri  TaskPriority

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = chg_pri ( ID tskid, PRI tskpri ) ;

[Description]

This system call changes the current priority of the task specified by tskid
to the value specified by tskpri.

Under uITRON 3.0 specification, at least any value of 1 through 8 can be
specified as task priority.  The smaller the value, the higher the priority.
Priority levels -4 through 0 are reserved, and they may not be used.
Priority levels outside this range (including negative values) may also
be specified depending on the implementation; this is considered an
extended function [level X] for which compatibility and connectivity are
not guaranteed.  In general, negative priority levels are reserved for
use by the system.

A task may specify itself by specifying tskid = TSK_SELF = 0.  Note, however,
that an E_ID error will result if tskid = TSK_SELF = 0 is specified to a system
call issued from a task-independent portion.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

The priority set by this system call remains in effect until the task exits.
Once a task enters DORMANT state, its priority prior to exiting is lost.
When a task which enters DORMANT state restarts, the initial task priority
(itskpri) specified at task creation or at system startup will be used.

If the target task is linked to ready queue or any other queue, this system
call may result in the re-ordering of the queues.  If chg_pri is executed on a
task waiting on the ready queue (including tasks in RUN state) or other
priority-based queue, the target task will be moved to the end of the part of
the queue for the associated priority.  If the priority specified is the same
as the current priority, the task will still be moved behind other tasks of
the same priority.  It is therefore possible for a task to relinquish its
execution privileges using chg_pri on itself by specifying its current
priority.

[Supplemental Information]

An EN_PAR error will result if the number of bits used on the requesting node
is larger than that used on the target node and a value not supported by the
target node is specified for tskpri.

Depending on the implementation, specifying tskpri = TPRI_INI = 0 may cause a
task's priority to be reset to the initial task priority (itskpri) which was
defined when it was first created or when the system started.  This feature is
used in some implementations in order to reset the task priority to its
original value after setting it to a higher value for indivisible processing.
This feature is an extended function [level X] for which compatibility and
connectivity are not guaranteed.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (the value of tskpri is invalid or may not be used)
  E_OBJ     Invalid object state (the target task is in DORMANT state)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for tskpri)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The location where target tasks for chg_pri are placed on a queue has been
clarified.


========================================================================
|| [S] || rot_rdq || Rotate Tasks on the Ready Queue
========================================================================
  rot_rdq:        Rotate Ready Queue

[Parameters]
  PRI     tskpri  TaskPriority

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = rot_rdq ( PRI tskpri ) ;

[Description]

This system call rotates tasks on the ready queue associated with the priority
level specified by tskpri.  Specifically, the task at the head of the ready
queue of the priority level in question is moved to the end of the ready queue,
thus switching the execution of tasks having the same priority.  Round robin
scheduling may be implemented by periodically issuing this system call in a
given period of time.

When rot_rdq is issued by task portions with tskpri = TPRI_RUN = 0, the ready
queue with the priority level of the issuing task is rotated.

When TPRI_RUN or a task's own priority level are specified for tskpri to
rot_rdq, the task issuing the system call will be placed on the end of its
ready queue.  In other words, task can issue rot_rdq to relinquishing its
execution privileges.  The concept of "ready queue" envisioned in the
description of this system call is one which includes the task in RUN state.

This system call does nothing if there are no tasks on the ready queue of the
specified priority.  No error will result.

This system call cannot rotate ready queues on other nodes.

[Supplemental Information]

Figures 11(a) and 11(b) show examples of what happens when rot_rdq is executed.
Figure 11(a) shows the initial state of the ready queue.  Figure 11(b) shows
the resulting state of the same queue after the rot_rdq is called with tskpri
equal to 2.  At this point, the next task to execute is Task C.



          |          |
 Priority +----------+
   High   | 1        |
    ^     +----------+
    |     | 2    -------------> [Task B] ----> [Task C] ----> [Task D]
    |     +----------+
    v     | 3    -------------> [Task E]
   Low    +----------+
          |          |

               Figure 11(a) Ready Queue Before Executing rot_rdq


          |          |
 Priority +----------+
   High   | 1        |
    ^     +----------+
    |     | 2    -------------> [Task C] ----> [Task D] ----> [Task B]
    |     +----------+
    v     | 3    -------------> [Task E]
   Low    +----------+
          |          |

 Note: The next task to execute is Task C.

          Figure 11(b) Ready Queue After Executing rot_rdq(tskpri=2)


Depending on the implementation, it may be possible to issue rot_rdq(tskpri =
TPRI_RUN) from task-independent portions, such as a cyclic handler.  In this
case the ready queue including the running task, or the ready queue including
the highest priority task, is rotated.  Normally these two are the same, but
not always, as when task dispatching is delayed.  In that case it is
implementation dependent whether to rotate the ready queue including the
running task or the ready queue including the highest priority task.  Note that
this is an extended function [Level X] for which compatibility and connectivity
are not guaranteed.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (the value of tskpri is invalid)


========================================================================
|| [SN] || rel_wai || Release Wait of Other Task
========================================================================
  rel_wai:        Release Wait

[Parameters]
  ID      tskid   TaskID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = rel_wai ( ID tskid ) ;

[Description]

This system call forcibly releases WAIT state (not including SUSPEND state)
of the task specified by tskid.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

An E_RLWAI or EN_RLWAI error is returned to the task whose WAIT state has been
released using rel_wai.  EN_RLWAI is returned when the target task uses the
connection function to operate on a remote object.

Wait release requests by rel_wai are not queued.  In other words, if
the task specified by tskid is already in WAIT state, the WAIT state is
released, otherwise an E_OBJ error will be returned to the issuer.  An
E_OBJ error will also result when a task specifies itself to this system call.

Rel_wai does not release SUSPEND state.  If rel_wai is issued on a task in
WAIT-SUSPEND state, WAIT will be released but SUSPEND will continue for that
task. When SUSPEND should also be released, the frsm_tsk system call must be
issued separately.

Rel_wai can also be used to release WAIT state associated with connection
function response wait.  If the task specified to rel_wai has issued a system
call for accessing another node, that system call will be aborted and EN_RLWAI
returned to the task specified to rel_wai.  The rel_wai system call itself
will complete normally.  However, it is not possible to determine whether it
completed with wait release conditions fulfilled (resources obtained) or
unfulfilled as seen from the target task.  Rel_wai can even abort a system
call such as sig_sem issued to another node.  The aborted system call
returns an EN_RLWAI error to its issuer (the task specified by rel_wai).
It cannot be known whether or not the semaphore count is incremented by
sig_sem when this error is returned.  Since the integrity of the number of
resources of the other node may be lost in this case, this problem must be
covered as necessary at the application level.

Rel_wai may also be used to release the wait for objects on other nodes (such
as semaphore wait).  However, just as with releasing connection function
response wait, it is not possible to determine whether the call completed
with wait release conditions fulfilled (resources obtained) or unfulfilled.
Since the integrity of the number of resources of the other node may be
again lost in this case, this problem must be covered as necessary at the
application level.  When it cannot be known whether or not resources have
been obtained, an EN_RLWAI error is returned to the task specified to rel_wai.
The rel_wai system call itself will complete normally.

Table 4 lists the results of executing rel_wai on tasks in various states.



       Table 4 Results of Executing rel_wai on Tasks in Various States

 +-----------------------------+--------------+---------------------+
 |      Target Task State      | rel_wai ercd |     Processing      |
 +-----------------------------+--------------+---------------------+
 | RUN and READY states        | E_OBJ        | Does nothing        |
 |(other non-issuing task)     |              |                     |
 | RUN state                   | E_OBJ        | Does nothing        |
 |(issuing task)               |              |                     |
 | Connection function         | E_OK         | Wait released*1     |
 | response wait state         |              |                     |
 | WAIT state                  | E_OK         | Wait released*2     |
 |(same node objects)          |              |                     |
 | WAIT state                  | E_OK         | Wait released*1     |
 |(other node objects)         |              |                     |
 | DORMANT state               | E_OBJ        | Does nothing        |
 |                             |              |                     |
 | NON-EXISTENT state          | E_NOEXS      | Does nothing        |
 |                             |              |                     |
 +-----------------------------+--------------+---------------------+

 *1 An EN_RLWAI error is returned to the target task.  It is not known
    whether or not resources were obtained (or returned) when wait was
    released for the target task.  The integrity of the number of
    resources may be lost.
 *2 An E_RLWAI error is returned to the target task.  It guaranteed that
    resources were not obtained when wait was released for the target
    task (Wait release conditions were still not satisfied).


[Supplemental Information]

A function similar to timeout can be implemented using an alarm handler which
issues this system call on tasks specified time after they have entered WAIT
state.

Rel_wai and wup_tsk differ in the following points.

  - Wup_tsk can only release the WAIT state by slp_tsk or tslp_tsk,
    while rel_wai can release WAIT states caused by these and other calls
    (including wai_flg, wai_sem, rcv_msg, get_blk, etc.).

  - As seen from the target task, releasing WAIT state with wup_tsk results
    in a normal completion (E_OK), whereas releasing WAIT state with rel_wai
    results in an error (E_RLWAI).

  - When wup_tsk is used, a request is queued even if neither slp_tsk nor
    tslp_tsk have been executed on the target task yet.  When rel_wai is used
    to the task which is not in WAIT state, an E_OBJ error will result.

If rel_wai causes connection function processing to be aborted or if it causes
the release of a wait for an object on another node, it only performs the
processing necessary on the local node (the node on which the task specified
to rel_wai exists).  In principle, it does not wait for some acknowledge from
the other node.   Even if illegal status is detected in the other node,
rel_wai will release connection function response wait.  Even if the specified
task is waiting for an object on another node, rel_wai processing itself
will not enter connection function response wait if the task specified by
rel_wai is on the same node as the issuing task.

Depending on the implementation, when rel_wai is used to release the wait for
an object on another node, it may guarantee that resources were not obtained
(to ensure resource integrity) and return E_RLWAI to the waiting task.
In this case, objects on other nodes are handled exactly the same way as
objects on the local node.  However, this feature is considered as an
extended function [level X] for which compatibility and connectivity are
not guaranteed.  Rel_wai must communicate with remote nodes in order to
implement this feature.  In this case, rel_wai processing may possibly enter
connection function response wait.  Whether or not this feature can be
implemented depends on the network configuration and protocol
being used.  Therefore, it is not included in the standard uITRON 3.0
specification.  In general, this feature is suitable for tightly-coupled
networks.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_OBJ     Invalid object state (the target task is not in WAIT state
            (including when it is in DORMANT state or when the issuing task
             specifies itself))
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion

[Rationale]

When rel_wai releases connection function response wait, it returns EN_RLWAI
to the specified task.  The reason why the specification does not require the
integrity of the number of resources to be guaranteed is given below.

The typical case when rel_wai needs to be issued to a task in connection
function response wait is when communications with the remote node are not
operating normally, and related processing must be aborted and restored for
the local node only.  Since rel_wai is intended for use when such problems
occur, it is not so important or it is meaningless to maintain the integrity
of the number of resources on the remote node.   A similar situation occurs
in case of an EN_COMM error, which is returned when the target node or
communication are not operating normally.

Since uITRON 3.0 specification is intended for loosely-coupled networks,
keeping communication protocol simple and providing an environment in which
each node can function separately is considered more important than ensuring
the integrity of resources over the entire network.  For example, since it is
possible that some nodes are operating and some nodes are under debugging,
it is important to keep protocol looser and ensure the independence of
separate nodes.  The above specification was determined based on these
considerations.

It is not necessary to ensure the integrity of the number of resources on a
remote node when rel_wai has been used to release WAIT state of a task
waiting for an object on that node, since rel_wai is intended primarily for
debugging and support in times of trouble.


========================================================================
|| [S] || get_tid || Get Task Identifier
========================================================================
  get_tid:        Get Task Identifier

[Parameters]
  None

[Return Parameters]
  ER      ercd    ErrorCode
  ID      tskid   TaskIdentifier

[C Language Interface]
  ER ercd = get_tid ( ID *p_tskid ) ;

[Description]

This system call gets the ID of the issuing task.

If this system call is issued from a task-independent portion, tskid will
be FALSE=0.

[Supplemental Information]

The following restriction exists under uITRON 3.0 specification: each object
(if it can be accessed) must have the same ID number regardless of the
environment (or node) in which the object is accessed.  The ID obtained by
get_tid may therefore be used as a parameter to system calls issued on other
environments (nodes).  And compatibility can therefore be maintained even for
application programs which used to run on a single node but have been
rewritten to be distributed across more than one node.

Note that if the above restriction is removed to extend to the IMTRON
specification, object IDs are no longer absolute, but relative depending on
which node they are accessed from.  For example, Object X may have ID=5 when
accessed from Node A, but ID=8 when accessed from Node B.  Under such a
specification, the ID obtained by get_tid cannot be used as a parameter to
system calls issued on other environments (nodes), and compatibility with
older programs using get_tid cannot be maintained.

We therefore recommend that use of get_tid be avoided in cases where a program
may be ported to IMTRON specification OS later.  More specifically, we
recommend that you do not pass the task ID obtained by get_tid to a task in
another access environment (that is, a task on another node under uITRON 3.0
specification).  Under IMTRON specification, where the access environment can
change dynamically, the scope in which a task ID obtained by get_tid is
meaningful is limited, as different task IDs are assigned under different
access environments.  In order to make it easy to migrate to this type of
programming style, we recommend that you avoid passing task IDs obtained
using get_tid to tasks on other nodes as much as possible even under
uITRON 3.0 specification OS.

When the above restriction is eliminated, system calls returning object IDs
in their return parameters require additional information representing
access environment.  In the case of get_tid, the task ID as seen from the
default access environment to which the issuing task belongs is returned.

[Error Codes (ercd)]
  E_OK      Normal Completion


========================================================================
|| [EN] || ref_tsk || Reference Task Status
========================================================================
  ref_tsk:        Reference Task Status

[Parameters]
  ID      tskid   TaskID
  T_RTSK  *pk_rtsk        Packet to Reference Task

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rtsk members)-
  VP      exinf   ExtendedInformation
  PRI     tskpri  TaskPriority
  UINT    tskstat TaskState
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_tsk ( T_RTSK *pk_rtsk, ID tskid ) ;

[Description]

This system call refers to the state of the task specified by tskid, and
returns its current priority (tskpri), its task state (tskstat), and its
extended information (exinf).

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Even if the tskid specifies a task on another node, task status information
(packet contents) which are read are automatically transferred to the
requesting node from the target node.

Tskstat may take the following values.

    tskstat:
        TTS_RUN H'0...01        RUN state (currently running)
        TTS_RDY H'0...02        READY state (ready to run)
        TTS_WAI H'0...04        WAIT state (waiting for something)
        TTS_SUS H'0...08        SUSPEND state (forcibly made to wait)
        TTS_WAS H'0...0c        WAIT-SUSPEND state
        TTS_DMT H'0...10        DORMANT state

Since these task states are expressed by bit correspondences they are
convenient when looking for OR conditions (such as whether a task is in RUN or
READY state).  TTS_WAS is a combination of both TTS_SUS and TTS_WAI,
TTS_SUS does not combine with any of the other states (TTS_RUN, TTS_RDY or
TTS_DMT).

A task may specify itself by specifying tskid = TSK_SELF = 0.  Note, however,
that an E_ID error will result if tskid = TSK_SELF = 0 is specified when this
system call is issued from a task-independent portion.

An E_NOEXS error will result if the task specified to ref_tsk does not exist.

Tskstat will be TTS_RUN if ref_tsk is executed specifying a task which has
been interrupted by an interrupt handler.

[Supplemental Information]

An EN_RPAR error will result if the number of bits used on the target node is
larger than that used on the requesting node, and if a value not supported by
the requesting node is returned for exinf, tskpri or tskstat.

The values of TTS_RUN, TTS_RDY, TTS_WAI, etc. as return values for tskstat are
not necessarily the same value to be entered in the TCB.  The way in which
task state is represented in the TCB is implementation dependent.  When
ref_tsk is executed, the internal representation of task state may simply be
converted to the standard values TTS_RUN, TTS_RDY, TTS_WAI, etc.

Depending on the implementation, the following additional information can also
be referenced in addition to exinf, tskpri and tskstat.

        tskwait Reason for wait
        wid     Wait object ID
        wupcnt  Number of queued wakeup requests
        suscnt  Number of nested SUSPEND requests
        tskatr  Task attributes
        task    Task starting address
        itskpri Initial task priority
        stksz   Stack size

If tskstat is TTS_WAI (or TTS_WAS), tskwait and wid can take the values given
in Table 5.



                        Table 5 tskwait and wid Values

 +-----------+------------+------------------------+-------------------+
 |  tskwait  |   Value    |      Description       |        wid        |
 +-----------+------------+------------------------+-------------------+
 |  TTW_SLP  | H'0...0001 | Waiting with slp_tsk   |         0         |
 |           |            | or tslp_tsk            |                   |
 |  TTW_DLY  | H'0...0002 | Waiting with dly_tsk   |         0         |
 |           |            |                        |                   |
 |  TTW_NOD  | H'0...0008 | Waiting for connection |         0         |
 |           |            | function response      |                   |
 |  TTW_FLG  | H'0...0010 | Waiting with wai_flg   | flgid of object   |
 |           |            |                        | being waited for* |
 |  TTW_SEM  | H'0...0020 | Waiting with wai_sem   | semid of object   |
 |           |            |                        | being waited for* |
 |  TTW_MBX  | H'0...0040 | Waiting with rcv_msg   | mbxid of object   |
 |           |            |                        | being waited for  |
 |  TTW_SMBF | H'0...0080 | Waiting with snd_mbf   | mbfid of object   |
 |           |            |                        | being waited for* |
 |  TTW_MBF  | H'0...0100 | Waiting with rcv_mbf   | mbfid of object   |
 |           |            |                        | being waited for* |
 |  TTW_CAL  | H'0...0200 | Waiting on rendezvous  | porid of object   |
 |           |            | call                   | being waited for* |
 |  TTW_ACP  | H'0...0400 | Waiting on rendezvous  | porid of object   |
 |           |            | accept                 | being waited for  |
 |  TTW_RDV  | H'0...0800 | Waiting for rendezvous |         0         |
 |           |            | completion             |                   |
 | (TTW_CAL| | H'0...0a00 | Waiting on rendezvous  |         0         |
 |  TTW_RDV) |            | call or waiting for    |                   |
 |           |            | rendezvous completion  |                   |
 |  TTW_MPL  | H'0...1000 | Waiting with get_blk   | mplid of object   |
 |           |            |                        | being waited for  |
 |  TTW_MPF  | H'0...2000 | Waiting with get_blf   | mpfid of object   |
 |           |            |                        | being waited for  |
 +-----------+------------+------------------------+-------------------+

 * The object being waited for may be on another node other than the task
   being referenced by ref_tsk.


The value assigned to wid is the ID seen from the node (access environment)
on which the task being referenced by ref_tsk exists.  If the task issuing
ref_tsk exists on a different node (access environment) than the task being
referenced, it may not be possible for the issuing task to use the object ID
returned in wid as a parameter to another system call to access the same
object.

Connection function response wait (TTW_NOD) indicates the intermediate state
waiting for the response (TR packet or TA packet) from the target node
after executing the system call to access the other node, and making a
request (sending TP packet) to the node.  When a task is actually waiting
for an object on remote node and wait release conditions are not yet
satisfied (for example there are not enough resource counts in a semaphore),
the normal WAIT state associated with that object (such as TTW_SEM to
represent waiting for a semaphore) is returned, instead of the state for
connection function response wait (TTW_NOD).  The state transition from
connection function response wait (TTW_NOD) to semaphore wait (TTW_SEM) is
notified to the requesting node by a TA packet sent from the target node.

If tskstat is not returned as TTS_WAI or TTS_WAS, both tskwait and wid will be
returned as 0.  Both wupcnt and suscnt will be returned as 0 when DORMANT
tasks are referenced.

Support for the return parameters tskwait, wid, wupcnt and suscnt is
considered extended functions [level X] for which compatibility and
connectivity are not guaranteed.

The issuing task's ID cannot be found using this system call even if tskid is
specified as TSK_SELF.  Get_tid should be used to get the own task ID.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (the packet address for return parameters cannot
            be used)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_RPAR   A value outside the range supported by the requesting node and/or
            transmission packet format was returned as a return parameter (a
            value outside supported range was returned for exinf, tskpri and/
            or tskstat)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from tsk_sts to ref_tsk.

Tskatr has been removed from the return parameters since it represents static
information about a task.

[Rationale]

System calls such as ref_tsk which reference an object's status are primarily
provided for debugging as they are not generally required in typical textbook
form programs.  This is why these system calls are included in support level
[E] and [EN].

****************************************************************************
***    3.2 Task-Dependent Synchronization Functions                      ***
****************************************************************************

Task-dependent synchronization functions utilize those synchronization
functions already supported by tasks.

This includes functions that suspend tasks for a while and associated
functions that release SUSPEND state, and synchronization functions which
make tasks wait and wake them up.


========================================================================
|| [SN] || sus_tsk || Suspend Other Task
========================================================================
  sus_tsk:        Suspend Task

[Parameters]
  ID      tskid   TaskID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = sus_tsk ( ID tskid ) ;

[Description]

This system call suspends the execution of the task specified by tskid by
putting it into SUSPEND state.

SUSPEND state is released by issuing the rsm_tsk or frsm_tsk system call.

If the task specified to sus_tsk is already in WAIT state, it will be put in
the combined WAIT-SUSPEND state by the execution of sus_tsk.  If wait
conditions for the task are later fulfilled, it will enter SUSPEND state.
If rsm_tsk is issued on the task, it will return to the WAIT state before
the suspension.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Since SUSPEND state indicates the suspension of execution by a system call
issued from another task, a task may not specify itself to this system call.
An E_OBJ error will result if a task specifies itself.

If more than one sus_tsk call is issued to a task, that task will be put
in multiple SUSPEND states.  This is called suspend request nesting.  When
this is done, rsm_tsk must be issued the same number of times which sus_tsk
was issued (suscnt) in order to return the task to its original state before
the suspension.  This means it is possible to nest the pairs of sus_tsk and
rsm_tsk.

The maximum number of times suspend requests may be nested, and even whether
or not suspend request nesting (the ability to issue sus_tsk on the same task
more than once) is even allowed, is implementation dependent.  Suspend request
nesting is considered an extended function [level X] for which compatibility
and connectivity are not guaranteed.

An E_QOVR error will result if sus_tsk is issued more than once on the same
task on a system which does not support suspend request nesting or if it is
issued more than the maximum number of times allowed.

[Supplemental Information]

A task which is suspended in addition to waiting for resources (such as
waiting for a semaphore) can be allocated resources (such as semaphore counts)
based on the same conditions as tasks which are not suspended.  Even when
suspended, the allocation of resources is not delayed in any way.  Conditions
concerning resource allocation and release of the wait state remain unchanged.
In other words, SUSPEND state is completely independent of other processing
and task states.

If it is desirable to delay the allocation of resources to a task which is
suspended, the user should use chg_pri in conjunction with sus_tsk and rsm_tsk.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_OBJ     Invalid object state (the specified task is in DORMANT state or
            the issuing task specified itself)
  E_QOVR    Queuing or nesting overflow (the number of nesting levels given by
            suscnt went over the maximum allowed)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion

[Differences from uITRON 2.0 and ITRON2 Specifications]

The term "suspend nesting" is now used instead of "suspend queuing" to
clarify its meaning.


========================================================================
|| [SN] || rsm_tsk || Resume Suspended Task
========================================================================
|| [EN] || frsm_tsk || Forcibly Resume Suspended Task
========================================================================
   rsm_tsk:       Resume Task
  frsm_tsk:       Forcibly Resume Task

[Parameters]
  ID      tskid   TaskID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = rsm_tsk ( ID tskid ) ;
  ER ercd = frsm_tsk ( ID tskid ) ;

[Description]

Both these system calls release SUSPEND state of the task specified by
tskid.  Specifically, they cause SUSPEND state to be released and the
execution of the specified task to resume when the task has been suspended
by the prior execution of sus_tsk.

If the specified task is in WAIT-SUSPEND state, the execution of rsm_tsk only
releases the SUSPEND state, and the task will become WAIT state.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

A task cannot specify itself to this system call.  An E_OBJ error will result
if a task specifies itself.

Rsm_tsk only releases one suspend request from the suspend request nest
(suscnt).  Accordingly, if more than one sus_tsk has been issued on the task
in question (suscnt >= 2), that task will remain suspended even after the
execution of rsm_tsk is completed.  In contrast, frsm_tsk will clear all
suspend requests (suscnt = 0) even if more than one sus_tsk has been issued
(suscnt >= 2) on the same task.  In other words, SUSPEND state is guaranteed
to be released, and execution will resume unless the task in question had been
in combined WAIT-SUSPEND state.

[Supplemental Information]

It is implementation dependent which location in the ready queue a task
returns to after the task which has been suspended from RUN or READY
state is resumed by rsm_tsk or frsm_tsk.

If for example the following system calls were executed on task_A and task_B,
both having the same priority, the following operations would occur.

        sta_tsk (tskid = task_A);
        sta_tsk (tskid = task_B);
            /* According to FCFS, order on the ready queue is now task_A
               followed by task_B */

        sus_tsk (tskid = task_A);
        rsm_tsk (tskid = task_A);
            /* It is implementation dependent whether task_A now comes before
               task_B on the ready queue or vice versa */

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_OBJ     Invalid object state (the target task is not in SUSPEND state
            (including when it is DORMANT or when the issuing task specifies
            itself))
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion

[Differences from uITRON 2.0 and ITRON2 Specifications]

The order of tasks on the ready queue after rsm_tsk has been executed has been
made implementation dependent.

[Rationale]

The reason why frsm_tsk is included in [level EN] is that the suspend request
nesting feature is [level X].

The reason the order of tasks on the ready queue after rsm_tsk has been
executed has been made implementation dependent is given below.

From a specification standpoint, even when a task is in SUSPEND state, there
should be no influence on the scheduling order, as also with preemption.  This
viewpoint comes out of consideration of the meaning of suspension.  SUSPEND
state is orthogonal to other states and the fact that suspension is used to
forcibly suspend tasks when problems occur or during debugging.

From an implementation standpoint, on the other hand, efficient processing may
not be possible, depending on how the queue is implemented, if it is required
that queue order be maintained while tasks are suspended.  Hereafter "ready
queue" means a ready queue in the implementation sense, as distinct from a
ready queue as defined in the specification, in the sense of including only
tasks in RUN state and tasks in READY state.  Specifically, if a ready queue is
built to include suspended tasks (Implementation (A)) it is easy to maintain
queue order (that's just the way it always is).  But, when the implementation
actually removes suspended tasks from the ready queue (Implementation (B)), it
is difficult to return them to their original location when they are resumed by
rsm_tsk.  Since Implementation (B) may actually be better for improving
dispatching performance in cases where many suspended tasks can be expected,
there is a tradeoff between (A) and (B).  Mutually exclusive choice of which is
better between (A) and (B) cannot be made.  In addition, while it is possible
to implement both types of ready queues (those including suspended tasks and
those that do not), this implementation (C) may not always be a good approach
in consideration of the increased overhead of updating the queues and link area
for them.


========================================================================
|| [R] || slp_tsk || Sleep Task
========================================================================
|| [E] || tslp_tsk || Sleep Task with Timeout
========================================================================
   slp_tsk:       Sleep Task
  tslp_tsk:       Sleep Task with Timeout

  [Parameters (slp_tsk)]
  None

  [Parameters (tslp_tsk)]
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd =  slp_tsk ( ) ;
  ER ercd = tslp_tsk ( TMO tmout ) ;

[Description]

Both these system calls cause the issuing task (which is in RUN state) to
sleep until wup_tsk is invoked.

The tslp_tsk system call is the same as slp_tsk but with an additional timeout
feature.  If a wup_tsk is issued before the period of time specified by tmout
elapses, tslp_tsk will complete normally.  An E_TMOUT error will result if no
wup_tsk is issued before the time specified by tmout expires.  Specifying
tmout = TMO_FEVR = -1 can be used to set the timeout period to forever (no
timeout).  In this case, tslp_tsk will function exactly the same as slp_tsk
causing the issuing task to wait forever for wup_tsk to be issued.

[Supplemental Information]

Since the slp_tsk system call causes the issuing task to enter WAIT state,
slp_tsk calls may not be nested.  It is possible, however, for another task to
execute a sus_tsk on a task which has put itself in WAIT state using
slp_tsk.  If this happens, the task will enter the combined WAIT-SUSPEND state.
The same is true for tslp_tsk.

If you simply wish to delay a task (make it wait for a while), use dly_tsk
rather than tslp_tsk.

No polling function for slp_tsk is provided.  A similar function can be
implemented if necessary using can_wup.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (a timeout value -2 or less was specified)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout exceeded
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from wai_tsk to tslp_tsk.


========================================================================
|| [RN] || wup_tsk || Wakeup Other Task
========================================================================
  wup_tsk:        Wakeup Task
[Parameters]
  ID      tskid   TaskID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = wup_tsk ( ID tskid ) ;

[Description]

This system call releases the WAIT state of the task specified by tskid
caused by the execution of slp_tsk or tslp_tsk.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

A task cannot specify itself in this system call.  An E_OBJ error will result
if a task specifies itself.

If the specified task is not in the WAIT state caused by a slp_tsk or
tslp_tsk, the wakeup request based on the wup_tsk call will be queued.
In other words, a record will be kept that a wup_tsk has been issued
for the specified task and no WAIT state will result even if slp_tsk or
tslp_tsk is executed by the task later.  This is called queuing for wakeup
request.

Wakeup requests are queued as follows.  A wakeup request queuing count (wupcnt)
is kept in the TCB for each task.  Initially (when sta_tsk is executed) the
value of wupcnt is 0.  Executing wup_tsk on a task which is not waiting for a
wakeup increments the wakeup request queuing count by one for the specified
task.  If slp_tsk or tslp_tsk is executed on that task, its wakeup request
queuing count will be decremented by one.  If the task with wakeup request
queuing count = 0 executes slp_tsk or tslp_tsk, that task will be put in
WAIT state rather than decrementing the wakeup request queuing count.

It is always possible to queue at least one wup_tsk (wupcnt = 1); the maximum
allowable number for the wakeup request queuing count (wupcnt) is
implementation dependent, and may be any number higher than or equal to one.
In other words, while the first wup_tsk issued to a task which is not waiting
for a wakeup will not result in an error, it is implementation dependent
whether or not any further wup_tsk calls on the same task will result in an
error.  The ability to queue more than one wakeup request is considered an
extended function [level X] for which compatibility and connectivity are not
guaranteed.

An E_QOVR error will result if wup_tsk is issued more than the maximum value
allowed for the wakeup request queuing count (wupcnt).

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_OBJ     Invalid object state (the specified task is in DORMANT state or
            the issuing task specified itself)
  E_QOVR    Queuing or nesting overflow (wakeup request queuing count
            will exceed the maximum value allowed for wupcnt)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion


========================================================================
|| [SN] || can_wup || Cancel Wakeup Request
========================================================================
  can_wup:        Cancel Wakeup Task

[Parameters]
  ID      tskid   TaskID

[Return Parameters]
  ER      ercd    ErrorCode
  INT     wupcnt  WakeupCount

[C Language Interface]
  ER ercd = can_wup ( INT *p_wupcnt, ID tskid ) ;

[Description]

This system call returns the wakeup request queuing count (wupcnt) for the
task specified by tskid while canceling all associated wakeup requests.
Specifically, it resets the wakeup request queuing count (wupcnt) to 0.

A task may specify itself by specifying tskid = TSK_SELF = 0.  Note, however,
that an E_ID error will result if tskid = TSK_SELF = 0 is specified when this
system call is issued from a task-independent portion.

Tasks can be handled through connection function.  If the implementation
supports the connection function, tskid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the task on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

[Supplemental Information]

An EN_RPAR error will result if the number of bits used on the target node is
larger than that used on the requesting node, and if a value not supported by
the requesting node is returned for wupcnt.

This system call can be used to determine whether or not processing has ended
within a certain period when a task should periodically waken up by wup_tsk
and do some processing.  In other words, if a task monitoring the progress
of its processing issues can_wup before issuing a slp_tsk after finishing
processing associated with a previous wakeup request, and if wupcnt,
one of can_wup's return parameters, is equal to or greater than one,
it indicates that the processing for the previous wakeup request does not
complete within a required time.  This allows the monitoring task to take
actions against processing delays.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID Number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OACV    Object access violation (A tskid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_OBJ     Invalid object state (the target task is in DORMANT state)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_RPAR   A value outside the range supported by the issuing node and/or
            transmission packet format was returned as a return parameter (a
            value outside supported range was returned for wupcnt)

****************************************************************************
***    3.3 Synchronization and Communication Functions                   ***
****************************************************************************

Synchronization and communication functions are completely independent of
tasks.  These functions include semaphores, eventflags and mailboxes.

Semaphores are used for synchronization and mutual exclusion by indicating
the availability and number of resources.  The task (the task which is
returning resources) notifying other tasks of an event increases the number
of resources held by the semaphore by one.  The task (the task which
will obtain resources) waiting for the event decreases the number of
resources held by the semaphore by one.  If the number of resources held by a
semaphore is insufficient (namely 0), the task requiring resources will
wait until the next time resources are returned to the semaphore.  If there is
more than one task waiting for a semaphore, the tasks will be placed in the
queue.

Eventflags are a synchronization function which use bit correspondence flags
to represent the availability of events.  The task notifying other tasks of an
event can set and clear certain bits of the associated eventflag.  Tasks
waiting for the event will continue to wait until certain conditions,
represented by the bit pattern of the eventflag, have been met.

Mailboxes are used for both synchronization and communication by passing
messages.  The task notifying other tasks of an event (the task which are
sending a message) can place messages on a message queue.  Tasks waiting for
the event (tasks which will receive the message) can retrieve messages from
the message queue.  If there is no message on the message queue yet, the task
will wait until the next message arrives.  If there is more than one task
waiting for a message the tasks will be placed in a queue.

The contents of messages are in shared memory, and only the corresponding
first address is actually sent or received.  Message packet contents are not
copied.  Therefore, different nodes with no shared memory between them can't
make use of mailboxes and mailboxes do not support the connection function
for different nodes.  If messages need to be transferred between different
nodes, you should use messagebuffers, an extended synchronization and
communication function, rather than mailboxes.  Messagebuffers support the
connection function and copy message contents.

There are two ways of implementing a message queue: using a linear list or
using a ring buffer.  It is implementation dependent which approach is
used.  Even if a ring buffer is used for the message queue, tasks sending
messages (tasks issuing snd_msg) do not wait in cases when the ring buffer
is full and the message cannot be enqueued.  Rather than entering WAIT
state in a case like this, an E_QOVR error is returned to the task that
issues snd_msg.  A ring buffer, if adopted for the message queue, requires
the specification of the size of the ring buffer when creating the mailbox.

On the other hand, if a linear list is adopted for the message queue, an
area of memory so the OS may link the linear list becomes necessary inside
each message packet.  This means that the OS uses part of the message packet
prepared by the user for management purposes.  This part is called the message
header.  When message headers are required, the message start address
parameter (pk_msg) of snd_msg represents the start address of the message
packet including the message header part (Figure 12).  Furthermore, if the
mailbox attributes include the use of message priority, the message priority
(msgpri) of each message is specified in the message header.  Note that
message priority support is considered an extended function [level X] for
which compatibility and connectivity are not guaranteed.  When the user puts
a message, that message is not located immediately after pk_msg, but after
the message header ("msgcont" in the figure).  Whether or not message
headers are used and if so their size and format are all implementation
dependent.



 pk_msg ===> |----------------------------------------------------------|
             |                      Message header                      |
             |                                                          |
             | *Whether or not there is a message header and if so what |
             |  its contents will be are both implementation dependent. |
             | *In some cases the message header may include            |
             |  information on message priority (msgpri).               |
             |                                                          |
             +----------------------------------------------------------+
             |                                                          |
             |                                                          |
             |                Message Contents (msgcont)                |
             |                                                          |
             |                                                          |
             |----------------------------------------------------------|

                  Figure 12 Message Format Used by Mailboxes


Memory blocks dynamically allocated from the memorypool using get_blk or
get_blf may be used to hold message packets.  Statically allocated memory may
also be used as well.  Typical procedure for the sending task in this case is
to obtain a memory block from the memorypool and send a block as a message.
After the receiving task reads the message, it directly returns the memory
block to the memorypool.

[Supplemental Information]

As stated previously both linear lists and ring buffers may be used to
implement message queues.  The advantages and disadvantages of using linear
lists are outlined below.

Advantages of using linear lists:

  - It is easy to delete messages from and insert new messages into the middle
    of the queue.  This makes it easy to implement a priority-ordered message
    queue.

  - The message queue (buffer) will never overflow.

  - It is not necessary to obtain memory for the message queue (buffer) when
    creating the mailbox.

Disadvantages of using linear lists:

  - A message header area for use by the OS is required within message packets.

  - Physical memory is required at the location pointed to by pk_msg.  It is
    impossible to send any data as pk_msg.

  - There is a danger that the system will go down because the message queue
    data structure is broken when a message in the message queue which has
    already been sent is accidentally resent using snd_msg.

The advantages and disadvantages of using a ring buffer to implement the
message queue are the inverse of those given above.

[Differences from uITRON 2.0 and ITRON2 Specifications]

It has been clarified that message queue implementation (whether to use a
linear list or ring buffer) is completely implementation dependent.


========================================================================
|| [EN] || cre_sem || Create Semaphore
========================================================================
  cre_sem:        Create Semaphore

[Parameters]
  ID      semid   SemaphoreID
  T_CSEM *pk_csem Packet to Create Semaphore
 -(pk_csem members)-
  VP      exinf   ExtendedInformation
  ATR     sematr  SemaphoreAttributes
  INT     isemcnt InitialSemaphoreCount [level X]
  INT     maxsem  MaximumSemaphoreCount [level X]
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = cre_sem ( ID semid, T_CSEM *pk_csem ) ;

[Description]

This system call creates the semaphore whose ID is specified by semid.
Specifically, a control block for the semaphore to be created is allocated,
the associated initial semaphore count is set to isemcnt and maximum allowable
semaphore count is set to maxsem.

The ability to set isemcnt and maxsem is considered an extended function
[level X] for which compatibility and connectivity are not guaranteed.
If isemcnt cannot be specified, it will be initialized to one.  If maxsem
cannot be specified, the maximum allowable value is implementation dependent.

Semaphores can be handled through connection function.  If the implementation
supports the connection function, semid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the semaphore on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

User semaphores have positive ID numbers, while system semaphores have
negative ID numbers.  User tasks (tasks having positive task IDs) cannot
access system semaphores (semaphores having negative ID numbers).  An E_OACV
error will result if a user task issues a system call on a system semaphore,
but error detection is implementation dependent.

Semaphores having ID numbers from -4 through 0 cannot be created.  An E_ID
error will result if a value in this range is specified for semid.

Exinf may be used freely by the user for including extended information about
the semaphore to be created.  Information set here may be accessed by ref_sem.
If a larger region is desired for including user information, or if the user
wishes to change the contents of this information, the usr should allocate
memory area and set the address of this memory packet to exinf.  The OS
does not take care of the contents of exinf.

The lower bits of sematr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of sematr may be specified as follows.

        sematr := (TA_TFIFO || TA_TPRI)

        TA_TFIFO    FIFO-ordered queuing of waiting tasks
        TA_TPRI     Priority-ordered queuing of waiting tasks [level X]

TA_TFIFO and TA_TPRI are used to specify the manner in which waiting tasks are
put on the semaphore's queue.  If TA_TFIFO is specified, tasks will be put on
the queue on a "First In, First Out" basis.  If TA_TPRI is specified, tasks
will be placed on the queue according to their priority level.  The TA_TPRI
specification is considered an extended function [level X] for which
compatibility and connectivity are not guaranteed.

The format of sematr is shown in Figure 13.



   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - P|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - P|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - P|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           sematr is 16 bits or less.
        2. P=1 specifies priority-ordered queuing of waiting tasks (TA_TPRI).

                           Figure 13 sematr Format


[Supplemental Information]

An EN_PAR error will result if the number of bits used on the requesting node
is larger than that used on the target node and a value not supported by the
target node is specified for exinf, sematr, isemcnt or maxsem.

Although the standard packet format of pk_csem (the order and number of bits
associated with each member) is as stated above, it may be changed as
necessary for implementation on various systems as long as restriction
on compatibility and connectivity with other systems is not a problem.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block cannot be allocated)
  E_ID      Invalid ID number (semid was invalid or could not be used)
  E_RSATR   Reserved attribute (sematr was invalid or could not be used)
  E_OBJ     Invalid object state (a semaphore of the same ID already exists)
  E_OACV    Object access violation (A semid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (pk_csem is invalid and/or isemcnt or maxsem is
            negative or invalid)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for exinf, sematr, isemcnt
            and/or maxsem)

[Differences from uITRON 2.0 and ITRON2 Specifications]

According to uITRON 2.0 specification, semaphore count is not specified to
sig_sem or wai_sem.  For this reason, attributes of new semaphores are limited
to TA_FIRST, TA_FIX equivalents.

Queuing by priority is at [level X].

The ability to check maximum semaphore count (maxsem) has been introduced
at [level X].


========================================================================
|| [EN] || del_sem || Delete Semaphore
========================================================================
  del_sem:        Delete Semaphore

[Parameters]
  ID      semid   SemaphoreID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = del_sem ( ID semid ) ;

[Description]

This system call deletes the semaphore specified by semid.

Semaphores can be handled through connection function.  If the implementation
supports the connection function, semid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the semaphore on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Issuing this system call causes memory used for the control block of the
associated semaphore to be released.  After this system call is invoked,
another semaphore having the same ID number can be created.

This system call will complete normally even if there are tasks waiting for
the semaphore.  In that case, an E_DLT error will be returned to each
waiting task.

[Supplemental Information]

When a semaphore being waited for by more than one tasks is deleted, the order
of tasks on the ready queue after the WAIT state is cleared is implementation
dependent in the case of tasks having the same priority.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (semid was invalid or could not be used)
  E_NOEXS   Object does not exist (the semaphore specified by semid does not
            exist)
  E_OACV    Object access violation (A semid less than -4 was specified from
            a user task.  This is implementation dependent.)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion


========================================================================
|| [RN] || sig_sem || Signal Semaphore
========================================================================
  sig_sem:        Signal Semaphore

[Parameters]
  ID      semid   SemaphoreID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = sig_sem ( ID semid ) ;

[Description]

This system call returns one resource to the semaphore specified by semid.
Specifically, if there are any tasks waiting for the specified semaphore, the
task at the head of the queue become RUN or READY state.  When this happens,
the associated semaphore count (semcnt) remains unchanged.  On the other hand,
if there are no tasks waiting for the semaphore, the associated semaphore
count (semcnt) is incremented by one.

Semaphores can be handled through connection function.  If the implementation
supports the connection function, semid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the semaphore on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

An E_QOVR error will result if, as a result of increment, the semaphore count
would exceed the maximum allowable semaphore count (maxcnt).  However, the
ability to check for errors related to the maximum allowable semaphore count
is considered an extended function [level X] for which compatibility
and connectivity are not guaranteed.  Note that in some cases the maximum
allowable semaphore count will be determined by conditions of the
implementation (such as limited number of bits) rather than explicitly
specified by the user.

If cre_sem [level EN] is not implemented on the system, semaphores are
created statically on system startup.  Parameters required for creating a
semaphore, such as semaphore attributes (sematr) and initial semaphore count
(isemcnt) are also specified statically at system startup.

[Supplemental Information]

No error results when the semaphore count (semcnt) exceeds the initial
semaphore count (isemcnt).  There are situations where the semaphore count
(semcnt) will exceed the initial semaphore count (isemcnt) when a semaphore is
being used for synchronization (as with the pair of wup_tsk and slp_tsk)
rather than mutual exclusion control.  If, on the other hand, a semaphore
is being used for exclusive control, it is possible to check for errors due
to semaphore count increment by setting the maximum allowable semaphore
count (maxsem) to a value equal to the initial semaphore count (isemcnt).

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (semid was invalid or could not be used)
  E_NOEXS   Object does not exist (the semaphore specified by semid does not
            exist)
  E_OACV    Object access violation (A semid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_QOVR    Queuing or nesting overflow (the queuing count given by semcnt
            went over the maximum allowed)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion


========================================================================
|| [RN] || wai_sem || Wait on Semaphore
========================================================================
|| [RN] || preq_sem || Poll and Request Semaphore
========================================================================
|| [EN] || twai_sem || Wait on Semaphore with Timeout
========================================================================
   wai_sem:       Wait on Semaphore
  preq_sem:       Poll and Request Semaphore
  twai_sem:       Wait on Semaphore with Timeout

[Parameters (for wai_sem and preq_sem)]
  ID      semid   SemaphoreID

[Parameters (for twai_sem)]
  ID      semid   SemaphoreID
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd =  wai_sem ( ID semid ) ;
  ER ercd = preq_sem ( ID semid ) ;
  ER ercd = twai_sem ( ID semid, TMO tmout ) ;

[Description]

The wai_sem system call obtains one resource from the semaphore specified by
semid.  Specifically, if the count (semcnt) for the specified semaphore is one
or greater, that semaphore's count is decremented by one.  In this case, the
task issuing this system call is not put in WAIT state, but rather continues to
execute.  If, on the other hand, the semaphore's count (semcnt) is 0, the task
issuing this system call will become WAIT state and be put on a queue
associated with the specified semaphore.  The semaphore's count (semcnt), 0,
will remain unchanged in this case.

Semaphores can be handled through connection function.  If the implementation
supports the connection function, semid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the semaphore on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

The preq_sem system call has the same function as wai_sem except for the
waiting feature.  Preq_sem polls whether or not the task should wait if
wai_sem is executed.  The meaning of parameters for preq_sem are the same as
for wai_sem.  The specific operations of preq_sem are as follows.

  - If the count (semcnt) of the specified semaphore is one or greater,
    processing is the same as wai_sem: the semaphore's count is decremented
    by one and the system call completes normally.

  - If the count (semcnt) of the specified semaphore is 0, an E_TMOUT error is
    returned to indicate polling failed and the system call finishes.  Unlike
    wai_sem, preq_sem does not wait in this case.  Just as with wai_sem, the
    semaphore's count remains unchanged.

The twai_sem system call has the same function as wai_sem with an additional
timeout feature.  A maximum wait time (timeout value) can be specified using
the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT,
will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied (i.e. without
sig_sem being executed).

Only positive values can be specified for tmout.  Although the time base for
tmout is recommended to be the same as that for the system clock (1 ms is
recommended), it may sometimes be larger than the time base of system clock
for 8 and 16-bit processors.  If an object on another node is being waited
for, the time base used for the timeout is that of the requesting node,
not of the target node.

Specifying TMO_POL = 0 to twai_sem for tmout indicates that a timeout value of
0 be used, resulting in exactly the same processing as preq_sem.  Specifying
TMO_FEVR = -1 to twai_sem for tmout indicates that an infinite timeout value
be used, resulting in exactly the same processing as wai_sem.

[Supplemental Information]

An EN_PAR error will result if the bit length used on the requesting node is
larger than that used on the target node and a value not supported by the
target node is specified for tmout.

Preq_sem and wai_sem represent the same processing as specifying certain
values (TMO_POL or TMO_FEVR) to twai_sem for tmout.  It is allowed that
only twai_sem is implemented in the kernel and that preq_sem and wai_sem
are implemented as macros which call twai_sem.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (semid was invalid or could not be used)
  E_NOEXS   Object does not exist (the semaphore specified by semid does not
            exist)
  E_OACV    Object access violation (A semid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (tmout is -2 or less)
  E_DLT     The object being waited for was deleted (the specified semaphore
            was deleted while waiting)
  E_RLWAI   Wait state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout exceeded
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for tmout)

[Differences from uITRON 2.0 and ITRON2 Specifications]

Timeout function is separated to a new system call named under the form
t???_???.  It is the same with other system calls which may enter WAIT states.

With the establishment of separate system calls which check for a timeout, the
error E_RSFN has been established for the t???_??? family of system calls to
indicate that t???_??? system calls are not supported because no timer is
available on the system.  The E_TNOSPT error has therefore been removed.


========================================================================
|| [EN] || ref_sem || Reference Semaphore Status
========================================================================
  ref_sem:        Reference Semaphore Status

[Parameters]
  ID      semid   SemaphoreID
  T_RSEM  *pk_rsem        Packet to Reference Semaphore

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rsem members)-
  VP      exinf   ExtendedInformation
  BOOL_ID wtsk    WaitingTaskInformation
  INT     semcnt  SemaphoreCount
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_sem ( T_RSEM *pk_rsem, ID semid ) ;

[Description]

This system call refers to the state of the semaphore specified by semid, and
returns its current semaphore count (semcnt), waiting task information (wtsk),
and its extended information (exinf).

Semaphores can be handled through connection function.  If the implementation
supports the connection function, semid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the semaphore on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Even if semid specifies a semaphore on another node, semaphore status
information (packet contents) which are read are automatically transferred
to the requesting node from the target node.

Wtsk indicates whether or not there is a task waiting for the semaphore in
question.  If there is no waiting task, wtsk is returned as FALSE = 0.  If
there is a waiting task, wtsk is returned as a value other than 0.

Depending on the implementation, wtsk may be returned as the ID (non-zero) of
the task waiting for the semaphore.  If there are multiple
tasks waiting for the semaphore, the ID of the task at the head of the queue
is returned.  However, this feature is considered an extended function
[level X] for which compatibility and connectivity are not guaranteed.
Even with implementations which return the ID of waiting tasks in wtsk,
the value of wtsk may not be correct (may be non-zero but undefined)
if the waiting task is on another node.  If a system returns the ID
of a waiting task, the task ID as seen from the access environment of the
node to which the semaphore specified to ref_sem belongs should be returned.

An E_NOEXS error will result if the semaphore specified to ref_sem does not
exist.

At least one of semcnt = 0 and wtsk = FALSE is always true in this
system call.

[Supplemental Information]

An EN_RPAR error will result if the number of bits used on the target node is
larger than that used on the requesting node, and if a value not supported by
the requesting node is returned for exinf, wtsk or semcnt.

Although both ref_sem and preq_sem can be used to find a semaphore's count
(semcnt) without causing the issuing task to wait, ref_sem simply reads the
semaphore's count (semcnt), while preq_sem functions identically to wai_sem
(decrements the semaphore count) when the count value is positive.

When using the [level X] feature whereby the ID of waiting tasks can be
returned to wtsk, the fact that the value of wtsk may not be correct when the
waiting task is on another node is due to restrictions on the implementation
of the connection function.  In other words, if connection function processing
is being carried out by another task (connection function processing task)
on target node, the ID of the connection function processing task will appear
as the ID of the waiting task, not the ID of the task which issued the
wai_sem system call.  If the task issuing wai_sem is on another node,
it may not be possible to access the same task using that ID even if the
correct task ID is returned by wtsk.  In other words, sometimes the value of
wtsk is meaningless even when the correct task ID is returned.

Depending on the implementation, additional information besides wtsk and
semcnt (such as the maximum allowable semaphore count, maxsem) may also be
referred.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (semid was invalid or could not be used)
  E_NOEXS   Object does not exist (the semaphore specified by semid does not
            exist)
  E_OACV    Object access violation (A semid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_RPAR   A value outside the range supported by the requesting node and/or
            transmission packet format was returned as a parameter (a value
            outside supported range was specified for exinf, wtsk or semcnt)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from sem_sts to ref_sem.


========================================================================
|| [EN] || cre_flg || Create Eventflag
========================================================================
  cre_flg:        Create EventFlag

[Parameters]
  ID      flgid   EventFlagID
  T_CFLG *pk_cflg Packet to Create EventFlag
 -(pk_cflg members)-
  VP      exinf   ExtendedInformation
  ATR     flgatr  EventFlagAttributes
  UINT    iflgptn InitialEventFlagPattern
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = cre_flg ( ID flgid, T_CFLG *pk_cflg ) ;

[Description]

This system call creates the eventflag specified by flgid.  Specifically, a
control block for the eventflag to be created is allocated and the associated
flag pattern is initialized using iflgptn.  A single eventflag handles one
word's worth of bits of the processor in question as a group.  All operations
are done in single word units.

Eventflags can be handled through connection function.  If the implementation
supports the connection function, flgid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the eventflag on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

User eventflags have positive ID numbers, while system eventflags have
negative ID numbers.  User tasks (tasks having positive task IDs) cannot
access system eventflags (eventflags having negative ID numbers).  An E_OACV
error will result if a user task issues a system call on a system eventflag,
but error detection is implementation dependent.

Eventflags having ID numbers from -4 through 0 cannot be created.  An E_ID
error will result if a value in this range is specified for flgid.

Exinf may be used freely by the user for including extended information about
the eventflag to be created.  Information set here may be accessed by ref_flg.
If a larger region is desired for including user information, or if the user
wishes to change the contents of this information, the usr should allocate
memory area and set the address of this memory packet to exinf.  The OS
does not take care of the contents of exinf.

The lower bits of flgatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of flgatr may be specified as follows.

        flgatr := (TA_WMUL || TA_WSGL)

        TA_WMUL Waiting for multiple tasks is not allowed (Wait Single Task)
        TA_WSGL Waiting for multiple tasks is allowed (Wait Multiple Tasks)
                [Level X]

Specifying TA_WMUL allows multiple tasks to wait.  This feature is considered
an extended function [level X] for which compatibility and
connectivity are not guaranteed.  So, it may not always be available.

The format of flgatr is shown in Figure 14.



   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - W - - -|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - W - - -|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - W - - -|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           flgatr is 16 bits or less.
        2. W=1 indicates that multiple task waiting (TA_WMUL) is allowed.

                           Figure 14 flgatr Format


[Supplemental Information]

An EN_PAR error will result if the number of bits used on the requesting node
is larger than that used on the target node and a value not supported by the
target node is specified for exinf, flgatr or iflgptn.

Although the standard packet format of pk_cflg (the order and number of bits
associated with each member) is as stated above, it may be changed as
necessary for implementation on various systems as long as restriction
on compatibility and connectivity with other systems is not a problem.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block cannot be allocated)
  E_ID      Invalid ID number (flgid was invalid or could not be used)
  E_RSATR   Reserved attribute (flgatr was invalid or could not be used)
  E_OBJ     Invalid object state (an eventflag of the same ID already exists)
  E_OACV    Object access violation (A flgid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (pk_cflg is invalid)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for exinf, flgatr and/or
            iflgptn)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The TA_WMUL feature is at [level X].

The ability to set the initial eventflag pattern with iflgptn has been added.


========================================================================
|| [EN] || del_flg || Delete Eventflag
========================================================================
  del_flg:        Delete EventFlag

[Parameters]
  ID      flgid   EventFlagID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = del_flg ( ID flgid ) ;

[Description]

This system call deletes the eventflag specified by flgid.

Eventflags can be handled through connection function.  If the implementation
supports the connection function, flgid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the eventflag on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Issuing this system call causes memory used for the control block of the
associated eventflag to be released.  After this system call is invoked,
another eventflag having the same ID number can be created.

This system call will complete normally even if there are tasks waiting for
the eventflag.  In that case, an E_DLT error will be returned to each
waiting task.

[Supplemental Information]

When an eventflag being waited for by more than one tasks is deleted, the order
of tasks on the ready queue after the WAIT state is cleared is implementation
dependent in the case of tasks having the same priority.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (flgid was invalid or could not be used)
  E_NOEXS   Object does not exist (the eventflag specified by flgid does not
            exist)
  E_OACV    Object access violation (A flgid less than -4 was specified from
            a user task.  This is implementation dependent.)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion


========================================================================
|| [SN] || set_flg || Set Eventflag
========================================================================
|| [SN] || clr_flg || Clear Eventflag
========================================================================
  set_flg:        Set EventFlag
  clr_flg:        Clear EventFlag

[Parameters (for set_flg)]
  ID      flgid   EventFlagID
  UINT    setptn  SetBitPattern

[Parameters (for clr_flg)]
  ID      flgid   EventFlagID
  UINT    clrptn  ClearBitPattern

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = set_flg ( ID flgid, UINT setptn ) ;
  ER ercd = clr_flg ( ID flgid, UINT clrptn ) ;

[Description]

The set_flg system call sets the bits specified by setptn of the one word
eventflag specified by flgid.  In other words, a logical sum is taken for the
values of the eventflag specified by flgid with the value of setptn.  The
clr_flg system call clears the bits of the one word eventflag based on the
corresponding zero bits of clrptn.  In other words, a logical product is taken
for the values of the eventflag specified by flgid with the value of clrptn.

Eventflags can be handled through connection function.  If the implementation
supports the connection function, flgid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the eventflag on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

If the eventflag value is changed by set_flg and the new eventflag value
satisfies the condition to release the WAIT state of the task which issued
wai_flg on the eventflag, the WAIT state of that task will be released and
the task will be put into RUN or READY state (or SUSPEND state if the task
was in WAIT-SUSPEND).

Issuing clr_flg never results in wait conditions being released on a task
waiting for the specified eventflag.  In other words, dispatching never
occurs with clr_flg.

Nothing will happen to the target eventflag if all bits of setptn are
specified as 0 with set_flg or if all bits of clrptn are specified as 1 with
clr_flg.  No error will result in either case.

If cre_flg [level EN] is not implemented on the system, eventflags
are created statically when the system is started.  Parameters required for
creating an eventflag, such as eventflag attributes (flgatr) and initial
eventflag pattern (iflgptn) are also specified statically at system startup.

Multiple tasks can wait for a single eventflag if that eventflags has the
TA_WMUL attribute.  This means that even eventflags can make queues for tasks
to wait on.  When such eventflags are used, a single set_flg call may result in
the release of multiple waiting tasks.  In this case, the order of tasks on the
ready queue after the WAIT state is cleared is preserved for tasks having the
same priority.  The feature represented by TA_WMUL, whereby multiple tasks may
wait for a single eventflag, is considered an extended function [level X] for
which compatibility and connectivity are not guaranteed.

[Supplemental Information]

If eventflags of differing bit lengths exist on the same network due to use of
the connection function, the least significant bits are used.  For example, if
the requesting node is 8 bit and the node on which the target eventflag exists
is 32 bit long (supporting 32-bit eventflags), then only the least significant
8 bits of the 32 total can be manipulated using set_flg and clr_flg.

An EN_PAR error will result if the bit length of eventflags on the requesting
node is larger than that used on the target node and a value not supported by
the target node is specified for setptn or clrptn.

If you wish to conserve memory and parameter space on a small system, 1-bit
eventflags may be used under the condition that compatibility with other
systems is not guaranteed.

If 1-bit eventflags are used, the parameters setptn and clrptn for set_flg
and clr_flg are not needed.  If 1-bit eventflags and one-word eventflags
exist on the same network due to use of the connection function, the least
significant bit of one-word eventflags will be used to correspond to a 1-bit
eventflag.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (flgid was invalid or could not be used)
  E_NOEXS   Object does not exist (the eventflag specified by flgid does not
            exist)
  E_OACV    Object access violation (A flgid less than -4 was specified from
            a user task.  This is implementation dependent.)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for setptn or clrptn)


========================================================================
|| [SN] || wai_flg || Wait for Eventflag
========================================================================
|| [SN] || pol_flg || Wait for Eventflag (Polling)
========================================================================
|| [EN] || twai_flg || Wait for Eventflag with Timeout
========================================================================
   wai_flg:       Wait for EventFlag
   pol_flg:       Poll EventFlag
  twai_flg:       Wait for EventFlag with Timeout

[Parameters (for wai_flg and pol_flg)]
  ID      flgid   EventFlagID
  UINT    waiptn  WaitBitPattern
  UINT    wfmode  WaitEventFlagMode

[Parameters (for twai_flg)]
  ID      flgid   EventFlagID
  UINT    waiptn  WaitBitPattern
  UINT    wfmode  WaitEventFlagMode
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode
  UINT    flgptn  EventFlagBitPattern

[C Language Interface]
  ER ercd =  wai_flg ( UINT *p_flgptn, ID flgid, UINT waiptn, UINT wfmode ) ;
  ER ercd =  pol_flg ( UINT *p_flgptn, ID flgid, UINT waiptn, UINT wfmode ) ;
  ER ercd = twai_flg ( UINT *p_flgptn, ID flgid, UINT waiptn, UINT wfmode, TMO
                       tmout ) ;

[Description]

The wai_flg system call waits for the eventflag specified by flgid to be set
to satisfy the wait release condition specified by wfmode.

If the eventflag specified by flgid already satisfies the wait release
conditions given by wfmode, the issuing task will continue execution without
waiting.

Eventflags can be handled through connection function.  If the implementation
supports the connection function, flgid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the eventflag on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Wfmode may be specified as follows.

        wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR]

        TWF_ANDW        H'0...000       AND wait
        TWF_ORW         H'0...002       OR wait
        TWF_CLR         H'0...001       Clear specification

If TWF_ORW is specified, the issuing task will wait for any of the bits
specified by waiptn to be set for the eventflag given by flgid (OR wait).  If
TWF_ANDW is specified, the issuing task will wait for all of the bits
specified by waiptn to be set for the eventflag given by flgid (AND wait).

If the TWF_CLR specification is not present, the eventflag value will remain
unchanged even after the wait conditions have been satisfied and the task has
been released from the WAIT state.  If TWF_CLR is specified, all bits of the
eventflag will be cleared to 0 once the wait conditions of the waiting task
have been satisfied.

The return parameter flgptn returns the value of the eventflag after the wait
state of a task has been released due to this system call.  If TWF_CLR was
specified, the value before eventflag bits were cleared is returned.  The
value returned by flgptn fulfills the wait release conditions of this system
call.

The pol_flg system call has the same function as wai_flg except for the
waiting feature.  Pol_flg polls whether or not the task should wait if
wai_flg is executed.  The meaning of parameters to pol_flg are the same as
for wai_flg.  The specific operations by pol_flg are as follows.

  - If the target eventflag already satisfies the conditions for releasing
    wait given by wfmode, processing is the same as wai_flg: the eventflag
    is cleared if TWF_CLR is specified and the system call completes
    normally.

  - If the target eventflag does not yet satisfy the conditions for
    releasing wait given by wfmode, an E_TMOUT error is returned to indicate
    polling failed and the system call finishes.  Unlike wai_flg, the
    issuing task does not wait in this case.  The eventflag is not cleared
    in this case even if TWF_CLR has been specified.

The twai_flg system call has the same function as wai_flg with an additional
timeout feature.  A maximum wait time (timeout value) can be specified using
the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT,
will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied.

Only positive values can be specified for tmout.  Although the time base for
tmout is recommended to be the same as that for the system clock (1 ms is
recommended), it may sometimes be larger than the time base of system clock
for 8 and 16-bit processors.  If an object on another node is being waited
for, the time base used for the timeout is that of the requesting node,
not of the target node.

Specifying TMO_POL = 0 to twai_flg for tmout indicates that a timeout value of
0 be used, resulting in exactly the same processing as pol_flg.  Specifying
TMO_FEVR = -1 to twai_flg for tmout indicates that an infinite timeout value
be used, resulting in exactly the same processing as wai_flg.

An E_PAR parameter error will result if waiptn is 0.

A task can not execute any of wai_flg, twai_flg or pol_flg on an eventflag
having the TA_WSGL attribute if another task is already waiting for that
eventflag.  An E_OBJ error will be returned to a task which executes wai_flg at
a later time regardless as to whether or not the task that executes wai_flg or
twai_flg later will be placed in a WAIT state (conditions for releasing wait
state be satisfied).  An E_OBJ error will be returned even to tasks which just
execute pol_flg, again regardless as to whether or not wait release conditions
for that task were satisfied.

On the other hand, multiple tasks can wait at the same time for the same
eventflag if that eventflag has the TA_WMUL attribute.  This means that even
event flags can make queues for tasks to wait on.  When such eventflags are
used, a single set_flg call may release multiple waiting tasks.  The feature
represented by TA_WMUL, whereby multiple tasks may wait for a single eventflag,
is considered an extended function [level X] for which compatibility
and connectivity are not guaranteed.

The following processing takes place if a queue for allowing multiple tasks to
wait has been created for en eventflag with the TA_WMUL attribute.

  - The waiting order on the queue is FIFO.  (However, depending on waiptn and
    wfmode, task at the head of the queue will not always be released from
    waiting.)

  - If a task specifying that the eventflag be cleared is on the queue, the
    flag is cleared when that task is released from waiting.

  - Since any tasks behind a task which clears the eventflag (by specifying
    TWF_CLR) will check the eventflag after it is cleared, they will not
    be released from waiting.

If multiple tasks having the same priority are released from waiting
simultaneously due to set_flg, the order of tasks on the ready queue after
release will be the same as their original order on the eventflag queue.

[Supplemental Information]

An EN_PAR error will result if the bit length of eventflags on the requesting
node is larger than that used on the target node and a value not supported by
the target node is specified for waiptn or tmout.

An EN_RPAR error will result if the bit length of eventflags on the target
node is larger than that used on the requesting node, and if a value not
supported by the requesting node is returned for flgptn.

If a logical sum of all bits is specified to wai_flg as the condition for
releasing wait (waiptn = H'fff...ff, wfmode = TWF_ORW), it is possible to
transfer messages using one-word bit patterns with a combination of set_flg.
However, it is not possible to send a message containing only 0s for all bits.
In addition, if the next message is sent before the previous message has
been read by wai_flg, the previous message will be lost.  In other words,
message queuing is not possible.

Since specifying waiptn = 0 will result in an E_PAR error, it is guaranteed
that the waiptn of tasks waiting for an eventflag will not be 0.  The result
is that if set_flg sets all bits of eventflag to 1 the task at the head of
the queue will always be released from waiting no matter what its wait
condition is.

The feature whereby multiple tasks may wait for the same eventflag is useful
in the following type of situation.  Let's say that Task B and Task C are
already waiting on wai_flg calls (2) and (3) till Task A executes set_flg.
If multiple task wait is allowed for the eventflag, results are the same
regardless of the order in which (1), (2) and (3) execute (Figure 15).
If multiple task wait is not allowed and system calls are executed in the
order (2), (3), (1), an E_OBJ error will result from the execution of
wai_flg (3).




      [Task A]              [Task B]              [Task C]
          |                     |                     |
          |                     |                     |
     (1) set_flg           (2) wai_flg           (3) wai_flg
          |                     |(no clearing)        |(no clearing)
          |                     |                     |
          |                     |                     |

           Figure 15 The Multiple Task Wait Feature of Eventflags


Pol_flg and wai_flg represent the same processing as specifying certain
values (TMO_POL or TMO_FEVR) to twai_flg for tmout.  As such, only twai_flg
is implemented in the kernel; pol_flg and wai_flg should be implemented as
macros which call twai_flg.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (flgid was invalid or could not be used)
  E_NOEXS   Object does not exist (the eventflag specified by flgid does not
            exist)
  E_OACV    Object access violation (A flgid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 or
            less)
  E_OBJ     Invalid object state (multiple tasks waiting for an eventflag
            with the TA_WSGL attribute)
  E_DLT     The object being waited for was deleted (the specified eventflag
            was deleted while waiting)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout exceeded
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for waiptn and tmout)
  EN_RPAR   A value outside the range supported by the requesting node and/or
            transmission packet format was specified as a parameter (a value
            exceeding the range for the requesting node was specified for
            flgptn)

[Differences from uITRON 2.0 and ITRON2 Specifications]

Timeout function is separated to a new system call named under the form
t???_???.  It is the same with other system calls which may enter WAIT states.

To make descriptions clearer the phrase "satisfy wait release conditions"
is now used instead of "satisfy (meet) wait conditions".

[Rationale]

The reason specifying waiptn = 0 results in an E_PAR error is that if the
specification were allowed tasks would never be able to finish WAIT state
no matter what value the eventflag being waited for assumed.


========================================================================
|| [EN] || ref_flg || Reference Eventflag Status
========================================================================
  ref_flg:        Reference EventFlag Status

[Parameters]
  ID      flgid   EventFlagID
  T_RFLG  *pk_rflg        Packet to Reference EventFlag

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rflg members)-
  VP      exinf   ExtendedInformation
  BOOL_ID wtsk    WaitingTaskInformation
  UINT    flgptn  EventFlagBitPattern
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_flg ( T_RFLG *pk_rflg, ID flgid ) ;

[Description]

This system call refers to the state of the eventflag specified by flgid,
and returns its current flag pattern (flgptn), waiting task information (wtsk),
and its extended information (exinf).

Eventflags can be handled through connection function.  If the implementation
supports the connection function, flgid is converted to a pair of node
number and object number using an object location table.
This pair is then used to access the eventflag on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Even if flgid specifies an eventflag on another node, eventflag status
information (packet contents) which are read are automatically transferred
to the requesting node from the target node.

Wtsk indicates whether or not there is a task waiting for the eventflag in
question.  If there is no waiting task, wtsk is returned as FALSE = 0.  If
there is a waiting task, wtsk is returned as a value other than 0.

Depending on the implementation, wtsk may be returned as the ID (non-zero) of
the task waiting for the eventflag.  If there are multiple
tasks waiting for the eventflag (only when attribute is TA_WMUL),
the ID of the task at the head of the queue is returned.
However, this feature is considered an extended function
[level X] for which compatibility and connectivity are not guaranteed.
Even with implementations which return the ID of waiting tasks in wtsk,
the value of wtsk may not be correct (may be non-zero but undefined)
if the waiting task is on another node.  If a system returns the ID
of a waiting task, the task ID as seen from the access environment of the
node to which the eventflag specified to ref_flg belongs should be returned.

An E_NOEXS error will result if the eventflag specified to ref_flg does not
exist.

[Supplemental Information]

An EN_RPAR error will result if the number of bits used on the target node is
larger than that used on the requesting node, and if a value not supported by
the requesting node is returned for exinf, wtsk or flgptn.

Although both ref_flg and pol_flg can be used to find an eventflag's pattern
(flgptn) without causing the issuing task to wait, ref_flg simply reads the
eventflag's pattern (flgptn) while pol_flg functions identically to wai_flg
when wait release conditions are satisfied (it clears the eventflag if
TWF_CLR is specified).

When using the [level X] feature whereby the ID of waiting tasks can be
returned to wtsk, the fact that the value of wtsk may not be correct when the
waiting task is on another node is due to restrictions on the implementation
of the connection function.  In other words, if connection function processing
is being carried out by another task (connection function processing task)
on target node, the ID of the connection function processing task will appear
as the ID of the waiting task, not the ID of the task which issued the
wai_flg system call.  If the task issuing wai_flg is on another node,
it may not be possible to access the same task using that ID even if the
correct task ID is returned by wtsk.  In other words, sometimes the value of
wtsk is meaningless even when the correct task ID is returned.

Depending on the implementation, additional information besides wtsk and
flgptn (such as eventflag attributes, flgatr) may also be referred.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (flgid was invalid or could not be used)
  E_NOEXS   Object does not exist (the eventflag specified by flgid does not
            exist)
  E_OACV    Object access violation (A flgid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_RPAR   A value outside the range supported by the requesting node and/or
            transmission packet format was returned as a parameter (a value
            outside supported range was specified for exinf, wtsk and/or
            flgptn)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from flg_sts to ref_flg.


========================================================================
|| [E] || cre_mbx || Create Mailbox
========================================================================
  cre_mbx:        Create Mailbox

[Parameters]
  ID      mbxid   MailboxID
  T_CMBX *pk_cmbx Packet to Create Mailbox
 -(pk_cmbx members)-
  VP      exinf   ExtendedInformation
  ATR     mbxatr  MailboxAttributes
  (the use of the following information is implementation dependent)
  INT     bufcnt  BufferMessageCount
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = cre_mbx ( ID mbxid, T_CMBX *pk_cmbx ) ;

[Description]

This system call creates the mailbox specified by mbxid.  Specifically, a
control block and buffer area are allocated for the mailbox to be created.

User mailboxes have positive ID numbers, while system mailboxes have
negative ID numbers.  User tasks (tasks having positive task IDs) cannot
access system mailboxes (mailboxes having negative ID numbers).  An E_OACV
error will result if a user task issues a system call on a system mailbox,
but error detection is implementation dependent.

Mailboxes having ID numbers from -4 through 0 cannot be created.  An E_ID
error will result if a value in this range is specified for mbxid.

Exinf may be used freely by the user for including extended information about
the mailbox to be created.  Information set here may be accessed by ref_mbx.
If a larger region is desired for including user information, or if the user
wishes to change the contents of this information, the usr should allocate
memory area and set the address of this memory packet to exinf.  The OS
does not take care of the contents of exinf.

The lower bits of mbxatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of mbxatr may be specified as follows.

        mbxatr := (TA_TFIFO || TA_TPRI) | (TA_MFIFO || TA_MPRI)

        TA_TFIFO    FIFO-ordered queuing of waiting tasks
        TA_TPRI     Priority-ordered queuing of waiting tasks [level X]
        TA_MFIFO    FIFO-ordered queuing of messages
        TA_MPRI     Priority-ordered queuing of messages [level X]

TA_TFIFO and TA_TPRI are used to specify the manner in which tasks receiving
messages are put on the mailbox's queue.  If TA_TFIFO is specified, tasks will
be put on the queue on a "First In, First Out" basis.  If TA_TPRI is
specified, tasks will be placed on the queue according to their priority
level.  The TA_TPRI specification is considered an extended function [level X]
for which compatibility and connectivity are not guaranteed.

Similarly, TA_MFIFO and TA_MPRI are used to specify the manner in which
messages are put on the message queue (the queue for message waiting to be
received).  If TA_MFIFO is specified, messages will be put on the message
queue on a "First In, First Out" basis.  If TA_MPRI is specified, messages
will be placed on the message queue according to their priority level.
Message priority may be specified inside the associated message packet.
The TA_MPRI specification is considered an extended function [level X]
for which compatibility is not guaranteed.

The format of mbxatr is shown in Figure 16.




   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - M P|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - M P|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - M P|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           mbxatr is 16 bits or less.
        2. P=1 specifies priority-ordered queuing of waiting tasks (TA_TPRI).
        3. M=1 specifies priority-ordered queuing of messages (TA_MPRI).

                           Figure 16 mbxatr Format

[Supplemental Information]

Although the standard packet format of pk_cmbx (the order and number of bits
associated with each member) is as stated above, it may be changed as
necessary for implementation on various systems as long as restriction
on compatibility and connectivity with other systems is not a problem.
Note that the specification of ring buffer size (bufcnt) is not necessary
when message queues are implemented as linear lists.

Bufcnt parameter is not specified by byte length, but by the number of
messages which the ring buffer can contain.

Messages received in the mailbox are written to shared memory, and only the
corresponding start address is actually sent.  It is therefore not possible
for differing nodes with no shared memory between them to use mailboxes.
Mailboxes do not support the connection function for this reason.  If messages
need to be transferred between different nodes, use messagebuffers for an
extended synchronization and communication function, rather than mailboxes.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block and/or buffer area
            cannot be allocated)
  E_ID      Invalid ID number (mbxid was invalid or could not be used)
  E_RSATR   Reserved attribute (mbxatr was invalid or could not be used)
  E_OBJ     Invalid object state (a mailbox of the same ID already exists)
  E_OACV    Object access violation (A mbxid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (pk_cmbx is invalid)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The parameter bufcnt has been provided so that buffer size may be specified
when implementing message queues using ring buffers.


========================================================================
|| [E] || del_mbx || Delete Mailbox
========================================================================
  del_mbx:        Delete Mailbox

[Parameters]
  ID      mbxid   MailboxID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = del_mbx ( ID mbxid ) ;

[Description]

This system call deletes the mailbox specified by mbxid.

Issuing this system call causes memory used for the control block and buffer
area of the associated mailbox to be released.  After this system call is
invoked, another mailbox having the same ID number can be created.

This system call will complete normally even if there are tasks waiting for
a message at the mailbox.  In that case, an E_DLT error will be returned
to each waiting task.  If there are messages still in the mailbox, they
will be deleted along with the mailbox and no error will result.

[Supplemental Information]

When a mailbox being waited for by more than one tasks is deleted, the order of
tasks on the ready queue after the WAIT state is cleared is implementation
dependent in the case of tasks having the same priority.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mbxid was invalid or could not be used)
  E_NOEXS   Object does not exist (the mailbox specified by mbxid does not
            exist)
  E_OACV    Object access violation (A mbxid less than -4 was specified from
            a user task.  This is implementation dependent.)


========================================================================
|| [S] || snd_msg || Send Message to Mailbox
========================================================================
  snd_msg:        Send Message to Mailbox

[Parameters]
  ID      mbxid   MailboxID
  T_MSG   *pk_msg Start Address of Message Packet

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = snd_msg ( ID mbxid, T_MSG *pk_msg ) ;

[Description]

This system call sends the message packet whose start address is given by
pk_msg to the mailbox specified by mbxid.  The start address (pk_msg) is
simply passed during receive without any message packet contents being copied.

If there are tasks already waiting for a message at the specified mailbox, the
task at the head of the queue will be released from waiting and the start
address of the message (pk_msg) specified with snd_msg will be transferred to
that task as one of the return parameters of rcv_msg.  If, on the other hand,
there are no tasks waiting for a message at the specified mailbox, the message
sent will be placed on that mailbox's message queue.  In neither case will the
task issuing the snd_msg call be made to wait.

With the message queue implemented as a ring buffer, the task issuing the
snd_msg call will not enter a WAIT state even if the message cannot be
queued because the ring buffer is full.  An E_QOVR error will be returned
immediately to the issuing task if this situation arises.

If cre_mbx [level E] is not implemented on the system, mailboxes are
created statically when the system is started.  Parameters required for
creating a mailbox, such as mailbox attributes (mbxatr) are also specified
statically at system startup.

[Supplemental Information]

Pk_msg is the start address of the message packet including its message
header.  Message headers may include an area reserved for use by the OS
and/or message priority information.  Users may only specify message
contents which come after the message header.

Messages sent by snd_msg are sent regardless of the state of the receiving
task.  This enables asynchronous message transfer. Only the message is tied to
a queue, not the issuing task itself.  In other words, while there is a
message queue and a receiving task queue, there is no sending task queue.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mbxid was invalid or could not be used)
  E_NOEXS   Object does not exist (the mailbox specified by mbxid does not
            exist)
  E_OACV    Object access violation (A mbxid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (the value of pk_msg cannot be used, invalid
            parameter (msgpri, etc.) in message header)
  E_QOVR    Queuing or nesting overflow (The message queue overflowed. This is
            implementation dependent.)


========================================================================
|| [S] || rcv_msg || Receive Message from Mailbox
========================================================================
|| [S] || prcv_msg || Poll and Receive Message from Mailbox
========================================================================
|| [E] || trcv_msg || Receive Message from Mailbox with Timeout
========================================================================
   rcv_msg:       Receive Message from Mailbox
  prcv_msg:       Poll and Receive Message from Mailbox
  trcv_msg:       Receive Message from Mailbox with Timeout

[Parameters (for rcv_msg and prcv_msg)]
  ID      mbxid   MailboxID

[Parameters (for trcv_msg)]
  ID      mbxid   MailboxID
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode
  T_MSG   *pk_msg Start Address of Message Packet

[C Language Interface]
  ER ercd = rcv_msg ( T_MSG **ppk_msg, ID mbxid ) ;
  ER ercd = prcv_msg ( T_MSG **ppk_msg, ID mbxid ) ;
  ER ercd = trcv_msg ( T_MSG **ppk_msg, ID mbxid, TMO tmout ) ;

[Description]

The rcv_msg system call receives a message from the mailbox specified by mbxid.
If there is no message in the specified mailbox (if the message queue is
empty), the task issuing this system call will enter the WAIT state, and be put
on the queue for waiting for arriving messages.  If the message queue of the
mailbox is not empty, the first message on the message queue will be retrieved
and returned to the issuing task as the return parameter pk_msg.

The prcv_msg system call is the same as rcv_msg without the waiting feature.
Prcv_msg polls whether or not the task should wait if rcv_msg is executed.
The meaning of parameters for prcv_msg are the same as for rcv_msg.  The
specific operations of prcv_msg are as follows.

The prcv_msg system call has the same function as rcv_msg except for the
waiting feature.  Prcv_msg polls whether or not the task should wait if
rcv_msg is executed.  The meaning of parameters to prcv_msg are the same as
for rcv_msg.  The specific operations by prcv_msg are as follows.

  - If there are messages in the specified mailbox, processing is the same as
    rcv_msg: the first message on the message queue is retrieved and the
    system call completes normally.

  - If there are no messages in the specified mailbox, an E_TMOUT error is
    returned to indicate polling failed and the system call finishes.
    Unlike rcv_msg, the issuing task does not wait in this case.  The status
    of the mailbox and the message queue remain unchanged in this case.

The trcv_msg system call has the same function as rcv_msg with an additional
timeout feature.  A maximum wait time (timeout value) can be specified using
the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT,
will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied (i.e. without
a message arriving).

Only positive values can be specified for tmout.  Although the time base for
tmout is recommended to be the same as that for the system clock (1 ms is
recommended), it may sometimes be larger than the time base of system clock
for 8 and 16-bit processors.

Specifying TMO_POL = 0 to trcv_msg for tmout indicates that a timeout value of
0 be used, resulting in exactly the same processing as prcv_msg.  Specifying
TMO_FEVR = -1 to trcv_msg for tmout indicates that an infinite timeout value
be used, resulting in exactly the same processing as rcv_msg.

[Supplemental Information]

Pk_msg is the start address of the message packet including its message header.
Message header may include an area reserved for use by the OS and/or message
priority information.  Users can specify only message contents which come
after the message header.

Prcv_msg and rcv_msg represent the same processing as specifying certain
values (TMO_POL or TMO_FEVR) to trcv_msg for tmout.  It is allowed that
only trcv_msg is implemented in the kernel and that prcv_msg and rcv_msg
are implemented as macros which call trcv_msg.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mbxid was invalid or could not be used)
  E_NOEXS   Object does not exist (the mailbox specified by mbxid does not
            exist)
  E_OACV    Object access violation (A mbxid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (tmout is -2 or less)
  E_DLT     The object being waited for was deleted (the specified mailbox was
            deleted while waiting)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout exceeded
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)

[Differences from uITRON 2.0 and ITRON2 Specifications]

Timeout function is separated to a new system call named under the form
t???_???.  It is the same with other system calls which may enter WAIT states.


========================================================================
|| [E] || ref_mbx || Reference Mailbox Status
========================================================================
  ref_mbx:        Reference Mailbox Status

[Parameters]
  ID      mbxid   MailboxID
  T_RMBX  *pk_rmbx        Packet to Reference Mailbox

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rmbx members)-
  VP      exinf   ExtendedInformation
  BOOL_ID wtsk    WaitingTaskInformation
  T_MSG   *pk_msg Start Address of Message Packet to be Received
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_mbx ( T_RMBX *pk_rmbx, ID mbxid ) ;

[Description]

This system call refers to the state of the mailbox specified by mbxid, and
returns the next message to be received (the message at the head of the
message queue), waiting task information (wtsk), and its extended information
(exinf).

Wtsk indicates whether or not there is a task waiting for the mailbox in
question.  If there is no waiting task, wtsk is returned as FALSE = 0.  If
there is a waiting task, wtsk is returned as a value other than 0.

Depending on the implementation, wtsk may be returned as the ID (non-zero) of
the task waiting for the mailbox.  If there are multiple
tasks waiting for the mailbox, the ID of the task at the head of the queue
is returned.  However, this feature is considered an extended function
[level X] for which compatibility and connectivity are not guaranteed.

An E_NOEXS error will result if the mailbox specified to ref_mbx does not
exist.

Pk_msg is the start address of the next message to be received by rcv_msg.
If there are no messages on the message queue pk_msg will be returned as
NADR = -1.  At least one of pk_msg = NADR and wtsk = FALSE is always true
in this system call.

[Supplemental Information]

Although both ref_mbx and prcv_msg can be used to find the next message
on a mailbox's message queue without causing the issuing task to wait,
ref_mbx simply reads the mailbox's next message, while prcv_msg functions
identically to rcv_msg when message is available (retrieves the message and
removes it from the message queue).

Depending on the implementation, additional information besides pk_msg and
wtsk (such as the number of messages on the message queue) may also be
referred.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mbxid was invalid or could not be used)
  E_NOEXS   Object does not exist (the mailbox specified by mbxid does not
            exist)
  E_OACV    Object access violation (A mbxid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from mbx_sts to ref_mbx.

****************************************************************************
***    3.4 Extended Synchronization and Communication Functions          ***
****************************************************************************

Extended synchronization and communication functions provide high-level
synchronization and communication functions independently from tasks.
These functions include messagebuffers and ports (rendezvous).

Messagebuffers provide both synchronization and communication by passing
messages.  Unlike mailboxes, messagebuffers allow copying and transfer of
variable length messages.  This makes it possible to pass messages even when
the sending and receiving end have no shared memory in common.  This
capability is especially useful when transferring messages between different
nodes connected over a loosely-coupled network.  Another characteristic of
messagebuffers is that the task which sends the message may enter a WAIT
state when the buffer is full.

Ports are objects used to implement what is known as a "rendezvous".  A
rendezvous is a synchronization and communication feature introduced in the
ADA language.  It is based on Communicating Sequential Processes (CSP) set
forth by Hoare.

Rendezvous use three primitives: call rendezvous, cal_por; accept rendezvous,
acp_por; and reply rendezvous, rpl_rdv.  Rendezvous function behaves in the
following way.

   1) In Figure 17, Task A and Task B are running asynchronously.  If Task A
      reaches (1) first and executes cal_por(porid), it will wait until Task B
      reaches (2).  The state of Task A during this time is called wait on
      rendezvous call.  Tskwait = TTW_CAL would be returned if ref_tsk were
      executed on Task A to find its status.  If, on the other hand, Task B
      reaches (2) first and executes acp_por(porid), it will wait until Task A
      reaches (1).  The state of Task B during this time is called wait on
      rendezvous accept.  Tskwait = TTW_ACP would be returned if ref_tsk were
      executed on Task B to find its status.

   2) A rendezvous is established when Task A has executed cal_por(porid) and
      Task B has executed acp_por(porid).  Task B will then execute (3) and (4)
      while Task A is waiting.  Task A's status during this time is called
      wait for rendezvous completion.  Tskwait = TTW_RDV would be returned if
      ref_tsk were executed on Task A to find its status.  Once (4), rpl_rdv,
      is executed, Task A will be released from waiting, and Task A and Task B
      will resume execution starting from (5) and (6), respectively.

   3) During the time represented between (3) and (4), Task A and Task B are
      guaranteed not to be running simultaneously, so that data shared between
      the tasks may be manipulated.  From the implementor's point of view,
      this has the advantage that queuing or buffering of data (messages) is
      unnecessary because both tasks are made to wait until data transfer is
      complete.




          [Task A]              [Task B]
              |                     |
              |                     |
              |            (2)      |
              |               acp_por (porid)
              |            (3)      |
     (1)      |                     |
        cal_por (porid)             |
     (5)      |                     |
              |               (4)   |
              |                  rpl_rdv
              |               (6)   |
              |                     |
              |                     |

 The WAIT state caused by (1) is called wait on rendezvous call (TTW_CAL).
 The WAIT state caused by (2) is called wait on rendezvous accept (TTW_ACP).
 The status of Task A during the time represented between (3) and (4) of
 Task B is called wait for rendezvous completion (TTW_RDV).

          Figure 17 Rendezvous Operation and Changes in Task Status


Although rendezvous can be implemented through a combination of other
synchronization and communication functions, we think that
rendezvous function can provide better efficiency than combinations of
other functions, especially when conducting communications including an
acknowledge feature or when the functions are used by servers.

[Supplemental Information]

Rendezvous function in ADA is included in language specification, while
ITRON is a specification of OS.  So, rendezvous functions and the objects of
them are, strictly speaking, different between in ADA and in ITRON
specification.

The ports of uITRON 3.0 specification are OS primitives provided in order to
implement an ADA rendezvous capability.  Rendezvous function implemented
using ports under uITRON 3.0 specification differs from ADA rendezvous in the
following ways.

  - Rendezvous function implemented using ports under uITRON 3.0 specification
    is task independent.  In other words, no task specification is given when
    calling a rendezvous using cal_por.  Only a port specification is needed.

  - With rendezvous function of uITRON 3.0 specification, a queue is sometimes
    formed for both the calling task (issuing cal_por) and accepting task
    (issuing acp_por).  In other words the port includes queues both for tasks
    in wait on rendezvous call and for those in wait on rendezvous accept.
    The calling task queue and the accepting task queue both operate according
    to FIFO; however, depending on the use of certain rendezvous conditions
    described below, the first task on the queue is not always released first
    from waiting.  When conditions are specified, FIFO rules only apply among
    tasks whose rendezvous conditions are the same.  The rendezvous function
    with the conditions is provided to implement the ADA's select function.

  - The calling task and accepting task are cut off from the port after a
    rendezvous has been established.  A port is an object used to carry out
    the processing needed until the establishment of a rendezvous.  The rest
    of the processing from the establishment of rendezvous to its completion
    is handled between the calling task and accepting task without the use of
    any ports.

  - A single port can simultaneously accomplish multiple rendezvous.  That is,
    even before rpl_rdv is executed on an established rendezvous, another task
    can execute acp_por on the same port.  This is allowed in consideration of
    the possibility of running multiple server tasks on accepting rendezvous.


========================================================================
|| [EN] || cre_mbf || Create MessageBuffer
========================================================================
  cre_mbf:        Create MessageBuffer

[Parameters]
  ID      mbfid   MessageBufferID
  T_CMBF *pk_cmbf Packet to Create MessageBuffer
 -(pk_cmbf members)-
  VP      exinf   ExtendedInformation
  ATR     mbfatr  MessageBufferAttributes
  INT     bufsz   BufferSize (in bytes)
  INT     maxmsz  MaxMessageSize (in bytes)
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = cre_mbf ( ID mbfid, T_CMBF *pk_cmbf ) ;

[Description]

Cre_mbf creates a messagebuffer having the ID number specified by mbfid.
Specifically, a control block is allocated for the messagebuffer.  A ring
buffer area is also allocated for use as a message queue (for waiting for
messages to be received) based on the value of bufsz.

Messagebuffers are objects used for managing the transfer of variable length
messages.  The main difference from a mailbox (mbx) is that variable length
message contents are copied during sending and receiving in the messagebuffer.
This means that this feature may be used for transferring messages between
nodes on a loosely-coupled network which have no shared memory.  Also, a task
which sends message may enter a WAIT state when the buffer is full.

Messagebuffers can be handled through connection function.  If the
implementation supports the connection function, mbfid is converted to
a pair of node number and object number using an object location table.
This pair is then used to access the messagebuffer on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

User messagebuffers have positive ID numbers, while system messagebuffers
have negative ID numbers.  User tasks (tasks having positive task IDs)
cannot access system messagebuffers (messagebuffers having negative ID
numbers).  An E_OACV error will result if a user task issues a system call
on a system messagebuffer, but error detection is implementation dependent.

Messagebuffers having ID numbers from -4 through 0 cannot be created.  An E_ID
error will result if a value in this range is specified for mbfid.  Of these
reserved ID values, messagebuffers having mbfid = TMBF_OS = (-4) are used as a
system (OS) error log (to record errors not reported to the task issuing the
system call in question).  Messagebuffers having mbfid = TMBF_DB = (-3) are
used for data exchange with debug support functions.  Both of these uses of
reserved ID values are considered an extended function [level X] for which
compatibility and connectivity are not guaranteed.

User tasks can not issue system calls (snd_mbf and rcv_mbf) on messagebuffers
having a messagebuffer ID of TMBF_OS or TMBF_DB.  It is implementation
dependent whether or not error checking for this is done or, if so, what error
codes are used.

Exinf may be used freely by the user for including extended information about
the messagebuffer to be created.  Information set here may be accessed by
ref_mbf.  If a larger region is desired for including user information, or if
the user wishes to change the contents of this information, the usr should
allocate memory area and set the address of this memory packet to exinf.
The OS does not take care of the contents of exinf.

The lower bits of mbfatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of mbfatr may be specified as follows.

        mbfatr := (TA_TFIFO || TA_TPRI)

        TA_TFIFO    FIFO-ordered queuing of waiting tasks
        TA_TPRI     Priority-ordered queuing of waiting tasks [level X]

Attributes TA_TFIFO and TA_TPRI are used to specify the manner in which tasks
receiving messages are put on the messagebuffer's queue.  If TA_TFIFO is
specified, tasks will be put on the queue on a "First In, First Out" basis.
If TA_TPRI is specified, tasks will be placed on the queue according to their
priority level.  The TA_TPRI specification is considered an extended function
[level X] for which compatibility and connectivity are not guaranteed.

Note that the order on the message queue is FIFO only.  If the buffer becomes
full, a task which send a message may also enter a WAIT state (send wait)
and the order of such sending tasks is FIFO only.

The format of mbfatr is shown in Figure 18.



   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - P|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                   Most Significant       Least Significant
                                   Bits                   Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - P|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - P|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           mbfatr is 16 bits or less.
        2. P=1 specifies priority-ordered queuing of waiting tasks (TA_TPRI).

                           Figure 18 mbfatr Format


[Supplemental Information]

An EN_PAR error will result if the bit length on the requesting node is larger
than that used on the target node and a value not supported by the target node
is specified for exinf, mbfatr, bufsz or maxmsz.

Although the standard packet format of pk_cmbf (the order and number of bits
associated with each member) is as stated above, it may be changed as
necessary for implementation on various systems as long as restriction
on compatibility and connectivity with other systems is not a problem.

The ring buffer used for the message queue must also contain control data to
manage each message.  As such, the ring buffer size specified by bufsz and
the total of all message sizes on the queue do not generally match.  The
latter value is usually smaller.  In this sense, the bufsz is not strictly the
size of all messages.

It is possible to create a messagebuffer of bufsz = 0.  In this case, the
sending and receiving tasks must perform completely synchronous communications.
In other words, if either of the system calls snd_mbf or rcv_mbf is executed,
the task making the call must enter the WAIT state.  When the other of these
system calls is issued, the message is transferred (copied) and both tasks
will then resume execution.

The following specific operations take place if bufsz=0 for a messagebuffer.

   1) In Figure 19, Task A and Task B are running asynchronously.  If Task A
      reaches (1) first and executes snd_mbf(mbfid), it will wait until Task B
      reaches (2).  The state of Task A during this time is called Send
      Message Wait.  Tskwait = TTW_SMBF would be returned if ref_tsk were
      executed on Task A to find its status.  If, on the other hand, Task B
      reaches (2) first and executes rcv_mbf(mbfid), it will enter Receive
      Message Wait state until Task A reaches (1).  Tskwait = TTW_MBF would be
      returned if ref_tsk were executed on Task B to find its status.

   2) The message is transferred from Task A to Task B when Task A has
      executed snd_mbf(mbfid) and Task B has executed rcv_mbf(mbfid).  Both
      tasks will then be released from waiting and resume execution.

Note that even when bufsz = 0 for a messagebuffer it is necessary for a
buffer for storing the message to be provided within the tasks in question in
order to perform connection function processing when connection function
support is being provided.  This is a consideration related to implementation
of the connection function.




          [Task A]              [Task B]
              |                     |
              |                     |
     (1)      |                     |
        snd_mbf (mbfid)             |
              |                     |
              |            (2)      |
              |               rcv_mbf (mbfid)
              |                     |
              |                     |

 The WAIT state caused by (1) is called send message wait (TTW_SMBF).
 The WAIT state caused by (2) is called receive message wait (TTW_MBF).

   Figure 19 Synchronous Communications Using a MessageBuffer of bufsz = 0


When tasks form a queue to send a message, it is implementation dependent
whether priority is given to tasks with the shorter messages to be sent or
those at the head of the queue.  For example, assume that Task A, with a
message size of 40, and Task B, with a message size of 10, are waiting to send
their messages to a messagebuffer in the order A then B, and that another task
performs a rcv_mbf, and a buffer space of 20 becomes available.  In this case,
it is implementation dependent whether or not Task B, which is not at the head
of the queue but has the smaller message size, can send a message to the
messagebuffer.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block and/or ring buffer
            cannot be allocated)
  E_ID      Invalid ID number (mbfid was invalid or could not be used)
  E_RSATR   Reserved attribute (mbfatr was invalid or could not be used)
  E_OBJ     Invalid object state (a messagebuffer of the same ID already
            exists)
  E_OACV    Object access violation (A mbfid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (pk_cmbf is invalid or bufsz and/or maxmsz is
            negative or invalid)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for exinf, mbfatr, bufsz and
            /or maxmsz)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The parameter name maxbmsz has been changed to maxmsz.

[Rationale]

The maximum message length (maxmsz) must be specified because the OS's real-
time property must be maintained during message transfer and buffer allocation
at message transfer is easy if the maximum message length is specified.
Snd_mbf will result in an E_PAR error if it attempts to send a message whose
size is greater than that specified by this parameter.

One fundamental design concept behind ITRON specification is that task-
dependent functions should be included as little as possible in order to
lighten the Task Control Block (TCB).  This is why messagebuffers are task
independent rather than task dependent.  Making messagebuffers task
independent is also better in terms of using them for logging errors.

Although mailboxes and messagebuffers are used for very similar purposes,
they are handled as separate objects due to differences in the parameters used
in their respective system calls and their internal structure.


========================================================================
|| [EN] || del_mbf || Delete MessageBuffer
========================================================================
  del_mbf:        Delete MessageBuffer

[Parameters]
  ID      mbfid   MessageBufferID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = del_mbf ( ID mbfid ) ;

[Description]

This system call deletes the messagebuffer specified by mbfid.

Messagebuffers can be handled through connection function.  If the
implementation supports the connection function, mbfid is converted to
a pair of node number and object number using an object location table.
This pair is then used to access the messagebuffer on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Issuing this system call releases memory area used for the control block of
the associated messagebuffer and the buffer area used for storing messages.
After this system call is invoked, another messagebuffer having the same ID
number can be created.

This system call will complete normally even if there are tasks waiting to
send or receive messages at the messagebuffer.  In that case, an E_DLT error
will be returned to each waiting task.  If there are messages still in the
messagebuffer, they will be deleted along with the messagebuffer and no
error will result.

[Supplemental Information]

When a messagebuffer being waited for by more than one tasks is deleted, the
order of tasks on the ready queue after the WAIT state is cleared is
implementation dependent in the case of tasks having the same priority.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mbfid was invalid or could not be used)
  E_NOEXS   Object does not exist (the messagebuffer specified by mbfid does
            not exist)
  E_OACV    Object access violation (A mbfid less than -4 was specified from
            a user task.  This is implementation dependent.)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion


========================================================================
|| [EN] || snd_mbf || Send Message to MessageBuffer
========================================================================
|| [EN] || psnd_mbf || Poll and Send Message to MessageBuffer
========================================================================
|| [EN] || tsnd_mbf || Send Message to MessageBuffer with Timeout
========================================================================
   snd_mbf:       Send Message to MessageBuffer
  psnd_mbf:       Poll and Send Message to MessageBuffer
  tsnd_mbf:       Send Message to MessageBuffer with Timeout

[Parameters (for snd_mbf and psnd_mbf)]
  ID      mbfid   MessageBufferID
  INT     msgsz   SendMessageSize (in bytes)
  VP      msg     Start Address of Send Message Packet

[Parameters (for tsnd_mbf)]
  ID      mbfid   MessageBufferID
  INT     msgsz   SendMessageSize (in bytes)
  VP      msg     Start Address of Send Message Packet
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = snd_mbf ( ID mbfid, VP msg, INT msgsz ) ;
  ER ercd = psnd_mbf ( ID mbfid, VP msg, INT msgsz ) ;
  ER ercd = tsnd_mbf ( ID mbfid, VP msg, INT msgsz, TMO tmout ) ;

[Description]

Snd_mbf sends the message stored at the address given by msg to the message
buffer specified by mbfid.  The size of the message is specified by msgsz;
that is, msgsz number of bytes beginning from msg are copied to the message
queue of the messagebuffer specified by mbfid.  The message queue is
implemented by the ring buffer.

Messagebuffers can be handled through connection function.  If the
implementation supports the connection function, mbfid is converted to
a pair of node number and object number using an object location table.
This pair is then used to access the messagebuffer on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

An E_PAR error will result if msgsz is larger than maxmsz specified with
cre_mbf.

If the available space in the buffer is not enough to include the message
given by msg into the message queue, the task issuing this system call will
wait on a send wait queue until more buffer space becomes available.
Order on the queue is FIFO.

The psnd_mbf system call has the same function as snd_mbf except for the
waiting feature.  Psnd_mbf polls whether or not the task should wait if
snd_mbf is executed.  The meaning of parameters to psnd_mbf are the same as
for snd_mbf.  The specific operations by psnd_mbf are as follows.

  - If there is enough space in the buffer, processing is the same as snd_mbf:
    the message is sent and the system call completes normally.

  - If there is not enough space in the buffer, an E_TMOUT error is returned
    to indicate polling failed and the system call finishes.  Unlike snd_mbf,
    the issuing task does not wait in this case.  The status of the
    messagebuffer and the message queue remain unchanged.

The tsnd_mbf system call has the same function as snd_mbf with an additional
timeout feature.  A maximum wait time (timeout value) can be specified using
the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT,
will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied (i.e. without
sufficient buffer space becoming available).

Only positive values can be specified for tmout.  Although the time base for
tmout is recommended to be the same as that for the system clock (1 ms is
recommended), it may sometimes be larger than the time base of system clock
for 8 and 16-bit processors.  If an object on another node is being waited
for, the time base used for the timeout is that of the requesting node,
not of the target node.

Specifying TMO_POL = 0 to tsnd_mbf for tmout indicates that a timeout value of
0 be used, resulting in exactly the same processing as psnd_mbf.  Specifying
TMO_FEVR = -1 to tsnd_mbf for tmout indicates that an infinite timeout value
be used, resulting in exactly the same processing as snd_mbf.

A message of size zero cannot be sent.  An E_PAR error will result if msgsz is
less than or equal to zero.

Psnd_mbf and tsnd_mbf(tmout=TMO_POL) may be executed from task-independent
portions and from tasks in dispatch disabled state.  This feature is an
extended function [level X] for which compatibility is not guaranteed.
Whether or not the execution of psnd_mbf is allowed is implementation
dependent.  Furthermore, even if allowed, target message
buffers are limited to those on the same node.  An EN_CTXID error will result
if a messagebuffer on another node is specified.

An E_CTX error will result if either snd_mbf or tsnd_mbf(tmout!=TMO_POL) is
executed from a task-independent portion or from a task in dispatch
disabled state.  For implementations not supporting the [level X] function
described in the previous paragraph, an E_CTX error will also result if either
psnd_mbf or tsnd_mbf(tmout=TMO_POL) is executed from a task-independent
portion or from a task in dispatch disabled state.

[Supplemental Information]

An EN_PAR error will result if the bit length used on the requesting node is
larger than that used on the target node and a value not supported by the
target node is specified for msgsz or tmout.

Psnd_mbf and snd_mbf represent the same processing as specifying certain
values (TMO_POL or TMO_FEVR) to tsnd_mbf for tmout.  It is allowed that
only tsnd_mbf is implemented in the kernel and that psnd_mbf and snd_mbf
are implemented as macros which call tsnd_mbf.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mbfid was invalid or could not be used)
  E_NOEXS   Object does not exist (the messagebuffer specified by mbfid does
            not exist)
  E_OACV    Object access violation (A mbfid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (msgsz is 0 or less; msgsz is larger than maxmsz;
            values unsuitable for msg; tmout is -2 or less)
  E_DLT     The object being waited for was deleted (the messagebuffer of
            interest was deleted while waiting)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state; implementation dependent for
            psnd_mbf and tsnd_mbf(tmout=TMO_POL))
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion (implementation-dependent; applicable to
            psnd_mbf and tsnd_mbf (tmout=TMO_POL) only)
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for msgsz and/or tmout)

[Differences from uITRON 2.0 and ITRON2 Specifications]

Tasks sending message can wait when the messagebuffer they specify is full.
This system call is named snd_mbf in uITRON 3.0 specification.  The
name of the old snd_mbf which did not allow sending tasks to wait has been
changed to psnd_mbf.  With these changes, E_QOVR error never results.

Parameter names have been changed to msg and msgsz.  Note that since messages
handled by mailboxes (snd_msg and rcv_msg) include a header, the parameter
name pk_msg is still used in those cases.


========================================================================
|| [EN] || rcv_mbf || Receive Message from MessageBuffer
========================================================================
|| [EN] || prcv_mbf || Poll and Receive Message from MessageBuffer
========================================================================
|| [EN] || trcv_mbf || Receive Message from MessageBuffer with Timeout
========================================================================
   rcv_mbf:       Receive Message from MessageBuffer
  prcv_mbf:       Poll and Receive Message from MessageBuffer
  trcv_mbf:       Receive Message from MessageBuffer with Timeout

[Parameters (for rcv_mbf and prcv_mbf)]
  ID      mbfid   MessageBufferID
  VP      msg     Start Address of Receive Message Packet

[Parameters (for trcv_mbf)]
  ID      mbfid   MessageBufferID
  VP      msg     Start Address of Receive Message Packet
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode
  INT     msgsz   ReceiveMessageSize (in bytes)

[C Language Interface]
  ER ercd = rcv_mbf ( VP msg, INT *p_msgsz, ID mbfid ) ;
  ER ercd = prcv_mbf ( VP msg, INT *p_msgsz, ID mbfid ) ;
  ER ercd = trcv_mbf ( VP msg, INT *p_msgsz, ID mbfid, TMO tmout ) ;

[Description]

Rcv_mbf receives the message from the messagebuffer specified by mbfid, and
stores it at the memory location given by msg.  In other words, the content
of the message at the head of the message queue of the messagebuffer
specified by mbfid is copied into an area which begins from msg and whose
size is msgsz.

Messagebuffers can be handled through connection function.  If the
implementation supports the connection function, mbfid is converted to
a pair of node number and object number using an object location table.
This pair is then used to access the messagebuffer on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

If the message has not yet been sent to the messagebuffer specified by mbfid
(if the message queue is empty), the task issuing this system call will wait
on a receive message wait queue until a message arrives.

The prcv_mbf system call has the same function as rcv_mbf except for the
waiting feature.  Prcv_mbf polls whether or not the task should wait if
rcv_mbf is executed.  The meaning of parameters to prcv_mbf are the same as
for rcv_mbf.  The specific operations by prcv_mbf are as follows.

  - If there is a message in the specified messagebuffer, processing is the
    same as rcv_mbf: the first message on the message queue is retrieved and
    the system call completes normally.

  - If there is no message in the specified messagebuffer, an E_TMOUT error
    is returned to indicate polling failed and the system call finishes.
    Unlike rcv_mbf, the issuing task does not wait in this case.  The
    status of the messagebuffer and the message queue remain unchanged.

The trcv_mbf system call has the same function as rcv_mbf with an additional
timeout feature.  A maximum wait time (timeout value) can be specified using
the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT,
will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied (i.e. without
a message arriving).

Only positive values can be specified for tmout.  Although the time base for
tmout is recommended to be the same as that for the system clock (1 ms is
recommended), it may sometimes be larger than the time base of system clock
for 8 and 16-bit processors.  If an object on another node is being waited
for, the time base used for the timeout is that of the requesting node,
not of the target node.

Specifying TMO_POL = 0 to trcv_mbf for tmout indicates that a timeout value of
0 be used, resulting in exactly the same processing as prcv_mbf.  Specifying
TMO_FEVR = -1 to trcv_mbf for tmout indicates that an infinite timeout value
be used, resulting in exactly the same processing as rcv_mbf.

[Supplemental Information]

An EN_PAR error will result if the bit length used on the requesting node is
larger than that used on the target node and a value not supported by the
target node is specified for tmout.

An EN_RPAR error will result if the number of bits used on the target node is
larger than that used on the requesting node, and if a value not supported by
the requesting node is returned for msgsz.

Since message contents are copied when receiving messages with rcv_mbf,
msg is a parameter, not a return parameter.

Prcv_mbf and rcv_mbf represent the same processing as specifying certain
values (TMO_POL or TMO_FEVR) to trcv_mbf for tmout.  It is allowed that
only trcv_mbf is implemented in the kernel and that prcv_mbf and rcv_mbf
are implemented as macros which call trcv_mbf.

When a message is received from a messagebuffer to which more than one tasks
are waiting to send a message, multiple tasks may be released from waiting at
the same time depending on the size of the message.  In this case the order of
messages in the messagebuffer is implementation dependent.  Likewise, the order
of tasks on the ready queue among tasks having the same priority after being
released from waiting is implementation dependent.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mbfid was invalid or could not be used)
  E_NOEXS   Object does not exist (the messagebuffer specified by mbfid does
            not exist)
  E_OACV    Object access violation (A mbfid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (values unsuitable for msg; tmout is -2 or less)
  E_DLT     The object being waited for was deleted (the specified message
            buffer was deleted while waiting)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for tmout)
  EN_RPAR   A value outside the range supported by the issuing node and/or
            transmission packet format was returned as a return parameter
            (msgsz is outside supported range for requesting node)

[Differences from uITRON 2.0 and ITRON2 Specifications]

Timeout function is separated to a new system call named under the form
t???_???.  It is the same with other system calls which may enter WAIT states.


========================================================================
|| [EN] || ref_mbf || Reference MessageBuffer Status
========================================================================
  ref_mbf:        Get MessageBuffer Status

[Parameters]
  ID      mbfid   MessageBufferID
  T_RMBF  *pk_rmbf        Packet Address to Reference MessageBuffer

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rmbf members)-
  VP      exinf   ExtendedInformation
  BOOL_ID wtsk    WaitingTaskInformation
  BOOL_ID stsk    SendingTaskInformation
  INT     msgsz   MessageSize (in bytes)
  INT     frbufsz FreeBufferSize (in bytes)
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_mbf ( T_RMBF *pk_rmbf, ID mbfid ) ;

[Description]

This system call refers to the state of the messagebuffer specified by mbfid,
and returns information of a task waiting to send a message (stsk), the size
of the next message to be received (msgsz), the free buffer size (frbufsz),
information of a task waiting to receive a message (wtsk), and its extended
information (exinf).

Messagebuffers can be handled through connection function.  If the
implementation supports the connection function, mbfid is converted to
a pair of node number and object number using an object location table.
This pair is then used to access the messagebuffer on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Even if mbfid refers to a messagebuffer on another node, messagebuffer
status information (packet contents) which are read are automatically
transferred to the requesting node from the target node.

Wtsk and stsk indicate whether or not there is a task waiting for the
messagebuffer in question.  If there is no waiting task, wtsk and stsk are
returned as FALSE = 0.  If there is a waiting task, wtsk and stsk are
returned as values other than 0.

Depending on the implementation, wtsk and stsk may be returned as the ID
(non-zero) of the task waiting for the messagebuffer.  If there are multiple
tasks waiting for the messagebuffer, the ID of the task at the head of the
queue is returned.  However, this feature is considered an extended function
[level X] for which compatibility and connectivity are not guaranteed.
Even with implementations which return the ID of waiting tasks in wtsk and
stsk, the value of wtsk and stsk may not be correct (may be non-zero but
undefined) if the waiting task is on another node.  If a system returns the
ID of a waiting task, the task ID as seen from the access environment of the
node to which the messagebuffer specified to ref_mbf belongs should be
returned.

An E_NOEXS error will result if the messagebuffer specified to ref_mbf
does not exist.

The size of the message at the head of the message queue (the next message to
be received) is returned to msgsz.  If there are no messages on the message
queue, msgsz will be returned as FALSE = 0.  A message whose size is zero
cannot be sent.

At least one of msgsz = FALSE and wtsk = FALSE is always true in this
system call.

Frbufsz indicates the amount of free memory in the ring buffer which makes up
the message queue.  This value can be used to know the total approximate size
of the messages which can be sent to the messagebuffer.

[Supplemental Information]

An EN_RPAR error will result if the number of bits used on the target node is
larger than that used on the requesting node, and if a value not supported by
the requesting node is returned for exinf, wtsk, stsk, msgsz or frbufsz.

When using the [level X] feature whereby the ID of waiting tasks can be
returned to wtsk, the fact that the value of wtsk may not be correct when the
waiting task is on another node is due to restrictions on the implementation
of the connection function.  In other words, if connection function processing
is being carried out by another task (connection function processing task)
on target node, the ID of the connection function processing task will appear
as the ID of the waiting task, not the ID of the task which issued the
rcv_mbf system call.  If the task issuing rcv_mbf is on another node,
it may not be possible to access the same task using that ID even if the
correct task ID is returned by wtsk.  In other words, sometimes the value of
wtsk is meaningless even when the correct task ID is returned.

The same is true for stsk.

Depending on the implementation, additional information besides wtsk, stsk,
msgsz and frbufsz (such as the maximum message size, maxmsz) may also be
referred.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mbfid was invalid or could not be used)
  E_NOEXS   Object does not exist (the messagebuffer specified by mbfid does
            not exist)
  E_OACV    Object access violation (A mbfid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_RPAR   A value outside the range supported by the issuing node and/or
            transmission packet format was returned as a return parameter (a
            value outside supported range for exinf, wtsk, stsk, msgsz and/or
            frbufsz on a requesting node)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from mbf_sts to ref_mbf.

[Rationale]

ref_mbf returns information about the size of the next message, but not
information regarding its contents.  This is for the following reasons.

  - Even if the start address for the message inside the ring buffer is
    returned, it cannot be read without knowledge of the structure
    (implementation dependent) of the ring buffer.

  - The overhead for copying message contents as rcv_mbf does is rather large,
    and such a specification does not meet the intended purpose of ref_mbf.


========================================================================
|| [EN] || cre_por || Create Port for Rendezvous
========================================================================
  cre_por:        Create Port for Rendezvous

[Parameters]
  ID      porid   Port ID for Rendezvous
  T_CPOR *pk_cpor Packet to Create Port for Rendezvous
 -(pk_cpor members)-
  VP      exinf   ExtendedInformation
  ATR     poratr  PortAttributes
  INT     maxcmsz MaximumCallMessageSize (in bytes)
  INT     maxrmsz MaximumReplyMessageSize (in bytes)
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = cre_por ( ID porid, T_CPOR *pk_cpor ) ;

[Description]

Cre_por creates a port for rendezvous having the ID number specified by porid.
Specifically, a control block is allocated for the port created.  Ports are
primitives (objects) used to implement rendezvous functions.

Ports can be handled through connection function.  If the
implementation supports the connection function, porid is converted to
a pair of node number and object number using an object location table.
This pair is then used to access the port on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

User ports have positive ID numbers, while system ports
have negative ID numbers.  User tasks (tasks having positive task IDs)
cannot access system ports (ports having negative ID
numbers).  An E_OACV error will result if a user task issues a system call
on a system port, but error detection is implementation dependent.

Ports having ID numbers from -4 through 0 cannot be created.  An E_ID error
will result if a value in this range is specified for porid.

Exinf may be used freely by the user for including extended information about
the port to be created.  Information set here may be accessed by ref_por.
If a larger region is desired for including user information, or if the user
wishes to change the contents of this information, the usr should allocate
memory area and set the address of this memory packet to exinf.  The OS
does not take care of the contents of exinf.

The lower bits of poratr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute bits of
poratr are currently all reserved and must be filled with TA_NULL = 0.

The format of poratr is shown in Figure 20.



   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - -|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - -|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - -|
                                                      +-+-+-+-+-+-+-+-+

 Note: There is no clear distinction between system attributes and
       implementation-dependent attributes when the bit length of
       poratr is 16 bits or less.

                           Figure 20 poratr Format


[Supplemental Information]

An EN_PAR error will result if the bit length used on the requesting node is
larger than that used on the target node and a value not supported by the
target node is specified for exinf, poratr, maxcmsz or maxrmsz.

Although the standard packet format of pk_cpor (the order and number of bits
associated with each member) is as stated above, it may be changed as
necessary for implementation on various systems as long as restriction
on compatibility and connectivity with other systems is not a problem.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block cannot be allocated)
  E_ID      Invalid ID number (porid was invalid or could not be used)
  E_RSATR   Reserved attribute (poratr was invalid or could not be used)
  E_OBJ     Invalid object state (a port of the same ID already exists)
  E_OACV    Object access violation (A porid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (pk_cpor is invalid or maxcmsz and/or maxrmsz is
            negative or invalid)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for exinf, poratr, maxcmsz
            and/or maxrmsz)

[Rationale]

The reason ports are made task independent is that task-dependent functions
are avoided as much as possible under ITRON specification.


========================================================================
|| [EN] || del_por || Delete Port for Rendezvous
========================================================================
  del_por:        Delete Port for Rendezvous

[Parameters]
  ID      porid   PortID for Rendezvous

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = del_por ( ID porid ) ;

[Description]

This system call deletes the port for rendezvous specified by porid.

Ports can be handled through connection function.  If the
implementation supports the connection function, porid is converted to
a pair of node number and object number using an object location table.
This pair is then used to access the port on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Issuing this system call causes memory used for the control block of the
associated port to be released.  After this system call is invoked,
another port having the same ID number can be created.

This system call will complete normally even if there are tasks waiting to
accept rendezvous (acp_por) or call rendezvous (cal_por) at the port.
In that case, an E_DLT error will be returned to each waiting task.

Deleting a port using del_por has no effect on tasks for which rendezvous has
already been established.  In this case, nothing is reported to the task
accepting the rendezvous (not in WAIT state), and the state of the task
calling for the rendezvous (in wait for rendezvous completion state) remains
unchanged.  When the task accepting the rendezvous issues rpl_rdv, rpl_rdv
will execute normally even if the port used for establishing the rendezvous
has already been deleted.

[Supplemental Information]

When a port being waited for by more than one tasks is deleted, the order of
tasks on the ready queue after the WAIT state is cleared is implementation
dependent in the case of tasks having the same priority.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (porid was invalid or could not be used)
  E_NOEXS   Object does not exist (the port specified by porid does not exist)
  E_OACV    Object access violation (A porid less than -4 was specified from
            a user task.  This is implementation dependent.)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion

[Differences from uITRON 2.0 and ITRON2 Specifications]

Now, del_por after a rendezvous has been established must not affect tasks
during their rendezvous.  This is due to the strategy that tasks should not be
related to any port once a rendezvous has been established for them.


========================================================================
|| [EN] || cal_por || Call Port for Rendezvous
========================================================================
|| [EN] || pcal_por || Poll and Call Port for Rendezvous
========================================================================
|| [EN] || tcal_por || Call Port for Rendezvous with Timeout
========================================================================
   cal_por:       Call Port for Rendezvous
  pcal_por:       Poll and Call Port for Rendezvous
  tcal_por:       Call Port for Rendezvous with Timeout

[Parameters (for cal_por and pcal_por)]
  ID      porid   PortID
  UINT    calptn  Call Bit Pattern Representing Rendezvous Conditions
  VP      msg     Start Address for a Packet of Message
  INT     cmsgsz  CallMessageSize (in bytes)

[Parameters (for tcal_por)]
  ID      porid   PortID
  UINT    calptn  Call Bit Pattern Representing Rendezvous Conditions
  VP      msg     Start Address for a Packet of Message
  INT     cmsgsz  CallMessageSize (in bytes)
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode
  INT     rmsgsz  ReplyMessageSize (in bytes)

[C Language Interface]
  ER ercd =  cal_por ( VP msg, INT *p_rmsgsz, ID porid, UINT calptn, INT
                       cmsgsz ) ;
  ER ercd = pcal_por ( VP msg, INT *p_rmsgsz, ID porid, UINT calptn, INT
                       cmsgsz ) ;
  ER ercd = tcal_por ( VP msg, INT *p_rmsgsz, ID porid, UINT calptn, INT
                       cmsgsz, TMO tmout ) ;

[Description]

These system calls call the specified port for a rendezvous.

Ports can be handled through connection function.  If the
implementation supports the connection function, porid is converted to
a pair of node number and object number using an object location table.
This pair is then used to access the port on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

The specific operation of cal_por is as follows.  A rendezvous is established
if there is a task waiting to accept a rendezvous at the port specified by
porid and if rendezvous conditions between that task and the task issuing this
call are satisfied.  In this case, the task waiting to accept the rendezvous
enters the RUN/READY state while the task issuing cal_por enters the wait for
rendezvous completion state.  The task in wait for rendezvous completion state
is released from waiting when the task it is rendezvousing with executes
rpl_rdv.  The cal_por system call finishes at this time.

If there is no task waiting to accept a rendezvous at the port specified by
porid, or if there is a task but conditions for establishing a rendezvous are
not satisfied, the task issuing cal_por will be placed at the end of the call
wait queue of the port in question and enter wait on rendezvous call state.

Conditions for establishing a rendezvous depend on whether or not the logical
product of the acpptn of the accepting task and the calptn of the calling task
is zero.  A rendezvous is established, if the logical product is not zero.
An E_PAR parameter error will result if calptn is zero because rendezvous
conditions can never be satisfied.

When a rendezvous is established, the calling task can send a message (a call
message) to the accepting task.  The size of the call message is given by
cmsgsz.  Specifically, a cmsgsz number of bytes beginning at the address given
by msg as specified by cal_por on the calling task are copied to the address
given by msg as specified by acp_por on the accepting task.

When the rendezvous completes, the accepting task may send a message (reply
message) to the calling task.  Specifically, contents of a reply message
specified by rpl_rdv on the accepting task are copied to the address given by
msg as specified by cal_por on the calling task.  The size of the reply
message rmsgsz is returned to cal_por.  In the end, the original contents of
the message area specified by msg for cal_por are destroyed by the reply
message received upon the execution of rpl_rdv.

Note that there is the possibility that message contents will be destroyed
when a rendezvous is forwarded since the area as much as maxrmsz beyond the
address msg as specified by cal_por is used as a buffer.  It is therefore
necessary to reserve an area of memory of at least maxrmsz beyond msg,
regardless of the anticipated size of the reply message, whenever there is any
possibility that a rendezvous requested by cal_por might be forwarded.  (For
details, see the section for fwd_por.)

An E_PAR error will result if cmsgsz is larger than the maxcmsz specified by
cre_por.  Note also that a message of size zero cannot be sent.  An E_PAR
error will result if cmsgsz is less than or equal to zero.  This error is
checked for before the calling task enters wait on rendezvous call state.  If
the error occurs, the task issuing cal_por will not enter wait on rendezvous
call.

The pcal_por system call has the same function as cal_por except for the
waiting feature.  Pcal_por polls whether or not the task should wait if
cal_por is executed.  The meaning of parameters to pcal_por are the same as
for cal_por.  The specific operations by pcal_por are as follows.

  - If there is a task waiting to accept a rendezvous at the specified port
    and conditions for establishing a rendezvous are satisfied, processing
    is the same as cal_por: a rendezvous is established and the task issuing
    this system call enters WAIT state for rendezvous completion.

  - If there is no task waiting to accept a rendezvous at the specified port
    or conditions for establishing a rendezvous are not satisfied, an E_TMOUT
    error is returned to indicate polling failed and the system call
    finishes.  Unlike cal_por, the issuing task does not wait in this case.
    The status of the port and associated queues remain unchanged.

The tcal_por system call has the same function as cal_por with an additional
timeout feature.  A maximum wait time (timeout value) can be specified using
the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT,
will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied (i.e. without
a rendezvous being established).

Only positive values can be specified for tmout.  Although the time base for
tmout is recommended to be the same as that for the system clock (1 ms is
recommended), it may sometimes be larger than the time base of system clock
for 8 and 16-bit processors.  If an object on another node is being waited
for, the time base used for the timeout is that of the requesting node,
not of the target node.

Specifying TMO_POL = 0 to tcal_por for tmout indicates that a timeout value of
0 be used, resulting in exactly the same processing as pcal_por.  Specifying
TMO_FEVR = -1 to tcal_por for tmout indicates that an infinite timeout value
be used, resulting in exactly the same processing as cal_por.

The tmout specification represents the amount of timeout to wait for a
rendezvous to be established, and has nothing to do with the time between the
establishment and completion of rendezvous.

Cal_por can support the connection function, thus allowing it to specify ports
on other nodes.  If cal_por specifies a port on another node however, it
becomes impossible to distinguish between wait on rendezvous call state and
wait for rendezvous completion state.  The task status of a task issuing
cal_por on a port on another node is therefore known as CALL OR wait for
rendezvous completion (indeterminate) state.  If ref_tsk is issued to a target
task, (TTW_CAL | TTW_RDV) will be returned as the value of tskwait to indicate
that the task is in indeterminate state either in wait on rendezvous call or
wait for rendezvous completion.  The value returned to ref_tsk in tskwait will
not change even if the rendezvous is later established or if it is
unestablished due to forwarding.

[Supplemental Information]

An EN_PAR error will result if the number of bits used on the requesting node
is larger than that used on the target node and a value not supported by the
target node is specified for calptn, cmsgsz or tmout.

An EN_RPAR error will result if the number of bits used on the target node is
larger than that used on the requesting node, and if a value not supported by
the requesting node is returned for rmsgsz.

It is possible to distinguish wait on rendezvous call state from wait for
rendezvous completion state even when cal_por specifies a port on another node
by changing the communications protocol to increase the number of packet
transfers.  Although the standard communications protocol of uITRON 3.0
specification does not support this, such an implementation-dependent
extension is permitted, so it is necessary to be careful when comparing values
returned in tskwait.  In other words, rather than checking whether or not
tskwait is equal to (TTW_CAL | TTW_RDV) you should write a program to check
the logical product of tskwait and (TTW_CAL | TTW_RDV), or incorrect result
may be introduced when using an OS which can distinguish between wait on
rendezvous call state and wait for rendezvous completion state.  The same
care must be taken when a port on another node may have been moved onto the
local node.

Pcal_por and cal_por represent the same processing as specifying certain
values (TMO_POL or TMO_FEVR) to tcal_por for tmout.  It is allowed that
only tcal_por is implemented in the kernel and that pcal_por and cal_por
are implemented as macros which call tcal_por.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (porid was invalid or could not be used)
  E_NOEXS   Object does not exist (the port specified by porid does not exist)
  E_OACV    Object access violation (A porid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (cmsgsz is 0 or less; cmsgsz is larger than
            maxcmsz; calptn=0; values unapplicable to msg; tmout is -2 or less)
  E_DLT     The object being waited for was deleted (the specified port was
            deleted while waiting)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for calptn, cmsgsz and/or
            tmout)
  EN_RPAR   A value outside the range supported by the requesting node and/or
            transmission packet format was returned as a return parameter
            (rmsgsz is outside supported range for requesting node)

[Differences from uITRON 2.0 and ITRON2 Specifications]

Timeout function is separated to a new system call named under the form
t???_???.  It is the same with other system calls which may enter WAIT states.

The message transfer interface has been made the same as that used with
messagebuffers.  Specific changes are as follows.

  - Instead of specifying a maximum message size for each cal_por or acp_por
    system call to establish rendezvous, it is specified for each port when
    it is created by cre_por, not for each message or rendezvous.

  - No rendezvous is established if an attempt is made to send a message
    larger than the maximum size specified by cre_por.  Also, the resulting
    error is reported to the message sender, not to the receiver.  The
    E_AROVR error was therefore abolished.

  - Message size is no longer specified in the first four bytes of a message,
    but rather using a separate parameter and return parameter.

[Rationale]

Cal_por for a port on another node cannot make out the difference between wait
on rendezvous call state and wait for rendezvous completion state because
transmission packet for reporting such a change in task status has been
eliminated.  It was considered best to avoid the transfer of unnecessary
packets as much as possible in order to take the greatest possible advantage
of implementing a complex feature such as a rendezvous feature.  If you need
to know when a task status changes from wait on rendezvous call to wait for
rendezvous completion state, special packets are needed just for rendezvous
acceptance and forwarding.

When an application requires exact task status, it is probably best to use a
combination of messagebuffers rather than rendezvous.


========================================================================
|| [E] || acp_por || Accept Port for Rendezvous
========================================================================
|| [E] || pacp_por || Poll and Accept Port for Rendezvous
========================================================================
|| [E] || tacp_por || Accept Port for Rendezvous with Timeout
========================================================================
   acp_por:       Accept Port for Rendezvous
  pacp_por:       Poll and Accept Port for Rendezvous
  tacp_por:       Accept Port for Rendezvous with Timeout

[Parameters (for acp_por and pacp_por)]
  ID      porid   PortID
  UINT    acpptn  Accept Bit Pattern Representing Rendezvous Conditions
  VP      msg     Start Address of Call Message Packet

[Parameters (for tacp_por)]
  ID      porid   PortID
  UINT    acpptn  Accept Bit Pattern Representing Rendezvous Conditions
  VP      msg     Start Address of Call Message Packet
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode
  RNO     rdvno   RendezvousNumber
  INT     cmsgsz  CallMessageSize (in bytes)

[C Language Interface]
  ER ercd =  acp_por ( RNO *p_rdvno, VP msg, INT *p_cmsgsz, ID porid, UINT
                       acpptn ) ;
  ER ercd = pacp_por ( RNO *p_rdvno, VP msg, INT *p_cmsgsz, ID porid, UINT
                       acpptn ) ;
  ER ercd = tacp_por ( RNO *p_rdvno, VP msg, INT *p_cmsgsz, ID porid, UINT
                       acpptn, TMO tmout ) ;

[Description]

These system calls accept the specified port for a rendezvous.

The specific operation of acp_por is as follows.  A rendezvous is established
if there is a task waiting to call a rendezvous at the port specified by porid
and if rendezvous conditions between that task and the task issuing this call
are satisfied.  In this case, the task waiting to call the rendezvous is
removed from the queue and the changes from wait on rendezvous call state to
wait for rendezvous completion state take place.  The task issuing acp_por
continues execution.

If there is no task waiting to call a rendezvous at the port specified by
porid, or if there is a task but conditions for establishing a rendezvous are
not satisfied, the task issuing acp_por will enter wait on rendezvous accept
state for the port in question.  No error results if there is already another
task in wait on rendezvous accept state at this time; the task issuing acp_por
is simply placed on the accept rendezvous queue.  Under uITRON 3.0
specification, it is possible for a single port to simultaneously handle
multiple rendezvous.  Accordingly, no error results even if the next
rendezvous is carried out while another task is still conducting a rendezvous
(before an rpl_rdv call related to this rendezvous is made) at the port
specified by porid.

Conditions for establishing a rendezvous depend on the logical product of the
acpptn of the accepting task and the calptn of the calling task.  A rendezvous
is established if the logical product is not 0.  If the first task does not
satisfy these conditions, each subsequent task on the call wait queue is
checked in order.  If calptn and acpptn are specified as the same non-zero
value, it is assumed there are no rendezvous conditions (i.e., unconditional).
An E_PAR parameter error will result if acpptn is zero because rendezvous
conditions can never be satisfied in this case.  All processing before a
rendezvous has been established is completely a mirror image on calling and
accepting rendezvous.

When a rendezvous is established, the calling task can send a message (a call
message) to the accepting task.  Contents of the call message are copied into
the memory area beginning at the address given by msg as specified by the
accepting task to acp_por.  The size of call message, cmsgsz will be the
return parameter of acp_por.

A task accepting rendezvous can establish more than one rendezvous at a time.
Specifically, a task which has accepted one rendezvous using acp_por may
execute acp_por again before executing rpl_rdv on the first rendezvous.  The
port specified to the second acp_por call at this time may be the same port as
the first rendezvous or a different one.  Although it represents a special
case, a task already conducting a rendezvous at a given port may even execute
acp_por again on the same port and conduct multiple rendezvous on the same port
at the same time.  Of course, the calling tasks being rendezvoused with will
differ.

The return parameter rdvno returned to acp_por represents data used to
distinguish different rendezvous when more than one has been established at a
given time.  This return parameter is used by rpl_rdv when a rendezvous
completes.  It is also used as a parameter to fwd_por when forwarding a
rendezvous.  Although the exact contents of rdvno are implementation dependent,
it is expected to include information specifying the calling task on the other
end of the rendezvous.

The pacp_por system call has the same function as acp_por except for the
waiting feature.  Pacp_por polls whether or not the task should wait if
acp_por is executed.  The meaning of parameters to pacp_por are the same as
for acp_por.  The specific operations by pacp_por are as follows.

  - If there is a task waiting to call a rendezvous at the specified port and
    conditions for establishing a rendezvous are satisfied, processing is
    the same as acp_por: a rendezvous is established and the system call
    completes normally.

  - If there is no task waiting to call a rendezvous at the specified port or
    conditions for establishing a rendezvous are not satisfied, an E_TMOUT
    error is returned to indicate polling failed and the system call
    finishes.  Unlike acp_por, the issuing task does not wait in this case.
    The status of the port and associated queues remain unchanged in this
    case.

The tacp_por system call has the same function as acp_por with an additional
timeout feature.  A maximum wait time (timeout value) can be specified using
the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT,
will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied (i.e. without
a rendezvous being established).

Only positive values can be specified for tmout.  Although the time base for
tmout is recommended to be the same as that for the system clock (1 ms is
recommended), it may sometimes be larger than the time base of system clock
for 8 and 16-bit processors.  If an object on another node is being waited
for, the time base used for the timeout is that of the requesting node,
not of the target node.

Specifying TMO_POL = 0 to tacp_por for tmout indicates that a timeout value of
0 be used, resulting in exactly the same processing as pacp_por.  Specifying
TMO_FEVR = -1 to tacp_por for tmout indicates that an infinite timeout value
be used, resulting in exactly the same processing as acp_por.

Acp_por does not support the connection function.  As such, acp_por cannot be
used for a port on another node.  Tasks accepting rendezvous must use ports on
the same node.  An EN_NOSPT error will result if porid is specified as a port
on another node.

[Supplemental Information]

The function to make a queue for tasks accepting rendezvous is very useful
when concurrently running multiple servers performing the same processing.
This capability also takes maximum advantage of the fact ports are task
independent.

If a task accepting a rendezvous terminates abnormally for some reason before
completing its rendezvous (before issuing rpl_rdv), the task calling for the
rendezvous by issuing cal_por will remain frozen in wait for rendezvous
completion without being released.  To avoid this type of situation, tasks
accepting rendezvous should execute a rpl_rdv or rel_wai call when they
terminate abnormally, as well as notify the task calling for the rendezvous
that the rendezvous ended in an error.

Rdvno includes information which specifies the calling task on the other end
of the rendezvous to be established; the  numbers to be assigned must be
unique as much as possible.  Even for rendezvous between the same tasks, the
first rendezvous and the second must be assigned different rdvno values.
Doing so avoids the following problems.

Suppose that a task which issued cal_por and is now in wait for rendezvous
completion is forcibly released from waiting by rel_wai or ter_tsk plus sta_tsk
and has again executed cal_por to establish rendezvous.  If the rdvno value
assigned to the first rendezvous is the same as that assigned to the second,
rpl_rdv issued to the first rendezvous may complete the second rendezvous.  It
is possible to detect the rpl_rdv error on the first rendezvous, if unique
rdvno values are assigned and a record is kept of the rdvno value expected by
the task in wait for rendezvous completion state.

One possible implementation of assigning rdvno values is using the ID of the
calling task (if cal_por was issued on a remote node, the task number or ID of
the connection function processing task may be used) in the low order bytes of
rdvno and a sequential number in the high order bytes.

Pacp_por and acp_por represent the same processing as specifying certain
values (TMO_POL or TMO_FEVR) to tacp_por for tmout.  It is allowed that
only tacp_por is implemented in the kernel and that pacp_por and acp_por
are implemented as macros which call tacp_por.

Using calptn and acpptn to establish rendezvous allows you to implement a
rendezvous selection feature (corresponding to ADA's select).  An example of
an ADA select statement is shown in Figure 21(a), while a corresponding
implementation example with ITRON specification OS is shown in Figure 21(b).

Although the ADA's selection feature is only provided for tasks accepting
rendezvous, it is possible to provide tasks calling for rendezvous with a
selection feature by specifying multiple bits for calptn under ITRON
specification.


         +---------------------------------------------+
         |     select                                  |
         |         when condition_A                    |
         |              accept entry_A do ... end;     |
         |     or                                      |
         |         when condition_B                    |
         |              accept entry_B do ... end;     |
         |     or                                      |
         |         when condition_C                    |
         |              accept entry_C do ... end;     |
         |     end select;                             |
         +---------------------------------------------+

          Figure 21(a) ADA Program Sample Using the select Statement


 +---------------------------------------------------------------------+
 | - Entry_A, entry_B and entry_C do not correspond to separate ports, |
 |   but the entire select statement corresponds to a single port.     |
 | - Entry_A, entry_B and entry_C correspond to bits 2^0, 2^1 and 2^2  |
 |   of calptn and acpptn.                                             |
 | - A select statement in a real sample of ADA code looks like this:  |
 |                ptn := 0;                                            |
 |                if condition_A then ptn := ptn + 2^0 endif;          |
 |                if condition_B then ptn := ptn + 2^1 endif;          |
 |                if condition_C then ptn := ptn + 2^2 endif;          |
 |                acp_por (acpptn := ptn);                             |
 | - If entry_A was simply accepted in the sample ADA source code with |
 |   no select statement, in ITRON specification OS, one would just    |
 |   execute:                                                          |
 |                acp_por(acpptn := 2^0);                              |
 |   If one wanted to wait unconditionally for entry_A, entry_B or     |
 |   entry_C being ORed one would execute:                             |
 |                acp_por(acpptn := 2^2 + 2^1 + 2^0);                  |
 | - On the other hand, the task calling for the rendezvous at entry_A |
 |   would execute:                                                    |
 |                cal_por(calptn := 2^0);                              |
 |   For calling entry_C:                                              |
 |                cal_por(calptn := 2^2);                              |
 +---------------------------------------------------------------------+

     Figure 21(b) Implementing the ADA select Feature
                  Using the Rendezvous Function of ITRON Specification


[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (porid was invalid or could not be used or porid
            represents a port on another node)
  E_NOEXS   Object does not exist (the port specified by porid does not exist)
  E_OACV    Object access violation (A porid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (acpptn = 0; values not applicable to msg; or
            tmout is -2 or less)
  E_DLT     The object being waited for was deleted (the specified port was
            deleted while waiting)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)
  EN_NOSPT  No support for the connection function

[Differences from uITRON 2.0 and ITRON2 Specifications]

Timeout function is separated to a new system call named under the form
t???_???.  It is the same with other system calls which may enter WAIT states.

The rdvno is a return parameter corresponding to ctskid under ITRON2
specification; its exact contents are implementation dependent.

[Rationale]

Regardless of the fact that conditions for establishing a rendezvous are
exactly the mirror image on the calling and accepting ports, the reason
cal_por and acp_por are provided as separate system calls is that the
processing required after a rendezvous is established differs for the two
types of tasks.  Specifically, while the calling task enters WAIT state
after the rendezvous is established, the accepting task enters RUN/READY
state.

The reason acp_por and fwd_por do not support the connection function is that
in any attempt to implement this function the special transmission packets
become necessary, thus making internode communication very complicated.
Implementation-dependent specifications may allow acp_por and fwd_por to
support the connection function as long as the compatibility and
connectivity with other systems is not a problem.


========================================================================
|| [E] || fwd_por || Forward Rendezvous to Other Port
========================================================================
  fwd_por:        Forward Rendezvous to Other Port

[Parameters]
  ID      porid   Port ID to be Forwarded to
  UINT    calptn  Call Bit Pattern Representing Rendezvous Conditions
  RNO     rdvno   Rendezvous Number before Forwarding
  VP      msg     Start Address of Call Message Packet
  INT     cmsgsz  CallMessageSize (in bytes)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = fwd_por ( ID porid, UINT calptn, RNO rdvno, VP msg, INT cmsgsz ) ;

[Description]

This system call forwards an accepted rendezvous to another port.

The task issuing this system call (Task X) must be currently in a rendezvous
(must have already executed acp_por).  The calling task being rendezvoused
with (Task Y) is represented by a rendezvous number returned in the return
parameter rdvno.  When fwd_por is executed in this situation, the rendezvous
between Task X and Task Y is released and all processing thereafter is the
same as if Task Y called for a rendezvous on the port (Port B) specified to
this call as porid.

The specific operations of fwd_por are as follows.

   1. The rendezvous specified by rdvno is released.

   2. Task Y enters wait on rendezvous call for the port given by porid.  The
      bit pattern given by calptn as specified with fwd_por by Task X, not
      with cal_por by Task Y, represents the selection conditions necessary to
      establish a rendezvous for Task Y.  Seen from Task Y, the wait for
      rendezvous completion state returns to the wait on rendezvous call state.

   3. After this, a rendezvous is established between Task Y and an accepting
      task, if a rendezvous at the port given by porid has been accepted.  In
      some cases execution of fwd_por will immediately establish a rendezvous
      if there is a task already waiting to accept a rendezvous on port given
      by porid and if conditions for establishing a rendezvous have been
      satisfied.

      Just as with the calptn parameter, the message sent to the accepting
      task when the rendezvous is established is that specified with fwd_por
      by Task X, not that specified with cal_por by Task Y.

   4. After the new rendezvous has completed, the reply message returned to
      the calling task by rpl_rdv is copied into the area specified for msg by
      Task Y to cal_por, not the area specified for msg by Task X to fwd_por.

Basically,

        executing:
                cal_por(porid=portA, calptn=ptnA, msg=mesA)
        followed by:
                fwd_por(porid=portB, calptn=ptnB, msg=mesB)

is exactly the same as executing:

        cal_por(porid=portB, calptn=ptnB, msg=mesB).

It is not necessary to log the history of rendezvous forwarding.

If ref_tsk is executed on the task which has been returned to wait on
rendezvous call state by fwd_por system call, tskwait will be returned as
TTW_CAL.  The return value of wid will represent the ID number of the port
forwarded to.

The execution of the fwd_por call finishes immediately.  This system call
never results in waiting.  Furthermore, a task issuing fwd_por loses any
relationship to the port on which the forwarded rendezvous was established,
the port forwarded to (the port given by porid), and any tasks conducting
rendezvous on these ports.

An E_PAR error results if cmsgsz is larger than maxcmsz specified for the port
forwarded to.  A message of size zero cannot be sent.  An E_PAR error will
result if cmsgsz is less than or equal to zero.  This error is checked for
before the rendezvous is forwarded.  If the error occurs, the rendezvous will
not be forwarded and the rendezvous given by rdvno will not be released.

The send message specified by fwd_por is copied into another memory area (such
as message area specified by cal_por) when fwd_por is executed.  Accordingly,
even if the contents of the message area specified by msg to fwd_por are
changed before the forwarded rendezvous is established, the forwarded
rendezvous will not be affected.

When forwarding a rendezvous with fwd_por, the maxrmsz of the port being
forwarded to (the port given by porid) must be less than or equal to the
maxrmsz of the port on which the rendezvous prior to forwarding was
established.  An E_OBJ error indicating that an invalid forwarding port was
specified will result if the maxrmsz of the port being forwarded to is larger
than that of the original port.  The task calling for the rendezvous prepares a
reply message receiving area based on the maxrmsz of the port before
forwarding.  So, if the maximum size for the reply message increases with the
rendezvous being forwarded, chances are that unexpectedly large reply messages
are returned to the calling port.  This causes a problem.  This is why a
rendezvous cannot be forwarded to a port having a larger maxrmsz.

The message size, cmsgsz, sent with fwd_por must also be less than or equal to
the maxrmsz of the port on which the prior-to-forward rendezvous was
established.  This is because it is assumed that the message area specified by
cal_por will be used as a buffer in implementing fwd_por.  An E_PAR error will
result if cmsgsz is larger than maxrmsz of the port before forwarding.  (For
details, see [Supplemental Information].)

It is unnecessary to execute fwd_por or rpl_rdv from task-independent
portions, but it is possible to issue fwd_por or rpl_rdv from tasks in
dispatch disabled or interrupt disabled state.  This feature can be used
when processing indivisibly to fwd_por or rpl_rdv is required.  Error
checking when fwd_por or rpl_rdv are executed from task-independent portions
is implementation dependent.

When Task Y returns from wait for rendezvous completion state back to wait on
rendezvous call state by fwd_por, the timeout for establishing the next
rendezvous is always forever (TMO_FEVR).  This is true even if Task Y
specified a timeout using tcal_por or made the call for a rendezvous using
pcal_por.

The port being forwarded to may be the same port used for the previous
rendezvous (the port on which the rendezvous for rdvno was established).
In this case, fwd_por cancels the rendezvous which was established
previously.  However, even in this case, the call message and calptn
parameters are changed into those specified with fwd_por by the accepting
task, not those specified with cal_por by the calling task.

It is possible to forward a rendezvous which has already been forwarded.

Fwd_por does not support the connection function.  As such, a port on another
node may not be specified to fwd_por.  Ports to which rendezvous are forwarded
must exist on the same node.  An EN_NOSPT error will result if porid is
specified as a port on another node.

[Supplemental Information]

Figure 22 represents the operation of a server task which uses fwd_por.




Requesting
 task x        Extended SVC
    |                                  +----------------------------<------+
    |      +--------+                  |                                   |
    |      |        |     +------+     |     Server Distribution Tasks     |
    |      |        |     |SVC   |     v                                   |
 ???_??? --+     cal_por -|Accept|- acp_por                                |
                    :     |Port  |     |                                   |
    +------+        :     +------+     |                                   |
    |      |        :                  | Preprocessing                     |
    |      |        :                  +----+  --------+  --------+  --... |
    |      |        :                       |          |          |        |
    v      |        :                       v          v          v        |
           |        :                    fwd_por    fwd_por    fwd_por -->-+
           |        :                       |          |          |
           |        :                 ++=========++=========++=========++===
           |        :                 ||Process A||Process B||Process C||
           |        :                 ||Server   ||Server   ||Server   ||...
           | (wait on rendezvous      ||Port     ||Port     ||Port     ||
           |  call or wait for        ++=========++=========++=========++===
           |  rendezvous completion)        |          |          |
           |        :                   acp_por     acp_por     acp_por
           |        :                    |   |       |   |       |   |
           |        :               +----+   |  +----+   |  +----+   |
           |        :               |        |  |        |  |        |
           |        :               ^        v  ^        v  ^        v
           |        :               | Process A | Process B | Process C
           |        :               | Server    | Server    | Server
           |        :               | Task      | Task      | Task
           |        :               |        |  |        |  |        |
           |        :               |        v  |        v  |        v
           |        :               +----+   |  +----+   |  +----+   |
           |        :                    |   |       |   |       |   |
           |        :                   rpl_rdv     rpl_rdv     rpl_rdv
           |        :                      :           :           :
           +--------+ <- - - - - - - - - - +  - - - - -+  - - - - -+  - -...

 Notes: 1. Bold outlines represent ports (rendezvous entry points).
        2. Cal_por may be used in place of fwd_por, but this results in
           nested rendezvous.  As long as it is okay for requesting Task
           X to resume execution after the processing of server task
           Processes A through C is complete, the use of fwd_por can
           eliminate the need for rendezvous nesting, thus increasing
           efficiency of operation.

                Figure 22 Server Task Operation Using fwd_por


Generally, fwd_por is executed by server distribution tasks (tasks for
distributing server accepted processing to other tasks) such as shown in the
figure.  Accordingly, a server distribution task which has executed fwd_por
must accept next request regardless as to whether
or not the forwarded rendezvous can be established.  In this case, the message
area of fwd_por is used for processing the next request.  So the modification
of contents of the message area should be made so that it does effect the
rendezvous forwarding which was previously processed.  For this reason, it
should allow for the modification of the contents of the message area
specified by msg to fwd_por after fwd_por is executed even before the
forwarded rendezvous has been established.

The implementation method which use the message area specified with cal_por
as a buffer area is allowed in order to realize this specification.
Specifically, fwd_por processing results in the call message specified with
fwd_por being copied to the msg area specified to cal_por, thus allowing for
the task issuing fwd_por to change the contents of the message area.  When a
rendezvous is established the message stored in the message area specified
with cal_por is passed to the task accepting the rendezvous regardless of
whether or that rendezvous was forwarded.  Even if the task issuing cal_por is
on another node, the task performing connection function processing should
have a buffer area for storing call and reply messages.  This buffer is used
for storing call messages when forwarding takes place.

The following specifications are provided so that this type of implementation
may be applicable.

  - If there is a possibility that a rendezvous requested using cal_por may be
    forwarded, a memory area of at least maxrmsz bytes must be allocated below
    msg as specified to cal_por regardless of the expected size of the reply
    message.

  - The send message size, cmsgsz, specified with fwd_por must be equal to or
    less than the maxrmsz specified for the port being forwarded to.

  - If a rendezvous is forwarded using fwd_por, the maxrmsz of the port being
    forwarded to must not be larger than the maxrmsz of the port being
    forwarded from.  Its value is equal to or less than that of the previous
    port.

Fwd_por is [level E] (not [level EN]) because it does not allow a rendezvous
to be forwarded to a port on another node.  Note however that the task calling
for the rendezvous, given by rdvno, may exist on another node.

In the sense that a task state on another node may change from wait for
rendezvous completion to wait on rendezvous call, fwd_por does need to
provide some processing related to the connection function.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (porid was invalid or could not be used, or
            porid represents a port on another node)
  E_NOEXS   Object does not exist (the port specified by porid does not exist)
  E_OACV    Object access violation (A porid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (cmsgsz is 0 or less; cmsgsz > maxcmsz of the port
            being forwarded to; cmsgsz > maxrmsz of the port being forwarded
            from; calptn=0; or the value unsuitable for msg)
  E_OBJ     Invalid object state (rdvno is invalid; maxrmsz of the port being
            forwarded to > maxrmsz prior to forwarding)
  E_CTX     Context error (issued from task-independent portions
            (implementation dependent))
  EN_NOSPT  No support for the connection function

[Differences from uITRON 2.0 and ITRON2 Specifications]

The operations related to rendezvous forwarding have been clarified.

Along with the separation of the cmsgsz parameter representing the size of the
call message, the order of the calptn parameter in the C language interface
has been changed.

[Rationale]

In order to reduce the number of states managed by operating system,
fwd_por specifications have been designed under the assumption that the
history of rendezvous forwarding will not be logged.  If an application
requires that this information be logged, we suggest nesting cal_por-acp_por
pairs rather than using fwd_por.


========================================================================
|| [E] || rpl_rdv || Reply Rendezvous
========================================================================
  rpl_rdv:        Reply Rendezvous

[Parameters]
  RNO     rdvno   RendezvousNumber
  VP      msg     Start Address of Reply Message Packet
  INT     rmsgsz  ReplyMessageSize (in bytes)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = rpl_rdv ( RNO rdvno, VP msg, INT rmsgsz ) ;

[Description]

This system call returns a reply message to the task being rendezvoused with
(the calling task), and then terminates the rendezvous.

The task issuing this system call (Task X) must be currently in a rendezvous
(must have already executed acp_por).  The calling task being rendezvoused
with is supposed to be Task Y and a rendezvous number returned as the return
parameter for acp_por is rdvno.  When rpl_rdv is executed in this situation,
the rendezvous between Task X and Task Y is released and Task Y, the calling
task in wait for rendezvous completion, is returned to RUN/READY state.

When a rendezvous is terminated using rpl_rdv, it is possible for Task X, the
accepting task, to send a message to Task Y, the calling task.  The contents
of the message specified by the accepting task are copied into the memory area
given by msg as specified with cal_por by the calling task.  The size of the
reply message rmsgsz is returned to cal_por as the return parameter.

An E_PAR error will result if rmsgsz is greater than the value specified to
cre_por for maxrmsz.  A message of size zero cannot be sent.  An E_PAR error
will result if rmsgsz is less than or equal to zero.  If the error occurs, the
rendezvous will not terminate and the wait for rendezvous completion state of
the task issuing cal_por will not be released.

There is no reason that fwd_por or rpl_rdv would need to be executed from task-
independent portions, but it is possible to issue fwd_por or rpl_rdv from
tasks in dispatch disabled or interrupt disabled state.  This feature can be
used when processing indivisibly to fwd_por or rpl_rdv is required.  Error
checking of fwd_por or rpl_rdv executed from task-independent portions is
implementation dependent.

[Supplemental Information]

Since rpl_rdv does not include a parameter representing an ID number, it is
not possible to reference the Object Location Table or directly control
objects on other nodes.  In this sense, the support level for this call is
[E] (not [EN]) as it is not necessary to make the interface of this system
call support the connection function.  Note however that the task calling
for the rendezvous may exist on another node.  In the sense that a task on
another node may be released from wait for rendezvous completion, rpl_rdv
needs to provide some processing related to the connection function.

If a given node does not support rendezvousing with tasks on another node, the
cal_por call issued by the other node should result in an EN_RSFN error before
rpl_rdv results in an error.

The task accepting a rendezvous has no way of directly knowing if the task
calling for the rendezvous terminates abnormally for some reason before the
rendezvous is completed (before rpl_rdv is issued).  In this case, an E_OBJ
error will result when the task accepting the rendezvous executes rpl_rdv.

After a rendezvous is established tasks are in principle cut off from the port
used (there is no reason for these objects to reference information regarding
each other).  However, since the value of maxrmsz, used when checking the
length of the reply message sent using rpl_rdv, is dependent on the port in
question, the task in rendezvous must record this information somewhere.  One
possible way of implementing this is to write it in the Task Control Block
(TCB) of the calling task in WAIT state or in memory (such as the stack) which
is accessible from the TCB.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (rmsgsz is 0 or less; maxrmsz; or the value
            unsuitable for msg)
  E_OBJ     Invalid object state (rdvno is invalid)
  E_CTX     Context error (issued from task-independent portions
            (implementation dependent))
  EN_CTXID  Specifies an object on another node when the system call was
            issued from a task in dispatch disabled state or task-independent
            portion (The call was issued from a task in dispatch disabled
            state, but the calling task is on another node. This is
            implementation dependent.)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from rpl_por to rpl_rdv since
this call does not manipulate any ports.

[Rationale]

Although rdvno is specified for rpl_rdv and fwd_por to distinguish
established rendezvous from each other, the ID (porid) for the port used
to establish rendezvous is not specified.  This is because tasks are no longer
related to any ports after a rendezvous has been established.

The E_OBJ error code is used rather than E_PAR when the value of rdvno is
invalid.  This is because rdvno is used to indicate the task calling for the
rendezvous.


========================================================================
|| [EN] || ref_por || Reference Port Status
========================================================================
  ref_por:        Reference Port Status

[Parameters]
  ID      porid   PortID
  T_RPOR  *pk_rpor        Start Address of Packet to Reference Port

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rpor members)-
  VP      exinf   ExtendedInformation
  BOOL_ID wtsk    WaitingTaskInformation
  BOOL_ID atsk    AcceptingTaskInformation
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_por ( T_RPOR *pk_rpor, ID porid ) ;

[Description]

This system call refers to the state of the port specified by porid, and
returns the information of a task waiting to accept a rendezvous (atsk), the
information of a task waiting to call for a rendezvous (wtsk), and its
extended information (exinf).

Ports can be handled through connection function.  If the
implementation supports the connection function, porid is converted to
a pair of node number and object number using an object location table.
This pair is then used to access the port on the appropriate node
(remote or local) of the network.  The object location table is specified
at the time of configuration of each node.

Even if porid specifies a port on another node, port status information
(packet contents) which are read are automatically transferred to the
requesting node from the target node.

Wtsk indicates whether or not there is a task waiting to call a rendezvous at
the port in question.  If there is no waiting task, wtsk is returned as
FALSE = 0.  If there is a waiting task, wtsk is returned as a value other
than 0.  On the other hand, atsk indicates whether or not there is a task
waiting to accept a rendezvous at the port in question.  If there is no
waiting task, atsk is returned as FALSE = 0.  If there is a waiting task,
atsk is returned as a value other than 0.

Depending on the implementation, wtsk may be returned as the ID (non-zero) of
the task waiting for the port.  Similarly, atsk may be returned as the ID
(non-zero) of the task waiting to accept a rendezvous at the port.
If there are multiple tasks waiting for the port, the ID of the task at the
head of the queue is returned.  However, this feature is considered an
extended function [level X] for which compatibility and connectivity are not
guaranteed.  Even with implementations which return the ID of waiting tasks in
wtsk, the value of wtsk may not be correct (may be non-zero but undefined)
if the waiting task is on another node.  If a system returns the ID
of a waiting task, the task ID as seen from the access environment of the
node to which the port specified to ref_por belongs should be returned.

An E_NOEXS error will result if the port specified to ref_por does not
exist.

[Supplemental Information]

An EN_RPAR error will result if the number of bits used on the target node is
larger than that used on the requesting node, and if a value not supported by
the requesting node is returned for exinf, wtsk or atsk.

When using the [level X] feature whereby the ID of waiting tasks can be
returned to wtsk, the fact that the value of wtsk may not be correct when the
waiting task is on another node is due to restrictions on the implementation
of the connection function.  In other words, if connection function processing
is being carried out by another task (connection function processing task)
on target node, the ID of the connection function processing task will appear
as the ID of the waiting task, not the ID of the task which issued the
cal_por system call.  If the task issuing cal_por is on another node,
it may not be possible to access the same task using that ID even if the
correct task ID is returned by wtsk.  In other words, sometimes the value of
wtsk is meaningless even when the correct task ID is returned.

This system call cannot be used to find out information related to tasks
which has established rendezvous.

Depending on the implementation, additional information besides wtsk and atsk
(such as maximum message sizes, maxcmsz and maxrmsz) may also be referred.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (porid was invalid or could not be used)
  E_NOEXS   Object does not exist (the port specified by porid does not exist)
  E_OACV    Object access violation (A porid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)
  EN_OBJNO  An object number which could not be accessed on the target node
            is specified.
  EN_CTXID  Specified an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion
  EN_RPAR   A value outside the range supported by the issuing node and/or
            transmission packet format was returned as a return parameter (a
            value outside supported range of the requesting node was returned
            for exinf, wtsk, atsk)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from por_sts to ref_por.

The system call for retrieving information related to tasks which has
established rendezvous (rdv_sts) was abolished due to the principle that
tasks are no longer related to any ports after a rendezvous has been
established for them.

****************************************************************************
***    3.5 Interrupt Management Functions                                ***
****************************************************************************

Interrupt management functions define external interrupt handlers and
disable/enable external interrupt.

Interrupt handlers are considered task-independent portions under ITRON and
uITRON specifications.  Although system calls may be issued from task-
independent portions in the same manner as from task portions, the following
restrictions apply as to the system calls which may be issued.

  - System calls which implicitly specify the issuing task or change the
    task state of issuing task into a WAIT state cannot be issued.
    Attempting to do so results in an E_CTX error.

  - System calls which handle objects on other nodes cannot be issued.
    Attempting to do so results in an EN_CTXID error.

  - Depending on restrictions of the implementation, some other system calls
    also cannot be issued from task-independent portions.  System calls that
    can be issued from task-independent portions is implementation dependent.
    However, a method must be provided for waking up tasks (releasing tasks
    from WAIT state) using system calls which can be issued from
    task-independent portions.

  - For increased processing speed, some system calls to be issued from task-
    independent portions may be separated from the system calls to be
    issued from task portions.  Such calls are specially named under the form
    i???_???.  Which system calls are separated is implementation dependent.

Task switching (dispatching) is not performed while task-independent portions
are executing.  Even if the result of a system call issued is a dispatching
request, that dispatching is delayed until control leaves the task-independent
portion.  This is called "delayed dispatching".


========================================================================
|| [C] || def_int || Define Interrupt Handler
========================================================================
  def_int:        Define Interrupt Handler

[Parameters]
  UINT    dintno  InterruptDefinitionNumber
  T_DINT *pk_dint Packet to DefineInterruptHandler
 -(pk_dint members)-
  ATR     intatr  InterruptHandlerAttributes
  FP      inthdr  InterruptHandlerAddress
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = def_int ( UINT dintno, T_DINT *pk_dint ) ;

[Description]

This system call defines an interrupt handler for the interrupt number given
by dintno, and makes that interrupt handler ready to use.  Specifically, it
makes all necessary correspondences with the interrupt number given by dintno
and the interrupt handler address and attributes.

Dintno represents an interrupt vector number or an interrupt device number.
This feature is CPU dependent.  Depending on the CPU, other parameters in
addition to intatr and inthdr (such as interrupt masks to use when the
interrupt handler starts) may also be specified.

The lower bits of intatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of intatr may be specified as follows.

        intatr := (TA_ASM || TA_HLNG)

        TA_ASM  The interrupt handler being defined is written in assembler
        TA_HLNG The interrupt handler being defined is written in a high-level
                language

The format of intatr is shown in Figure 23.



   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - H|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - H|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - H|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           intatr is 16 bits or less.
        2. H=1 indicates that the interrupt handler being defined is
           written in a high-level language (TA_HLNG).

                           Figure 23 intatr Format


As a rule, the OS does not involve itself when an interrupt handler starts
under ITRON or uITRON specifications.  When an interrupt is invoked, the
interrupt handler defined with this system call is started directly by the
interrupt processing mechanism of the CPU hardware.  Accordingly, code at the
beginning and end of an interrupt handler must save and restore any registers
used by the interrupt handler.

The interrupt handler is finished with the ret_int or ret_wup system calls.

Even when a system call issued in an interrupt handler results in a situation
where a task in RUN state should go to another state and another task should go
to RUN state, no task dispatching takes place while the interrupt handler is
running.  Even when dispatching is required, the interrupt handler must finish
executing before dispatching.  In other words, even if a dispatch request
occurs while an interrupt handler is executing, it is not processed
immediately, but rather that dispatching is delayed until the interrupt handler
finishes.  This is called "delayed dispatching".

Interrupt handlers are executed as task-independent portions.  As such, a
system call, which may result in a WAIT state or which specifies the issuing
task, cannot be executed from an interrupt handler.

System calls which may be available from an interrupt handler are
implementation dependent.  However, a method must be provided for waking up
tasks (releasing tasks from WAIT state) using system calls which can be
issued from an interrupt handler.  The following restrictions may be provided
depending upon implementation-dependent specifications.

  - A system call may be restricted such that it is allowed to be issued only
    from task-independent portions (such as an interrupt handler).

  - Performance may be increased by making separate versions of system
    calls depending on whether they are issued from task portions or task-
    independent portions.  In this case, the name of the system call issued
    from task-independent portions must be i???_??? when the equivalent
    system call issued from task portions is ???_???.
    For example, if there is a special version of sig_sem, which returns
    semaphore resources, has been provided for execution within an interrupt
    handler.  The name of this system call would then be isig_sem.

Specifying pk_dint = NADR = -1 cancels the definition of the previously
defined interrupt handler.

It is possible to redefine an interrupt handler for the interrupt number
already defined.  When redefining an interrupt handler, it is not necessary
to first cancel the handler definition which has that number.  No error will
result if a new interrupt handler is defined using a dintno for which a
handler has already been defined.

ITRON and uITRON specifications require that a function is provided for
defining interrupt handlers.  However, interrupt handlers do not necessarily
have to be defined dynamically using this system call.  Just as with the
creation of objects, handlers may be defined statically at system startup.
In other words, this system call does not absolutely have to be supported as
long as another method of defining interrupt handlers is provided.

[Supplemental Information]

The standard packet format of pk_dint (the order and number of bits associated
with each member) is as stated above; packet format may be changed as
necessary for implementation on various systems as long as the compatibility
with other systems is not a problem.

When TA_HLNG is specified, a high-level language environment setting
program (a high-level language support routine) is called before branching
to the inthdr address.  The least significant bit (LSB) of the system
attribute bits is used for this specification.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block cannot be allocated)
  E_RSATR   Reserved attribute (intatr was invalid or could not be used)
  E_PAR     Parameter error (dintno, pk_dint or inthdr was invalid or could
            not be used)


========================================================================
|| [R] || ret_int || Return from Interrupt Handler
========================================================================
  ret_int:        Return from Interrupt Handler

[Parameters]
  None

[Return Parameters]
  Not returned to the context issuing the system call.

[C Language Interface]
  void ret_int ( ) ;

[Description]

This system call causes the invoked interrupt handler to finish.

Under ITRON and uITRON specifications, dispatching is not performed during
the execution of an interrupt handler even if system calls in the interrupt
handler request dispatching.  Instead such dispatching is delayed until the
interrupt handler finishes by issuing ret_int.  This is the principle of
delayed dispatching.  For this reason, ret_int processes any dispatch requests
caused by the issuing of system calls from the interrupt handler.

As a rule, the OS does not involve itself when an interrupt handler starts
under ITRON or uITRON specifications.  When an interrupt is invoked, the
interrupt handler is started directly by the interrupt processing mechanism
of the CPU hardware.  Accordingly, code at the beginning and end of an
interrupt handler must save and restore any registers used by the interrupt
handler.

For these reasons, sometimes ret_int cannot use the function codes because
the status of the stack and registers at the time ret_int is executed must be
the same as before the interrupt handler started.  When this happens, ret_int
must be implemented using a trap instruction of another vector separate from
that used for other system calls.

The above point must be carefully noted when writing interrupt handlers in
assembly language and using the ret_int system call under an assembly
language interface.  When interrupt handlers are written in a high-level
language, the above processing will be handled inside a high-level language
support routine or a high-level language interface routine.

[Supplemental Information]

Ret_int is a system call which does not return any parameters to the original
issuing context.  Accordingly, even if an error code is returned due to the
detection of some error, the handlers making this system call do not usually
perform any error checking, and it is in fact possible that a program could
run out of control.  For this reason, even if an error is detected upon making
this system call, it is not returned to the issuer of the system call.  If
information on detected errors is required, it should be left in a message
buffer used as an error log.

If it is known that dispatching never occurs (if it is known the same task
will continue execution) after control has been returned from an interrupt
handler, the interrupt handler may finish using an assembler interrupt return
instruction, rather than ret_int.

Depending on the CPU architecture and method of configuring the OS, it may be
possible to perform delayed dispatching even when an interrupt handler
finishes using an assembler return from interrupt instruction.  In the case of
ITRON or uITRON specification OS implemented on a TRON-specification chip,
executing the assembler return from interrupt instruction (REIT instruction)
starts a delayed interrupt function (DI function).  This instruction performs
all the processing of ret_int including delayed dispatching.  Under this
implementation, the REIT instruction may be interpreted as realizing the
ret_int system call.

Depending on the implementation, if the interrupt handler is written in a
high-level language, the high-level language's return instruction (such as
C's return statement or function end) allows automatic execution of ret_int
(through a high-level language support routine).

Operations are not guaranteed when ret_int is executed from other functions
or subroutines called from an interrupt handler.  Those operations include
returning from the interrupt handler as dictated by a system call, returning
to where the functions or subroutines are called, and reporting of errors.

E_CTX error checking when ret_int is called from a timer handler is
implementation dependent.  Depending on the implementation, control may return
from a different type of handler.

If ret_int is implemented using an assembler return from interrupt instruction
or a return from subroutine instruction, manipulating the stack becomes
difficult when this system call is invoked from a high-level language.  So,
the specification allows an implementation to interpret ret_int written in the
high-level language simply as a return statement, and have the corresponding
assembler return from interrupt instruction or return from subroutine
instruction execute in the high-level language support routine to which
control is returned.

It is necessary to execute ret_int at the top level of the interrupt handler
(rather than from a called function or subroutine) when writing interrupt
handlers which can be executed on all implementations of the OS (when writing
programs with broad compatibility).

Under uITRON 3.0 specification, the names of all system calls which indicate
the end of a handler begin with 'ret'.  And all system calls which do not
return to their issuing contexts are named ret_???, ext_??? or exd_???.

[Error Codes]
  * It is probable to detect the following error.  No return is made to the
    context issuing the system call even if an error is detected.  Error codes
    therefore cannot be returned directly as a return parameter of the system
    call.  The method by which errors are detected, if necessary, is
    implementation dependent.

  E_CTX     Context error (issued from portions other than interrupt
            handlers (implementation dependent))


========================================================================
|| [E] || ret_wup || Return and Wakeup Task
========================================================================
  ret_wup:        Return and Wakeup Task

[Parameters]
  ID      tskid   WakeupTaskID

[Return Parameters]
  Not returned to the context issuing the system call.

[C Language Interface]
  void ret_wup ( ID tskid ) ;

[Description]

If the task specified by tskid is waiting due to the execution of slp_tsk or
tslp_tsk, this system call will cause its WAIT state to be released, and the
issuing interrupt handler to finish.

If the specified task has not yet executed slp_tsk or tslp_tsk when ret_wup is
called, the request will be queued.

ret_wup combines the functions of wup_tsk and ret_int.

Since ret_wup is a system call intended for execution from an interrupt
handler, tskid cannot be used to specify a task on another node.  For this
reason, ret_wup is [level E], not [level EN].

[Supplemental Information]

The task specified to ret_wup is usually a task used for processing interrupt
(an interrupt task).  The ret_wup system call is provided so that interrupt
tasks may be efficiently run from interrupt handlers.

Ret_wup is a system call which does not return any parameters to the original
issuing context.  Accordingly, even if an error code is returned due to the
detection of some error, the handlers making this system call do not usually
perform any error checking, and it is in fact possible that a program could
run out of control.  For this reason, even if an error is detected upon making
this system call, it is not returned to the issuer of the system call.  If
information on detected errors is required, it should be left in a message
buffer used as an error log.

[Error Codes]
  * It is probable to detect the following errors.  No return is made to the
    context issuing the system call even if an error is detected.  Error codes
    therefore cannot be returned directly as a return parameter of the system
    call.  The method by which errors are detected, if necessary, is
    implementation dependent.

  E_CTX     Context error (issued from portions other than interrupt
            handlers (implementation dependent))
  E_ID      Invalid ID number (tskid was invalid or could not be used)
  E_NOEXS   Object does not exist (the task specified by tskid does not exist)
  E_OBJ     Invalid object state (a task is in DORMANT state)
  E_QOVR    Queuing or nesting overflow (the queuing count given by wupcnt
            went over the maximum allowed)
  EN_CTXID  Specifies an object on another node when the system call was
            issued from a task in dispatch disabled state or from a task-
            independent portion


========================================================================
|| [R] || loc_cpu || Lock CPU
========================================================================
  loc_cpu:        Lock CPU

[Parameters]
  None

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = loc_cpu ( ) ;

[Description]

This system call disables external interrupt and task dispatching.

Interrupts and dispatching remain disabled until unl_cpu is executed.  All
possibility that a task might be preempted (have its CPU privileges taken away)
by an interrupt handler or another task is suppressed after it executes
loc_cpu.

Specific operations while interrupt and dispatching are disabled are as
follows.

  - External interrupt is disabled.  Even if a request for an interrupt
    occurs, the startup of the associated interrupt handler will be delayed
    until the CPU is unlocked by unl_cpu.

  - Even in a situation where normally a task issuing loc_cpu should be
    preempted by a system call issued by the task issuing dis_dsp, the task
    that should normally be executed is not dispatched.  Instead, dispatching
    of this task is delayed until dispatch disabled state is cleared by
    unl_cpu.

  - An E_CTX error will result if a task which has executed loc_cpu attempts
    to execute a system call which may cause an issuing task to enter a wait
    state (such as slp_tsk, wai_sem, etc.).

  - An EN_CTXID error will result if a task which has executed loc_cpu
    attempts to execute a system call which manipulates an object on another
    node (if the ID parameter of the system call issued represents an object
    on another node).

  - If system status is referred by ref_sys after the execution of loc_cpu,
    TSS_LOC will be returned as sysstat.

No error will result and execution will continue unaffected if a task which
has already disabled interrupt and dispatching issues another loc_cpu call.
Regardless of how many times loc_cpu has been issued, only a single call to
unl_cpu is required to once again enable interrupt and dispatching.  The
operation of nested pairs of loc_cpu and unl_cpu should be maintained by the
user if necessary.

It is possible to issue loc_cpu and unl_cpu system calls while dispatching has
already been disabled by dis_dsp.  If loc_cpu is issued after dis_dsp, the
system will change from the dispatch disabled state to the interrupt and
dispatch disabled state.  In this case, the end result of issuing loc_cpu is
the same regardless of whether or not dis_dsp has already been issued.  If the
system calls are made in the order, dis_dsp, loc_cpu and then unl_cpu, both
interrupt and dispatching will be enabled after the execution of unl_cpu.
The pair of loc_cpu and unl_cpu can't be nested inside the pair of dis_dsp
and ena_dsp.

If unl_cpu is issued after dis_dsp, the system will change from the dispatch
disabled state to a state in which both interrupt and dispatching are enabled.
In this case, unl_cpu functions exactly the same as ena_dsp.

On the other hand, an E_CTX error will result if either dis_dsp or ena_dsp is
issued between a loc_cpu and an unl_cpu (while both interrupt and dispatching
are disabled).

Table 6 outlines all the state transitions described above.


           Table 6 State Transitions Related to dis_dsp and loc_cpu

+------+-----------+---------------------+--------+--------+--------+--------+
|Status| Value Re- | Status Description  |If      |If      |If      |If      |
|Number| turned by |---------+-----------|dis_dsp |ena_dsp |loc_cpu |unl_cpu |
|      | ref_sys   |Interrupt|Dispatching|executed|executed|executed|executed|
+------+-----------+---------+-----------+--------+--------+--------+--------+
|  1   |  TSS_TSK  | Enabled |  Enabled  |  ->2   |  ->1   |  ->3   |  ->1   |
+------+-----------+---------+-----------+--------+--------+--------+--------+
|  2   |  TSS_DDSP | Enabled |  Disabled |  ->2   |  ->1   |  ->3   |  ->1   |
+------+-----------+---------+-----------+--------+--------+--------+--------+
|  3   |  TSS_LOC  | Disabled|  Disabled |  E_CTX |  E_CTX |  ->3   |  ->1   |
+------+-----------+---------+-----------+--------+--------+--------+--------+
|      | Implemen- |         |           | Whether or not this state exists  |
|  4   | tation    | Disabled|  Enabled  | is implementation dependent.      |
|      | Dependent |         |           |  (related to specifications for   |
|      |           |         |           |   dis_int and chg_iXX)            |
+------+-----------+---------+-----------+--------+--------+--------+--------+


[Supplemental Information]

A running task cannot enter the DORMANT or NON-EXISTENT state while interrupt
and dispatching are disabled.  An E_CTX error will result if an running task
issues either ext_tsk or exd_tsk while interrupt and dispatching are disabled.
Note however that since both ext_tsk and exd_tsk are system calls which do not
make returns to their original context, error is not reported using return
parameters of these system calls.  If information on detected errors is
required it should be left in a messagebuffer used as an error log.

It is possible to use loc_cpu for exclusive control between a task and an
interrupt handler or another task, but only if the system is not a
multiprocessor configuration.

In some cases, alternative function of loc_cpu may be implemented with dis_dsp
and dis_int plus chg_iXX.  However, since specifications for dis_int and
chg_iXX depend on the processor being used, use loc_cpu and unl_cpu when
writing programs which are not CPU dependent.  Even if the procedure is not in
need of disabling dispatch and is solely intended to inhibit interrupt, use
loc_cpu of unl_cpu when writing a CPU independent program is desired.

CPU and/or implementation-dependent operations result when an attempt is made
by the user to directly manipulate the interrupt mask (the disable interrupt
flag) in the PSW (Processor Status Word) without using loc_cpu.  Specifically,
dispatching may or may not also be disabled while interrupt is disabled in
this way.  While this method of disabling interrupt may be tempting for the
purpose of improving efficiency, we recommend that only loc_cpu and unl_cpu be
used rather than manipulating the interrupt mask in the PSW (the disable
interrupt flag) when writing programs which are not CPU dependent.

Depending on the CPU architecture and method of configuring the OS, it may be
possible to ensure that setting the interrupt mask (disable interrupt flag)
will automatically disable dispatching as well.  In the case of ITRON or
uITRON specification OS implemented on a TRON-specification chip, where the
delayed interrupt function (DI function) is used for implementing dispatching,
changing the interrupt mask (IMASK) in the PSW automatically disables all
dispatching.  Under this implementation, the IMASK modification instruction
may be interpreted as being no different from the loc_cpu system call.

Although the system status while interrupt and dispatching are disabled by
loc_cpu is similar to that associated with task-independent portions, it is
not exactly the same.  Table 7 shows the differences between the two.


               Table 7 System Status when loc_cpu has Executed
                       Versus Task-Independent Portions

+------------------------------+----------------------------------------+
| Status after loc_cpu has     | Task-independent portions              |
| executed                     |                                        |
+------------------------------+----------------------------------------+
| External interrupt disabled  | Disabled except for higher priority    |
|                              | external interrupt                     |
|                              |                                        |
| Dispatching disabled         | Dispatching disabled (delayed)         |
| (delayed)                    |                                        |
|                              |                                        |
| Tskid is returned by get_tid | 0 is returned by get_tid               |
|                              |                                        |
| All system calls may be      | Which system calls may be issued is    |
| issued (except those         | implementation dependent (except those |
| resulting in a WAIT state)   | resulting in a WAIT state)             |
|                              |                                        |
| TSS_LOC is returned as       | TSS_INDP is returned as sysstat for    |
| sysstat for ref_sys          | ref_sys                                |
+------------------------------+----------------------------------------+


[Error Codes (ercd)]
  E_OK      Normal Completion
  E_CTX     Context error (issued from task-independent portions)

[Differences from uITRON 2.0 and ITRON2 Specifications]

This is a new system call.

[Rationale]

The reason loc_cpu may not be issued from a task-independent portion
(interrupt handler) is that nesting control is not available.

The dis_int system call is provided for disabling interrupt without disabling
dispatching.  However, dis_int cannot clearly define what operations take
place when dispatching occurs while interrupt is disabled.  (For details,
see the description of dis_int.) dis_int is [level C] since
specifications for dispatching while interrupt is disabled are CPU dependent.
If both interrupt and dispatching are disabled as with loc_cpu, then
operations are no longer implementation dependent.  This leads to the
specification that the support level for loc_cpu, which combines the functions
of disabling interrupt and disabling dispatching, is [level R], while
dis_int, which only disables interrupt, is [level C].

The reason an E_CTX error results when dis_dsp or ena_dsp is issued between a
loc_cpu and an unl_cpu is as follows.  Loc_cpu causes system status to transit
to one in which both interrupt and dispatching are disabled, while ena_dsp
causes the system status to transit to one in which dispatching is enabled.
Allowing ena_dsp to execute after loc_cpu would make it possible to disable
interrupt while enabling dispatching.  However, as stated previously,
dispatching while interrupt is disabled remains a CPU-dependent
specification.  Executing ena_dsp after a loc_cpu therefore results in
an error so as to avoid any ambiguity in this specification.  Dis_dsp also
results in an error along with ena_dsp.


========================================================================
|| [R] || unl_cpu || Unlock CPU
========================================================================
  unl_cpu:        Unlock CPU

[Parameters]
  None

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = unl_cpu ( ) ;

[Description]

This system call enables external interrupt and task dispatching.
Specifically, it releases the system status caused by loc_cpu in which
interrupt and dispatching are disabled.

No error will result and execution will continue unaffected if unl_cpu is
issued while interrupt and dispatching are still enabled.

If unl_cpu is issued while dispatching has been disabled by dis_dsp,
both interrupt and dispatching are enabled.  In this case, unl_cpu functions
exactly the same as ena_dsp.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_CTX     Context error (issued from task-independent portions)


========================================================================
|| [C] || dis_int || Disable Interrupt
========================================================================
  dis_int:        Disable Interrupt

[Parameters]
  UINT    eintno  InterruptEnableNumber

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = dis_int ( UINT eintno ) ;

[Description]

This system call disables the interrupt specified by the interrupt number
eintno.

The specific format of eintno is CPU or implementation dependent, and it
represents an interrupt vector number and interrupt device number.  Depending
on the implementation, eintno may represent the same or different information
as dintno parameter of def_int.

Under some implementations of this system call, omitting the eintno parameter,
or specifying a special value for it, may result in disabling all interrupts.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (eintno was invalid or could not be used)

[Rationale]

The basic reason dis_int was classified under the CPU-dependent system call
[level C] is that its specification is highly dependent on CPU architecture
and hardware configuration.  The specific reasons are as follows.

   1) The format of eintno is CPU and/or implementation dependent when eintno
      is specified to dis_int to disable the interrupt of a particular device
      (or vector).

   2) It is difficult to standardize the specifications related to the
      handling of the dispatches during disabled interrupt when disabling all
      external interrupts without passing eintno for dis_int.  Specifically,
      a problem arises when dispatching occurs while interrupt is disabled
      by dis_int, in regards to whether disabled interrupt state should be
      continued or not after the dispatching.  Studying this problem
      closely reveals the following facts.

        2a) If dispatch disable and interrupt disable are considered as
            independent states, task dispatching should be performed while
            continuing to disable all interrupts.

            For example, situations may arise in which, in order to lighten
            the load of individual tasks, one may desire to perform a dispatch
            while disabling an interrupt when calling on other tasks to
            perform certain processing similar to the way in which subroutines
            are called.  In this case, the critical section covers multiple
            tasks. Specifically, several very closely related tasks will form
            a single critical section.  In this type of application, disabling
            dispatching should be independent from disabling interrupt.

            However, under typical implementations, an interrupt mask (disable
            interrupt flag) inside the PSW is used to indicate whether
            interrupt is disabled.  This would mean that it would be
            necessary not to replace the disable interrupt flag only whenever
            the PSW was replaced due to dispatching just to make disabling
            dispatching independent from disabling interrupt.  Doing so
            places a great burden on the implementation.

        2b) In order to avoid the burden on the implementation described in 2a)
            above, it is necessary to replace the entire PSW including the
            interrupt mask (disable interrupt flag) when dispatching is
            performed.  If this is done, interrupt disable state then depends
            on the issuing task and the interrupt disable state (the value of
            the disable interrupt flag in the PSW) may change due to
            dispatching.  In this case, despite the original desire to allow
            dispatching while disabling interrupt, interrupt may be
            automatically enabled depending on the PSW value of the task being
            dispatched.  A specification of this type is misleading and
            problematic.

        2c) Neither of the problems described in 2a) or 2b) occur if,
            depending on the CPU architecture and OS configuration, the
            interrupt mask (disable interrupt bit) is separated from the PSW.
            But making this specification results in enforcing conditions on
            the CPU architecture and hardware configuration used, meaning that
            this method of implementation is not always available.

The problem described above and methods of implementing loc_cpu and
dis_int will be discussed using Figure 24, which represents a
model of a typical hardware configuration.

Consider which parameters of loc_cpu and dis_int should be set based on the
hardware configuration shown in Figure 24.  Note that the following discussion
is not an ITRON specification, but rather a guideline to follow during
implementation.

  (1) Using an interrupt mask (disable interrupt flag) inside the PSW of the
      CPU
            Example: IMASK of TRON-specification chip or IFLAG of iAPX86

      - Since the flag is included in the PSW, it is naturally replaced during
        dispatching.  In other words, the flag status changes depending on
        dispatching.  If the flag is to be used to represent the INTERRUPT
        DISABLE state, mistakes will be lessened if dispatching is also
        disabled when interrupt is disabled.  This feature supports loc_cpu
        rather than dis_int.

      - Multiple interrupts of the same priority can be managed in some cases.
        (when using a TRON-specification chip or Motorola M68000 family
        processor)

      - Interrupt mask can trigger the delayed interrupt function (DI
        function) of a TRON-specification chip.



                                                   +-----------------+
                                               +---| peripheral chip |
                                               |   +-----------------+
         +-----+    +----------------------+   |   +-----------------+
         | CPU |----| interrupt controller |---+---| peripheral chip |
         +-----+    +----------------------+   |   +-----------------+
                                               |   +-----------------+
                                               +---| peripheral chip |
                                               |   +-----------------+
                                               |
                                               |           ...
                                               |   +-----------------+
                                               +---| peripheral chip |
                                                   +-----------------+

           /\                  /\                          /\
           ||                  ||                          ||
 (1) Interrupt mask  (2) A single mask for     (4) An interrupt mask for
     is inside PSW       all interrupts            all peripheral chips
     (priority or    (3) Separate masks for    (5) Separate masks for
      level)             each peripheral chip      each port

 Note: (1) through (5) are parameters which may be set from all parts.

    Figure 24 Typical Hardware Model for Considering Interrupt Processing


  (2) Using the mask for all interrupts in interrupt controller

      - Since this mask is not included in the PSW, its contents do not change
        even when task dispatching is performed.  In this case, disabling
        interrupt and disabling dispatching are independent of one another.
        When dis_int is to be used to disable all interrupts it should operate
        on this mask (corresponds to 2c) described above).

      - This method of implementation may not be applicable depending on
        architecture of the CPU and interrupt controller.

      - Processing may be slower since a peripheral device needs to be
        accessed.

  (3) Using the masks for each peripheral chip supported by interrupt
      controller

      - Since these masks are not included in the PSW, their contents do not
        change even when task dispatching is performed.  In this case,
        disabling interrupt and disabling dispatching are independent of one
        another.  When dis_int is to be used to disable an interrupt for
        specific devices by specifying eintno, it should operate on these
        masks.


========================================================================
|| [C] || ena_int || Enable Interrupt
========================================================================
  ena_int:        Enable Interrupt

[Parameters]
  UINT    eintno  InterruptEnableNumber

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = ena_int ( UINT eintno ) ;

[Description]

This system call enables the interrupt specified by the interrupt number
eintno.

The specific format of eintno is CPU or implementation dependent, and it
represents an interrupt vector number and interrupt device number.

Under some implementations of this system call, omitting the eintno parameter,
or specifying a special value for it, may result in enabling all interrupts.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (eintno was invalid or could not be used)


========================================================================
|| [C] || chg_iXX || Change Interrupt Mask (Level or Priority)
========================================================================
  chg_iXX: Change Interrupt XXXX

[Parameters]
  UINT    iXXXX   InterruptMask (level or priority)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = chg_iXX ( UINT iXXXX ) ;

[Description]

This system call changes the interrupt mask of the CPU (level or priority) to
that specified by iXXXX.

A suitable name based on the architecture of the CPU platform should be chosen
for the part of the system call name and parameter name which are represented
here as "XXXX".  Specific examples of system call names include chg_ims,
chg_ipl and chg_ilv.  In addition to iXXXX, this system call may include other
parameters, such as an interrupt number (intno), depending on the CPU.

[Supplemental Information]

During the time that any interrupts are disabled due to the use of this system
call, dispatching can be delayed until interrupt is enabled again as while
an interrupt handler is executing.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (iXXXX was invalid or could not be used)


========================================================================
|| [C] || ref_iXX || Reference Interrupt Mask (Level or Priority)
========================================================================
  ref_iXX:        Refer XXXX Status

[Parameters]
  None

[Return Parameters]
  ER      ercd    ErrorCode
  UINT    iXXXX   InterruptMask (level or priority)

[C Language Interface]
  ER ercd = ref_iXX ( UINT *p_iXXXX ) ;

[Description]

This system call returns the interrupt mask of the CPU (level or priority) in
the return parameter iXXXX.

A suitable name based on the architecture of the CPU platform should be chosen
for the part of the system call name and parameter name which are represented
here as "XXXX".  Specific examples of system call names include ref_ims,
ref_ipl and ref_ilv.  This system call may include certain parameters, such as
an interrupt number (intno), depending on the CPU.

[Error Codes (ercd)]
  E_OK      Normal Completion

****************************************************************************
***    3.6 Memorypool Management Functions                               ***
****************************************************************************

Memorypool management functions manage memorypools and allocate memory blocks.
There are two types of memorypool: fixed-size memorypools and variable-size
memorypools.  Both are considered separate objects and require different
system calls for manipulation.  While the size of memory blocks allocated
from fixed-size memorypools are all fixed, blocks of any size may be
specified when allocating memory blocks from variable-size memorypools.

Since loosely-coupled networks without any shared memory are envisioned under
the connection function of uITRON 3.0 specification, memorypool management
functions are intended to handle memory on the same node only.  As such,
memorypool management functions can't use the connection function.

Supporting functions for controlling the hardware MMU (Memory Management
Unit) are not included in memorypool management functions.


========================================================================
|| [E] || cre_mpl || Create Variable-Size Memorypool
========================================================================
  cre_mpl:        Create Variable-size Memorypool

[Parameters]
  ID      mplid   Variable-size MemoryPoolID
  T_CMPL *pk_cmpl Packet to Create Variable-size MemoryPool
 -(pk_cmpl members)-
  VP      exinf   ExtendedInformation
  ATR     mplatr  MemoryPoolAttributes
  INT     mplsz   MemoryPoolSize (in bytes)
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = cre_mpl ( ID mplid, T_CMPL *pk_cmpl ) ;

[Description]

This system call creates a variable-size memorypool having the ID number
specified by mplid.  Specifically, a memory area of the size determined by
mplsz is allocated for use as a memorypool.  A control block for the
memorypool being created is also allocated.

User memorypools have positive ID numbers, while system memorypools
have negative ID numbers.  User tasks (tasks having positive task IDs)
cannot access system memorypools (memorypools having negative ID
numbers).  An E_OACV error will result if a user task issues a system call
on a system memorypool, but error detection is implementation dependent.

Memorypools having ID numbers from -4 through 0 cannot be created.  An E_ID
error will result if a value in this range is specified for mplid.

Exinf may be used freely by the user for including extended information about
the memorypool to be created.  Information set here may be accessed by
ref_mpl. If a larger region is desired for including user information, or if
the user wishes to change the contents of this information, the usr should
allocate memory area and set the address of this memory packet to exinf.
The OS does not take care of the contents of exinf.

The lower bits of mplatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of mplatr may be specified as follows.

        mplatr := (TA_TFIFO || TA_TPRI)

        TA_TFIFO    FIFO-ordered queuing of memory waiting tasks
        TA_TPRI     Priority-ordered queuing of memory waiting tasks [level X]

TA_TFIFO and TA_TPRI are used to specify the manner in which tasks waiting for
memory allocation are put on the memorypool's queue.  If TA_TFIFO is
specified, tasks will be put on the queue on a "First In, First Out" basis.
If TA_TPRI is specified, tasks will be placed on the queue according to their
priority level.  The TA_TPRI specification is considered an extended function
[level X] for which compatibility and connectivity are not guaranteed.

The format of mplatr is shown in Figure 25.



   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - P|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - P|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - P|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           mplatr is 16 bits or less.
        2. P=1 specifies priority-ordered queuing of waiting tasks (TA_TPRI).

                           Figure 25 mplatr Format


[Supplemental Information]

Although the standard packet format of pk_cmpl (the order and number of bits
associated with each member) is as stated above, it may be changed as
necessary for implementation on various systems as long as restriction
on compatibility and connectivity with other systems is not a problem.

The memory required for creating memorypools and for allocating control
blocks for each object is reserved while system initialization.
Associated parameters are therefore specified at system configuration.

When tasks form a queue to compete for a memory, it is implementation
dependent whether priority is given to tasks requesting the smaller size of
memory or those at the head of the queue.  For example, assume that Task A,
requesting 400 bytes of memory, and Task B, requesting 100 bytes, are waiting
for a variable-size memorypool in the order A then B, and that another task
frees a memory block using rel_blk, and 200 bytes of continuous memory block
becomes available.  In this case, it is implementation dependent whether or
not Task B, which is not at the head of the queue but is requesting the
smaller size of memory, can get the newly freed memory.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block and/or for
            memorypool cannot be allocated)
  E_ID      Invalid ID number (mplid was invalid or could not be used)
  E_RSATR   Reserved attribute (mplatr was invalid or could not be used)
  E_OBJ     Invalid object state (a memorypool of the same ID already exists)
  E_OACV    Object access violation (A mplid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (pk_cmpl is invalid or mplsz is negative or
            invalid)

[Differences from uITRON 2.0 and ITRON2 Specifications]

Fixed-size memorypools and variable-size memorypools are now treated as
separate objects.  The parameter for specifying the block size of variable-
size memorypools has been eliminated, and size is now specified directly as a
number of bytes.  The system call blk_sts used on variable-size memory blocks
has been eliminated.

Attributes have been made more consistent.  The TA_TPRI specification
is at [level X].  Furthermore, the TA_CNT and TA_FIRST distinctions
have been made implementation dependent.

[Rationale]

The reason fixed-size memorypools and variable-size memorypools are
treated as separate objects is that the algorithms used for memory allocation
and the parameters used in associated system calls are quite different.

A function for providing multiple memorypools can be used for dividing
memorypools for memory reservation in case of emergency or during error
processing.


========================================================================
|| [E] || del_mpl || Delete Variable-Size Memorypool
========================================================================
  del_mpl:        Delete Variable-size MemoryPool

[Parameters]
  ID      mplid   Variable-size MemoryPoolID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = del_mpl ( ID mplid ) ;

[Description]

This system call deletes the variable-size memorypool specified by mplid.

No check or error report is performed even if there are tasks using memory
from the memorypool to be deleted.  This system call completes normally
even if some of the memory blocks are not returned.

Issuing this system call causes memory used for the control block of the
associated memorypool and the memory area making up the memorypool itself
to be released.  After this system call is invoked, another memorypool
having the same ID number can be created.

This system call will complete normally even if there are tasks waiting to
get memory blocks from the memorypool.  In that case, an E_DLT error will be
returned to each waiting task.

[Supplemental Information]

When a memorypool being waited for by more than one tasks is deleted, the order
of tasks on the ready queue after the WAIT state is cleared is implementation
dependent in the case of tasks having the same priority.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mplid was invalid or could not be used)
  E_NOEXS   Object does not exist (the memorypool specified by mplid does not
            exist)
  E_OACV    Object access violation (A mplid less than -4 was specified from
            a user task.  This is implementation dependent.)


========================================================================
|| [E] || get_blk || Get Variable-Size Memory Block
========================================================================
|| [E] || pget_blk || Poll and Get Variable-Size Memory Block
========================================================================
|| [E] || tget_blk || Get Variable-Size Memory Block with Timeout
========================================================================
   get_blk:       Get Variable-size Memory Block
  pget_blk:       Poll and Get Variable-size Memory Block
  tget_blk:       Get Variable-size Memory Block with Timeout

[Parameters (for get_blk and pget_blk)]
  ID      mplid   Variable-size MemoryPoolID
  INT     blksz   MemoryBlockSize (in bytes)

[Parameters (for tget_blk)]
  ID      mplid   Variable-size MemoryPoolID
  INT     blksz   MemoryBlockSize (in bytes)
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode
  VP      blk     StartAddress of MemoryBlock

[C Language Interface]
  ER ercd = get_blk ( VP *p_blk, ID mplid, INT blksz );
  ER ercd = pget_blk ( VP *p_blk, ID mplid, INT blksz );
  ER ercd = tget_blk ( VP *p_blk, ID mplid, INT blksz, TMO tmout ) ;

[Description]

A memory block of the size in bytes given by blksz is allocated from the
variable-size memorypool specified by mplid.  The start address of the memory
block allocated is returned in blk.

The allocated memory block is not cleared to zero.  The contents of the
memory block allocated are undefined.

If the memory block cannot be obtained from the specified memorypool when
get_blk is issued, the task issuing get_blk will be placed on the memory
allocation queue of the specified memorypool, and wait until it can get the
memory it requires.

The pget_blk system call has the same function as get_blk except for the
waiting feature.  Pget_blk polls whether or not the task should wait if
get_blk is executed.  The meaning of parameters to pget_blk are the same
with get_blk.  The specific operations by pget_blk are as follows.

  - If there is enough free memory to get the memory block of specified size
    immediately, processing is the same as get_blk: that is, the
    requested memory is allocated and the system call completes normally.

  - If there is not enough free memory, an E_TMOUT error is returned to
    indicate polling failed and the system call finishes.  Unlike get_blk,
    the issuing task does not wait in this case.  Also, the issuing task
    does not get any memory.

The tget_blk system call has the same function as get_blk with an additional
timeout feature.  A maximum wait time (timeout value) can be specified using
the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT,
will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied (i.e. without
sufficient free memory becoming available).

Only positive values can be specified for tmout.  Although the time base for
tmout is recommended to be the same as that for the system clock (1 ms is
recommended), it may sometimes be larger than the time base of system clock
for 8 and 16-bit processors.

Specifying TMO_POL = 0 to tget_blk for tmout indicates that a timeout value of
0 be used, resulting in exactly the same processing as pget_blk.  Specifying
TMO_FEVR = -1 to tget_blk for tmout indicates that an infinite timeout value
be used, resulting in exactly the same processing as get_blk.

If cre_mpl [level E] is not implemented on the system, variable-size
memorypools are created statically at system startup.  Parameters
required for creating a memorypool such as memorypool attributes (mplatr) and
memorypool size (mplsz) are also specified statically at system startup.

The order in which tasks wait on the queue when waiting to be allocated memory
blocks is according to either FIFO or task priority.  The specification
whereby tasks wait according to task priority is considered an extended
function [level X] for which compatibility is not guaranteed.  Furthermore,
when tasks form a memory allocation queue, it is implementation dependent
whether priority is given to tasks requesting the smaller size of memory or
those at the head of the queue.

Among the system calls performing resource allocation (free memory in the
buffer is considered a resource), only pget_blk, pget_blf and psnd_mbf may be
executed from task-independent portions or from tasks in dispatch disabled
state.  The same is true for tget_blk, tget_blf and tsnd_mbf with tmout =
TMO_POL.  This feature is considered an extended function [level X] for
which compatibility is not guaranteed.  The support of these functions are
implementation dependent.

[Supplemental Information]

On real-time OS, it is rare that the execution of tasks stop to wait for
memory to be allocated.  As such, pget_blk is generally more useful than
get_blk.

Pget_blk and get_blk represent the same processing as specifying certain
values (TMO_POL or TMO_FEVR) to tget_blk for tmout.  It is allowed that
only tget_blk is implemented in the kernel and that pget_blk and get_blk
are implemented as macros which call tget_blk.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mplid was invalid or could not be used)
  E_NOEXS   Object does not exist (the memorypool specified by mplid does not
            exist)
  E_OACV    Object access violation (A mplid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (tmout is -2 or less, blksz is negative or invalid)
  E_DLT     The object being waited for was deleted (the specified memorypool
            was deleted while waiting)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state; implementation dependent for
            pget_blk and tget_blk(tmout=TMO_POL))

[Differences from uITRON 2.0 and ITRON2 Specifications]

Timeout function is separated to a new system call named under the form
t???_???.  It is the same with other system calls which may enter WAIT states.

[Rationale]

Among the system calls performing resource allocation, only pget_blk, pget_blf
and psnd_mbf, and tget_blk, tget_blf and tsnd_mbf with tmout=TMO_POL may be
executed from task-independent portions.  The reasons for this are as follows.

  - Generally, resources such as semaphore count values and memory blocks are
    allocated to tasks.  As such, a task-independent portion such as an
    interrupt handler cannot obtain the resources, and wai_sem cannot be
    issued from task-independent portions.

  - But there would be no inconsistencies if it is assumed those resources
    were returned (or sent to another task or mailbox) before the task-
    independent portion terminated even if task-independent portions get
    resources.  For example, when a message must be sent from an interrupt
    handler, it is necessary for a memory block to be allocated for that
    message before it can be sent.  Since an interrupt handler cannot be
    allowed to wait, it must issue pget_blk rather than get_blk.

    When using psnd_mbf, the resource mentioned above is free memory in the
    message buffer.

  - There is no reason for system calls such as pol_flg, preq_sem and prcv_msg
    (except pget_blk, pget_blf and psnd_mbf) to be allowed to execute from
    task-independent portions.  An E_CTX error will result if any of these
    system calls are executed from task-independent portions.


========================================================================
|| [E] || rel_blk || Release Variable-Size Memory Block
========================================================================
  rel_blk:        Release Variable-size Memory Block

[Parameters]
  ID      mplid   Variable-size MemoryPoolID
  VP      blk     StartAddress of MemoryBlock

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = rel_blk ( ID mplid, VP blk ) ;

[Description]

This system call releases the memory block specified by blk and returns it to
the variable-size memorypool specified by mplid.

Executing rel_blk allows memory to be allocated to the next task waiting for
memory allocation from the memorypool given by mplid, thus releasing that
task from its WAIT state.

The variable-size memorypool to which the memory block is returned must be the
same memorypool from which it was originally allocated.  An E_PAR error will
result if an attempt is made to return a memory block to another memorypool
than that from which it was originally allocated.

[Supplemental Information]

When memory is returned to a variable-size memorypool for which more than one
task is waiting, multiple tasks may be released from waiting at the same time
depending on the number of bytes of memory.  The order of tasks on the ready
queue among tasks having the same priority after being released from waiting
for memory is implementation dependent.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mplid was invalid or could not be used)
  E_NOEXS   Object does not exist (the memorypool specified by mplid does not
            exist)
  E_OACV    Object access violation (A mplid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (blk is invalid or an attempt was made to return
            the memory block to the wrong memorypool)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The E_ILBLK error has been unified to E_PAR.


========================================================================
|| [E] || ref_mpl || Reference Variable-Size Memorypool Status
========================================================================
  ref_mpl:        Reference Variable-size MemoryPool Status

[Parameters]
  ID      mplid   Variable-size MemoryPoolID
  T_RMPL *pk_rmpl StartAddress of Packet to Reference Variable-size MemoryPool

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rmpl members)-
  VP      exinf   ExtendedInformation
  BOOL_ID wtsk    Waiting TaskInformation
  INT     frsz    FreeMemorySize (in bytes)
  INT     maxsz   MaximumFreeMemorySize (in bytes)
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_mpl ( T_RMPL *pk_rmpl, ID mplid ) ;

[Description]

This system call refers to the state of the variable-size memorypool
specified by mplid, and returns the total free memory size currently available
(frsz), the maximum continuous memory size of readily available free memory
(maxsz), information of a task waiting to be allocated memory (wtsk), and
its extended information (exinf).

Wtsk indicates whether or not there is a task waiting to be allocated memory
from the variable-size memorypool specified.  If there is no waiting task,
wtsk is returned as FALSE = 0.  If there is a waiting task, wtsk is
returned as a value other than 0.

Depending on the implementation, wtsk may be returned as the ID (non-zero) of
the task waiting to allocate memory from the variable-size memorypool.
If there are multiple tasks waiting at the memorypool, the ID of the task
at the head of the queue is returned.  However, this feature is considered
an extended function [level X] for which compatibility and connectivity
are not guaranteed.

An E_NOEXS error will result if the memorypool specified to ref_mpl does not
exist.

[Supplemental Information]

Under some implementations, a variable-size memorypool with mplid = TMPL_OS =
-4 is a system memorypool used by the OS and any unused memory is assumed
to belong to this memorypool.  Ref_mpl system call with mplid = TMPL_OS = -4
returns the remaining OS memory size.  When ref_mpl is used on this
memorypool, only the frsz and maxsz return parameters are meaningful.  The
values of exinf and wtsk are undefined in this case.  However, this feature is
considered an extended function [level X] for which compatibility is not
guaranteed.

In some implementations, memorypools having mplid = -3 or -2 may be referred
with ref_mpl as memorypools used by implementation-dependent parts of the OS
(such as those used for the stack only).  This system call can provide more
detailed information regarding remaining memory if the usage of memorypools
having mplid = -3 or -2 is more clearly defined.  Whether or not this feature
is used and any details regarding information provided are implementation
dependent.

Mplid = -1 and mplid = 0 are reserved ID number values.  An E_ID error
will result if either is specified.

Depending on the implementation, additional information besides wtsk, frsz and
maxsz (such as fragcnt to indicate the number of fragments of the free area)
may also be referred.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mplid was invalid or could not be used)
  E_NOEXS   Object does not exist (the memorypool specified by mplid does not
            exist)
  E_OACV    Object access violation (A mplid less than -4 was specified from
            a user task.  This is implementation dependent.)
        Note: User tasks can issue ref_mpl in order to reference memorypools
              of mplid = TMPL_OS = -4.  Whether or not memorypools of mplid =
              -3 or -2 may be specified to ref_mpl by user tasks is
              implementation dependent.
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from mpl_sts to ref_mpl.

The mpl_sts system call of ITRON2 specification returns the information of
the number of fragments of the free area (fragcnt).  This feature has been
eliminated from the standard interface of uITRON 3.0 specification.


========================================================================
|| [E] || cre_mpf || Create Fixed-Size Memorypool
========================================================================
  cre_mpf:        Create Fixed-size MemoryPool

[Parameters]
  ID      mpfid   Fixed-size MemoryPoolID
  T_CMPF *pk_cmpf Packet to Create Fixed-size MemoryPool
 -(pk_cmpf members)-
  VP      exinf   ExtendedInformation
  ATR     mpfatr  MemoryPoolAttributes
  INT     mpfcnt  MemoryPoolBlockCount
  INT     blfsz   MemoryBlockSize (in bytes)
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = cre_mpf ( ID mpfid, T_CMPF *pk_cmpf ) ;

[Description]

This system call creates a fixed-size memorypool having the ID number
specified by mpfid.  Specifically, a memory area of a size based on values of
mpfcnt and blfsz is reserved for use as a memorypool.  A control block for
the memorypool being created is also allocated.  The get_blf system call
specifying the memorypool created by this call can be issued to allocate
memory blocks of the size given by blfsz (in bytes).

User memorypools have positive ID numbers, while system memorypools
have negative ID numbers.  User tasks (tasks having positive task IDs)
cannot access system memorypools (memorypools having negative ID
numbers).  An E_OACV error will result if a user task issues a system call
on a system memorypool, but error detection is implementation dependent.

Memorypools having ID numbers from -4 through 0 cannot be created.  An E_ID
error will result if a value in this range is specified for mpfid.

Exinf may be used freely by the user for including extended information about
the memorypool to be created.  Information set here may be accessed by
ref_mpf. If a larger region is desired for including user information, or if
the user wishes to change the contents of this information, the usr should
allocate memory area and set the address of this memory packet to exinf.
The OS does not take care of the contents of exinf.

The lower bits of mpfatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of mpfatr may be specified as follows.

        mpfatr := (TA_TFIFO || TA_TPRI)

        TA_TFIFO    FIFO-ordered queuing of memory waiting tasks
        TA_TPRI     Priority-ordered queuing of memory waiting tasks [level X]

TA_TFIFO and TA_TPRI are used to specify the manner in which tasks waiting for
memory are put on the memorypool's queue.  If TA_TFIFO is specified, tasks
will be put on the queue on a "First In, First Out" basis.  If TA_TPRI is
specified, tasks will be placed on the queue according to their priority level.
The TA_TPRI specification is considered an extended function [level X] for
which compatibility is not guaranteed.

The format of mpfatr is shown in Figure 26.



   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - P|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - P|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - P|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           mpfatr is 16 bits or less.
        2. P=1 specifies priority-ordered queuing of waiting tasks (TA_TPRI).

                           Figure 26 mpfatr Format


[Supplemental Information]

Although the standard packet format of pk_cmpf (the order and number of bits
associated with each member) is as stated above, it may be changed as
necessary for implementation on various systems as long as restriction
on compatibility and connectivity with other systems is not a problem.

The memory area required for creating memorypools and for allocating
control blocks for each object is allocated while system initialization.
Associated parameters are therefore specified at system configuration.

When using fixed-size memorypools, it is necessary to prepare different
memorypools when different block sizes are required.  This means that
memorypools must be created for each different block size when various memory
block sizes are necessary.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block and/or for
            memorypool cannot be allocated)
  E_ID      Invalid ID number (mpfid was invalid or could not be used)
  E_RSATR   Reserved attribute (mpfatr was invalid or could not be used)
  E_OBJ     Invalid object state (a memorypool of the same ID already exists)
  E_OACV    Object access violation (A mpfid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (pk_cmpf is invalid or mpfsz and/or blfsz is
            negative or invalid)

[Differences from uITRON 2.0 and ITRON2 Specifications]

Fixed-size memorypools and variable-size memorypools are now treated as
separate objects.  Attributes have been made more consistent.  The
TA_TPRI specification is at [level X].


========================================================================
|| [E] || del_mpf || Delete Fixed-Size Memorypool
========================================================================
  del_mpf:        Delete Fixed-size MemoryPool

[Parameters]
  ID      mpfid   Fixed-size MemoryPoolID

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = del_mpf ( ID mpfid ) ;

[Description]
This system call deletes the fixed-size memorypool specified by mpfid.

No check or error report is performed even if there are tasks using memory
from the memorypool to be deleted.  This system call completes normally
even if some of the memory blocks are not returned.

Issuing this system call causes memory used for the control block of the
associated memorypool and the memory area making up the memorypool itself
to be released.  After this system call is invoked, another memorypool
having the same ID number can be created.

This system call will complete normally even if there are tasks waiting to
get memory block from the memorypool.  In that case, an E_DLT error will be
returned to each waiting task.

[Supplemental Information]

When a memorypool being waited for by more than one tasks is deleted, the order
of tasks on the ready queue after the WAIT state is cleared is implementation
dependent in the case of tasks having the same priority.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mpfid was invalid or could not be used)
  E_NOEXS   Object does not exist (the memorypool specified by mpfid does not
            exist)
  E_OACV    Object access violation (A mpfid less than -4 was specified from
            a user task.  This is implementation dependent.)


========================================================================
|| [E] || get_blf || Get Fixed-Size Memory Block
========================================================================
|| [E] || pget_blf || Poll and Get Fixed-Size Memory Block
========================================================================
|| [E] || tget_blf || Get Fixed-Size Memory Block with Timeout
========================================================================
   get_blf:       Get Fixed-size Memory Block
  pget_blf:       Poll and Get Fixed-size Memory Block
  tget_blf:       Get Fixed-size Memory Block with Timeout

[Parameters (for get_blf and pget_blf)]
  ID      mpfid   Fixed-sizeMemoryPoolID

[Parameters (for tget_blf)]
  ID      mpfid   Fixed-sizeMemoryPoolID
  TMO     tmout   Timeout

[Return Parameters]
  ER      ercd    ErrorCode
  VP      blf     StartAddress of MemoryBlock

[C Language Interface]
  ER ercd =  get_blf ( VP *p_blf, ID mpfid );
  ER ercd = pget_blf ( VP *p_blf, ID mpfid );
  ER ercd = tget_blf ( VP *p_blf, ID mpfid, TMO tmout ) ;

[Description]

A memory block is allocated from the fixed-size memorypool specified by mpfid.
The start address of the memory block allocated is returned to blf.  The size
of the memory block allocated is specified by the blfsz parameter when the
fixed-size memorypool was created.

The allocated memory block is not cleared to zero.  The contents of the
allocated memory block are undefined.

If the memory block cannot be obtained from the specified memorypool when
get_blf is issued, the task issuing get_blf will be placed on the memory
allocation queue of the specified memorypool, and wait until it can get the
memory it requires.

The pget_blf system call has the same function as get_blf except for the
waiting feature.  Pget_blf polls whether or not the task should wait if
get_blf is executed.  The meaning of parameters to pget_blf are the same
with get_blf.  The specific operations by pget_blf are as follows.

  - If there is a free memory block available, processing is the same as
    get_blf: that is, the requested memory is allocated and the system call
    completes normally.

  - If there is no free memory block, an E_TMOUT error is returned to
    indicate polling failed and the system call finishes.  Unlike get_blf,
    the issuing task does not wait in this case.  Also, the issuing task
    does not get any memory.

The tget_blf system call has the same function as get_blf with an additional
timeout feature.  A maximum wait time (timeout value) can be specified using
the parameter tmout.  When a timeout is specified, a timeout error, E_TMOUT,
will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied (i.e. without
free memory becoming available).

Only positive values can be specified for tmout.  Although the time unit for
tmout is recommended to be the same as that for the system clock (1 ms is
recommended), it may sometimes be larger than the time unit of system clock
for 8 and 16-bit processors.

Specifying TMO_POL = 0 to tget_blf for tmout indicates that a timeout value of
0 be used, resulting in exactly the same processing as pget_blf.  Specifying
TMO_FEVR = -1 to tget_blf for tmout indicates that an infinite timeout value
be used, resulting in exactly the same processing as get_blf.

If cre_mpf [level E] is not implemented on the system, fixed-size memorypools
are created statically at system startup.  Parameters required for creating
a memorypool such as memorypool attributes (mpfatr), memorypool size (mpfsz),
and block size (blfsz) are also specified statically at system startup.

The order in which tasks wait on the queue to allocate memory blocks is
according to either FIFO or task priority.  The specification whereby tasks
wait according to priority is considered an extended function [level X]
for which compatibility is not guaranteed.

Among the system calls performing resource allocation (free memory in the
buffer is considered a resource), only pget_blk, pget_blf and psnd_mbf may be
executed from task-independent portions or from tasks in dispatch disabled
state.  The same is true for tget_blk, tget_blf and tsnd_mbf with tmout =
TMO_POL.  This feature is considered an extended function [level X] for
which compatibility is not guaranteed.  The support of these functions are
implementation dependent.

[Supplemental Information]

On real-time OS, it is rare that the execution of tasks stop to wait for
memory to be allocated.  As such, pget_blf is generally more useful than
get_blf.

Pget_blf and get_blf represent the same processing as specifying certain
values (TMO_POL or TMO_FEVR) to tget_blf for tmout.  It is allowed that
only tget_blf is implemented in the kernel and that pget_blf and get_blf
are implemented as macros which call tget_blf.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mpfid was invalid or could not be used)
  E_NOEXS   Object does not exist (the memorypool specified by mpfid does not
            exist)
  E_OACV    Object access violation (A mpfid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (tmout is -2 or less)
  E_DLT     The object being waited for was deleted (the specified memorypool
            was deleted while waiting)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)
  E_TMOUT   Polling failure or timeout exceeded
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state; implementation dependent for
            pget_blf and tget_blf(tmout=TMO_POL))


========================================================================
|| [E] || rel_blf || Release Fixed-Size Memory Block
========================================================================
  rel_blf:        Release Fixed-Size Memory Block

[Parameters]
  ID      mpfid   Fixed-size MemoryPoolID
  VP      blf     StartAddress of MemoryBlock

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = rel_blf ( ID mpfid, VP blf ) ;

[Description]

This system call releases the memory block specified by blf and returns it to
the fixed-size memorypool specified by mpfid.

Executing rel_blf allows memory to be allocated to the next task waiting for
memory allocation from the memorypool given by mpfid, thus releasing that
task from its WAIT state.

The fixed-size memorypool to which the memory block is returned must be the
same memorypool from which it was originally allocated.  An E_PAR error will
result if an attempt is made to return a memory block to another memorypool
than that from which it was originally allocated.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mpfid was invalid or could not be used)
  E_NOEXS   Object does not exist (the memorypool specified by mpfid does not
            exist)
  E_OACV    Object access violation (A mpfid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (blf is invalid or an attempt was made to return
            the memory block to the wrong memorypool)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The E_ILBLK error has been integrated into E_PAR.


========================================================================
|| [E] || ref_mpf || Reference Fixed-Size Memorypool Status
========================================================================
  ref_mpf:        Reference Fixed-Size MemoryPool Status

[Parameters]
  ID      mpfid   Fixed-size MemoryPoolID
  T_RMPF  *pk_rmpf        StartAddress of Packet to Reference Fixed-size
  Memorypool

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rmpf members)-
  VP      exinf   ExtendedInformation
  BOOL_ID wtsk    WaitingTaskInformation
  INT     frbcnt  FreeMemoryBlockCount
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_mpf ( T_RMPF *pk_rmpf, ID mpfid ) ;

[Description]

This system call refers to the state of the fixed-size memorypool specified
by mpfid, and returns the current number of free blocks (frbcnt),
information of a task waiting to be allocated memory (wtsk), and its extended
information (exinf).

Wtsk indicates whether or not there is a task waiting to be allocated memory
from the fixed-size memorypool specified.  If there is no waiting task,
wtsk is returned as FALSE = 0.  If there is a waiting task, wtsk is
returned as a value other than 0.

Depending on the implementation, wtsk may be returned as the ID (non-zero) of
the task waiting to be allocated memory from the fixed-size memorypool.
If there are multiple waiting tasks at the memorypool, the ID of the task
at the head of the queue is returned.  However, this feature is considered
an extended function [level X] for which compatibility and connectivity
are not guaranteed.

An E_NOEXS error will result if the memorypool specified to ref_mpf does not
exist.

At least one of frbcnt = 0 and wtsk = FALSE is always true in this
system call.

[Supplemental Information]

While the frsz return parameter of ref_mpl returns the total size of free
memory, the frbcnt return parameter of ref_mpf returns the number of free
blocks.

Depending on the implementation, additional information besides wtsk and
frbcnt (such as memorypool attributes, mpfatr) may also be referred.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_ID      Invalid ID number (mpfid was invalid or could not be used)
  E_NOEXS   Object does not exist (the memorypool specified by mpfid does not
            exist)
  E_OACV    Object access violation (A mpfid less than -4 was specified from
            a user task.  This is implementation dependent.)
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)

****************************************************************************
***    3.7 Time Management Functions                                     ***
****************************************************************************

Time management functions provide functions for time-dependent processing.

There are functions for setting and referring the system clock, delaying
tasks, manipulating handlers invoked cyclically (cyclic handlers), and
manipulating handlers started at specified time (alarm handlers).

The following data types are used by time-related functions.

  - SYSTIME (System Time)
        Data type used by the system clock, get_tim and set_tim.
        Recommended time unit is 1 ms, and recommended bit width is 48 bits.
        Packet interface is used.

  - CYCTIME (Cycle Time)
        Data type used for specifying the cycle time for starting cyclic
        handlers with def_cyc.
        48 bit width, the same format as the system clock is recommended;
        sometimes a smaller bit width may be used.
        Time unit is the same as the system clock.
        Packet interface is used.

  - ALMTIME (Alarm Time)
        Data type used for specifying the time (relative or absolute time)
        to start alarm handlers with def_alm.
        48 bit width, the same format as the system clock is recommended;
        sometimes a smaller bit width may be used.  A different number of bits
        from CYCTIME may also sometimes be used.
        Time unit is the same as the system clock.
        Packet interface is used.

  - DLYTIME (Delay Time)
        Data type used for specifying the task delay time by dly_tsk.
        Same bit width as INT is used.
        The same time unit as the system clock is recommended;  sometimes
        a longer time unit than the system clock may be used in the case
        of processors with small bit widths (8 or 16 bits).
        Interface does not use packets.

  - TMO (Timeout)
        Data type used to specify the timeout with system calls of the form
        t???_??? which may cause the issuing task to enter a WAIT state.
        Same bit width as INT is used.
        The same time unit as the system clock is recommended;  sometimes
        a longer time unit than the system clock may be used in the case
        of processors with small bit widths (8 or 16 bits).
        Interface does not use packets.
        TMO_FEVR = -1 specifies waiting forever.
        Time unit for the requesting node, not that of the target node,
        is applied to a system call waiting for an object on another node.

[Supplemental Information]

There are a variety of data types and bit widths used for parameters such as
SYSTIME and TMO which represent the time of day or time intervals.  These have
been selected for the following reasons.

When 1 ms is used as unit time, the amount of time which can be
represented by a 32-bit signed integer is about 24 days.  48 bits are
therefore necessary since 32 bits are insufficient for representing a system
clock.  These 48 bits are divided into several parts depending on the bit
width of the processor being used for system calls (get_tim and set_tim) which
deal with the system clock, and the interface of these calls uses packets.

Non-time-related parameters for system calls used to define cyclic handlers
(def_cyc) or alarm handlers (def_alm) are provided with interface in packets,
such as handler address; so the time-related parameters also use the packets.
Use of 48-bit width is standard in parameters as it is in system clock, but a
smaller bit width may also be used.  The number of bits for the time-of-the-
day parameter of def_alm to define an absolute time may differ from the number
of bits used for the time interval parameter of def_cyc to define a cyclic
time interval.

The parameters used to specify timeout specifications in system calls of the
form t???_???, ready to enter a WAIT state, and those used to specify delay
times to dly_tsk do not require that precision (resolution).  In order to
simplify their interfaces, the interfaces for these parameters therefore do
not use packets.  Those time parameters have the number of bits equivalent to
an integer (int data type in C language).  Furthermore, these parameters may
use time unit larger than that of the system clock (1 ms is recommended) to
make the bit width smaller.

Time unit for the requesting node, not for the target node, applies to the
timeout for a system call waiting for an object on another node.  Specific
operations and method of implementation are as follows.

Each system determines a time unit for the entire network (as a rule, NT = 1
ms) in addition to a time unit for each node (xT).  Although the time unit of
each node sometimes cannot be made 1 ms due to the bit width of the associated
CPU, the time unit in the entire network is, as a rule, 1 ms since the
expression of the time unit will suffice in the standard packet format (usually
32 bits).

The following processing results when a system call with a timeout is issued
from Node X (time unit XT) on an object on Node Y (time unit YT).

  - Node X places the timeout value (N_tmout) calculated as given below in a
    packet to be sent to Node Y.
        Timeout value in a packet = N_tmout = ((tmout * XT) / NT)

  - Once on Node Y, the timeout value (N_tmout) included in the packet sent
    from Node X undergoes the following calculation and the resulting value is
    used as the timeout parameter for the associated system call on that node.
        Timeout Value on Node Y = ((N_tmout * NT) / YT)

For example, assume the following conditions:

        Task A exists on Node X with time unit  = XT = 10 ms
        Semaphore B exists on Node Y with time unit = YT = 20 ms
        Semaphore C exists on Node Z with time unit = ZT = 50 ms
        Network time unit = NT = 1 ms

If Task A executes

        twai_sem (semid = semaphore_B, tmout = 30)

the timeout time interval is 30 * 10 ms = 300 ms. Where

        N_tmout = (30 * 10 ms) / 1 ms = 300

The connection function processing task on target Node Y will accept this
request and issue the system call

        twai_sem (semid = semaphore_B, tmout = (300 * 1 ms) / 20 ms = 15)

Furthermore, if Task X executes

        twai_sem (semid = semaphore_C, tmout = 30)

the timeout value is 30 ms * 10 = 300 ms.  Where

        N_tmout = (30 * 10 ms) / 1 ms = 300

Up to this point every thing is the same as when waiting on Semaphore B.  The
connection function processing task on target Node Z will accept this request
and issue the system call

        twai_sem (semid = semaphore_C, tmout = (300 * 1 ms) / 50 ms = 6)

This demonstrates that the timeout time unit is always be the same even if the
target node changes as far as the requesting node remains unchanged.

[Differences from uITRON 2.0 and ITRON2 Specifications]

"Time management and timer handler functions" under uITRON 2.0 specification
are now called "time management functions".

Time-related data types have been reorganized as described above.  Data type
names and parameter type names have also been changed accordingly.

[Rationale]

If no special consideration was taken by the implementation, system calls with
a timeout would use the time unit of the target node (the node on which the
object being waited for exists).  However, programming in this case would be
inconvenient and misleading since the time unit of different timeouts even
inside the same program (programs executing on the same node) may be different
depending on the node where the object being waited for exists.  To cope with
this problem, special consideration as described above has been taken so that
the time unit of the requesting node always applies in this type of
specification.


========================================================================
|| [S] || set_tim || Set System Clock
========================================================================
  set_tim:        Set Time

[Parameters]
  SYSTIME *pk_tim PacketAddressRepresentingCurrentTime
 -(pk_tim members)-
  SYSTIME systim  CurrentSystemTime

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = set_tim ( SYSTIME *pk_tim );

[Description]

This system call sets the system clock to the time specified by systim.  The
bit width of the system clock and systim, which is implementation dependent, is
recommended to be 48 bits.  It is recommended that the system clock give the
number of milliseconds elapsed since January 1, 1985, 00:00:00 am (GMT).

If the number of bits required to represent systim is larger than that used
for an integer (int data type in C language) and the processor cannot handle
systim as a single data, systim may be split into high order and low order
parts (and even medium order if required) and handled in separate members of
the packet structure.  To implement a 48-bit systim on a 16-bit processor,
for example, systim is split into an upper 16 bits (usystim), medium 16 bits
(msystim), and lower 16 bits (lsystim) and pk_tim packet includes each
separated members of systim.  To implement a 48-bit systim on a 32-bit
processor, systim is split into an upper 16 bits (usystim) and lower 32 bits
(lsystim) and pk_tim packet includes each separated members of systim.

[Supplemental Information]

Modification of the system clock with set_tim during the system operation may
cause an erratic timing operation of a waiting task or a timer handler (cyclic
or alarm).  Operations in this case are implementation dependent.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (pk_tim is invalid or the time setting is invalid)

[Differences from uITRON 2.0 and ITRON2 Specifications]

Interface is now configured in packets.

System calls checking for timeouts are now separated.  Since this has
resulted in the elimination of the E_TNOSPT error, E_TNOSPT is no longer
returned to set_tim.  An E_RFSN error indicating that whole system call is not
supported will result if no timer is available since any support would be
meaningless in such a case.  The same is true for all other time management
system calls.


========================================================================
|| [S] || get_tim || Get System Clock
========================================================================
  get_tim:        Get Time

[Parameters]
  SYSTIME *pk_tim Packet address representing current time

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_tim members)-
  SYSTIME systim  CurrentSystemTime

[C Language Interface]
  ER ercd = get_tim ( SYSTIME *pk_tim );

[Description]

This system call gets the current value of the system clock and returns it in
the return parameter systim.

Although the bit width of the system clock and systim are implementation
dependent, 48 bits are recommended.  It is recommended that the system clock
give the number of milliseconds elapsed since January 1, 1985, 00:00:00 am
(GMT).

If the number of bits required to represent systim is larger than that used
for an integer (int data type in C language) and the processor cannot handle
systim as a single data, systim may be split into high order and low order
parts (and even medium order if required) and handled in separate members of
the packet structure.  To implement a 48-bit systim on a 16-bit processor,
for example, systim is split into an upper 16 bits (usystim), medium 16 bits
(msystim), and lower 16 bits (lsystim) and pk_tim packet includes each
separated members of systim.  To implement a 48-bit systim on a 32-bit
processor, systim is split into an upper 16 bits (usystim) and lower 32 bits
(lsystim) and pk_tim packet includes each separated members of systim.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (pk_tim is invalid)


========================================================================
|| [S] || dly_tsk || Delay Task
========================================================================
  dly_tsk:        Delay Task

[Parameters]
  DLYTIME dlytim  DelayTime

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = dly_tsk ( DLYTIME dlytim );

[Description]

This system call temporarily halts the execution of the task issuing the call,
and makes it enter the time elapse wait state.  The task halts execution for
the amount of time defined by dlytim.

Time elapse wait is one type of WAIT state, and may be released by rel_wai.

The time count continues even if the task issuing this system call later
enters SUSPEND state (WAIT-SUSPEND state) as well.

Although the time unit for dlytim is recommended to be the same as that for
the system clock, sometimes a longer time unit than the system clock (1 ms
is recommended) may be used in the case of processors with smaller bit
widths (8 or 16 bits).

[Supplemental Information]

Unlike tslp_tsk, this system call completes normally when the issuing task
is delayed specified time.  The task will not be released from its WAIT
state even if wup_tsk is issued during the delay.  Dly_tsk finishes before
the full delay time has elapsed only when ter_tsk or rel_wai are issued.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory
  E_PAR     Parameter error (dlytim < 0)
  E_CTX     Context error (issued from task-independent portions or a
            task in dispatch disabled state)
  E_RLWAI   WAIT state was forcibly released (rel_wai was received while
            waiting)


========================================================================
|| [E] || def_cyc || Define Cyclic Handler
========================================================================
  def_cyc:        Define Cyclic Handler

[Parameters]
  HNO     cycno   CyclicHandlerNumber
  T_DCYC *pk_dcyc Packet to Define CyclicHandler
 -(pk_dcyc members)-
  VP      exinf   ExtendedInformation
  ATR     cycatr  CyclicHandlerAttributes
  FP      cychdr  CyclicHandlerAddress
  UINT    cycact  CyclicHandlerActivation
  CYCTIME cyctim  CycleTime
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = def_cyc ( HNO cycno, T_DCYC *pk_dcyc ) ;

[Description]

This system call defines a cyclic handler specified by cycno.  A cyclic
handler is a task-independent handler which runs periodically at the fixed
cycle specified.

Cycno represents a number used to identify cyclic handlers when there is more
than one.  It is used by system calls such as act_cyc and ref_cyc.

Exinf may be used freely by the user for including extended information about
the cyclic handler to be defined.  Information set here may be accessed by
ref_cyc. If a larger region is desired for including user information, or if
the user wishes to change the contents of this information, the usr should
allocate memory area and set the address of this area to exinf.  The OS does
not take care of the contents of exinf.

The lower bits of cycatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of cycatr may be specified as follows.

        cycatr := (TA_ASM || TA_HLNG)

        TA_ASM  The handler being defined is written in assembler
        TA_HLNG The handler being defined is written in a high-level language

The format of cycatr is shown in Figure 27.




   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - H|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - H|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - H|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           cycatr is 16 bits or less.
        2. H=1 indicates that the cyclic handler being defined is written
           in a high-level language (TA_HLNG).

                           Figure 27 cycatr Format


Cycadr is the start address of the cyclic handler.  Cyctim is the time
interval at which the handler is periodically started.  Cycact temporarily
selects ON/OFF for the cyclic handler.  Cycact may be specified as follows.

        cycact := (TCY_OFF || TCY_ON)

        TCY_OFF H'0...00        Do not invoke the cyclic handler
        TCY_ON  H'0...01        Invoke the cyclic handler

Cycact = TCY_OFF indicates that the cyclic handler is not invoked temporarily.
The handler will not be executed in this state.

The bit width of cyctim is implementation dependent.  Although 48 bits are
recommended just as the system clock, a smaller bit width may sometimes be
used.

If the number of bits required to represent cyctim is larger than that used
for an integer (int data type in C language) and the processor cannot handle
cyctim as a single data, cyctim may be split into high order and low order
parts (and even medium order if required) and handled in separate members of
the packet structure.  To implement a 48-bit cyctim on a 16-bit processor,
for example, cyctim is split into an upper 16 bits (ucyctim), medium 16 bits
(mcyctim), and lower 16 bits (lcyctim) and pk_dcyc packet includes each
separated members of cyctim.  To implement a 48-bit cyctim on a 32-bit
processor, cyctim is split into an upper 16 bits (ucyctim) and lower 32 bits
(lcyctim) and pk_dcyc packet includes each separated members of cyctim.

Cyclic handlers and alarm handlers are generically called timer handlers.
Timer handlers terminate when the ret_tmr system call is issued.  The user
must save any registers used by the timer handler.

Even when a system call issued in a cyclic handler results in a situation where
a task in RUN state should go to another state and another task should go to
RUN state, no task dispatching takes place while the cyclic handler is running.
Even when dispatching is required, the cyclic handler must finish executing
before dispatching.  In other words, even if a dispatch request occurs while a
cyclic handler is executing, it is not processed immediately, but rather that
dispatching is delayed until the cyclic handler finishes.  This is called
"delayed dispatching".

Cyclic handlers are executed as task-independent portions.  As such, a
system call, which may result in a WAIT state or which specifies the issuing
task, cannot be executed from a cyclic handler.

System calls which may be available from a cyclic handler are
implementation dependent.  However, a method must be provided for waking up
tasks (releasing tasks from WAIT state) using system calls which can be
issued from a cyclic handler.  The following restrictions may be provided
depending upon implementation-dependent specifications.

  - A system call may be restricted such that it is allowed to be issued only
    from task-independent portions (such as a cyclic handler).

  - Performance may be increased by making separate versions of system
    calls depending on whether they are issued from task portions or task-
    independent portions.  In this case, the name of the system call issued
    from task-independent portions must be i???_??? when the equivalent
    system call issued from task portions is ???_???.
    For example, if there is a special version of sig_sem, which returns
    semaphore resources, has been provided for execution within a cyclic
    handler.  The name of this system call would then be isig_sem.

Specifying pk_dcyc = NADR = -1 cancels the definition of the previously
defined cyclic handler.

It is possible to redefine a cyclic handler for the cyclic handler number
already defined.  When redefining a cyclic handler, it is not necessary to
first cancel the handler definition which has that number.  No error will
result if a new cyclic handler is defined using a cycno for which a handler
has already been defined.

Cyclic handlers do not necessarily have to be defined dynamically using this
system call.  Just as with the creation of objects, handlers may be defined
statically at system startup.

[Supplemental Information]

Execution of def_cyc clears the interval counter.  The handler will be
invoked first exactly after the time interval specified by cyctim has elapsed.

Since there is no specification to def_cyc concerning how many times to invoke
the handler, a cyclic handler will be run cyclically until either its
definition is cancelled or it is deactivated by act_cyc with cycact = TCY_OFF.

Cyclic handlers, being not objects, are not provided with ID number.  Multiple
handlers are identified using a handler number (cycno).

If more than one timer handler and/or interrupt handler are to be invoke at
the same time, it is implementation dependent whether they may either be run
serially (the execution of one handler will start after the first one
finishes) or they may be run nested (the execution of one handler will be
suspended, the other handler will execute, and when the other handler
finishes, the first handler will resume execution).  In both case, the
principle of delayed dispatching applies since both timer handlers and
interrupt handlers are considered task-independent portions.

Although the standard packet format of pk_dcyc (the order and number of bits
associated with each member) is as stated above, packet format may be changed
as necessary for implementation on various systems as long as the
compatibility with other systems is not a problem.

When TA_HLNG is specified, a high-level language environment setting
program (a high-level language support routine) is called before branching
to the cychdr address.  The least significant bit (LSB) of the system
attribute bits is used for this specification.

In an implementation allowing def_cyc to be issued by a timer handler, it is
possible to redefine a cyclic handler with the same cyclic handler number in
the handler.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block cannot be allocated)
  E_RSATR   Reserved attribute (cycatr was invalid or could not be used)
  E_PAR     Parameter error (cycno, pk_dcyc, cychdr, cycact and/or cyctim is
            invalid or could not be used)

[Rationale]

The cyclic handler and alarm handler are the task-independent portion
because of the possibilities in which the task having issued def_cyc or
def_alm may exit or be deleted while the definition for the cyclic handler
or the alarm handler is still effective.


========================================================================
|| [E] || act_cyc || Activate Cyclic Handler
========================================================================
  act_cyc:        Activate Cyclic Handler

[Parameters]
  HNO     cycno   CyclicHandlerNumber
  UINT    cycact  CyclicHandlerActivation

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = act_cyc ( HNO cycno, UINT cycact ) ;

[Description]

This system call changes the activation (cycact) of the specified cyclic
handler.

cycact may be specified as follows.

        cycact := (TCY_OFF || TCY_ON) | [TCY_INI]

        TCY_OFF H'0...00        Do not invoke the cyclic handler
        TCY_ON  H'0...01        Invoke the cyclic handler
        TCY_INI H'0...02        Initialize the interval counter of
                                the cyclic handler

Specifying cycact = TCY_OFF deactivates the cyclic handler regardless of the
value of the interval counter.  The handler will not be invoked if it reaches
the specified time interval while TCY_OFF is specified.

Specifying cycact = TCY_ON activates the cyclic handler regardless of the
value of the interval counter.  Since the OS still continues counting of
the specified time interval even while the handler is deactivated, the
amount of time before the cyclic handler is invoked again after act_cyc has
been executed is varied.

Specifying cycact = (TCY_ON | TCY_INI) activates the cyclic handler and also
clears its interval counter.  In other words, after executing act_cyc with
cycact = (TCY_ON | TCY_INI), the cyclic handler will be invoked for the
first time exactly after the specified time interval (cyctim) has elapsed.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOEXS   Object does not exist (the cyclic handler for cycno is undefined)
  E_PAR     Parameter error (cycno was invalid or could not be used, cycact is
            invalid)


========================================================================
|| [E] || ref_cyc || Reference Cyclic Handler Status
========================================================================
  ref_cyc:        Reference Cyclic Handler Status

[Parameters]
  HNO     cycno   CyclicHandlerNumber
  T_RCYC *pk_rcyc Packet to ReferenceCyclicHandler

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rcyc members)-
  VP      exinf   ExtendedInformation
  CYCTIME lfttim  LeftTime
  UINT    cycact  CyclicHandlerActivation
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_cyc ( T_RCYC *pk_rcyc, HNO cycno ) ;

[Description]

This system call refers to the state of the cyclic handler specified by cycno,
and returns the cyclic handler's activation state (cycact), the remaining
time until the cyclic handler is invoked next (lfttim), and its extended
information (exinf).

TCY_ON or TCY_OFF is returned as cycact.  TCY_INI is never returned.

An E_NOEXS error will be returned to ref_cyc if the cyclic handler for cycno
is not defined.

[Supplemental Information]

Depending on the implementation, additional information besides cycact and
lfttim (such as the cycle time, cyctim) may also be referred.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOEXS   Object does not exist (the cyclic handler for cycno is undefined)
  E_PAR     Parameter error (cycno was invalid or could not be used, the packet
            address for the return parameters could not be used)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from cyh_sts to ref_cyc.

Packet interface is now used.


========================================================================
|| [E] || def_alm || Define Alarm Handler
========================================================================
  def_alm:        Define Alarm Handler

[Parameters]
  HNO     almno   AlarmHandlerNumber
  T_DALM *pk_dalm Packet to Define AlarmHandler
 -(pk_dalm members)-
  VP      exinf   ExtendedInformation
  ATR     almatr  AlarmHandlerAttributes
  FP      almhdr  AlarmHandlerAddress
  UINT    tmmode  TimeMode
  ALMTIME almtim  AlarmTime

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = def_alm ( HNO almno, T_DALM *pk_dalm ) ;

[Description]

This system call defines an alarm handler specified by almno.  A alarm
handler is a task-independent handler which runs at the time specified.

Almno represents a number used to identify alarm handlers when there is more
than one.  It is used by system calls like ref_alm.

Exinf may be used freely by the user for including extended information about
the alarm handler to be defined.  Information set here may be accessed by
ref_alm. If a larger region is desired for including user information, or if
the user wishes to change the contents of this information, the usr should
allocate memory area and set the address of this area to exinf.  The OS does
not take care of the contents of exinf.

The lower bits of almatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of almatr may be specified as follows.

        almatr := (TA_ASM || TA_HLNG)

        TA_ASM  The handler of interest is written in assembler
        TA_HLNG The handler of interest is written in a high-level language

The format of almatr is shown in Figure 28.




   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - H|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - H|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - H|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           almatr is 16 bits or less.
        2. H=1 indicates that the alarm handler being defined is written
           in a high-level language (TA_HLNG).

                           Figure 28 almatr Format


Almhdr is the start address of the alarm handler.  Almtim is the time when the
handler will be invoked.  Tmmode can be specified as follows to indicate
whether to start the handler at an absolute time or a relative time.

        tmmode := (TTM_ABS || TTM_REL)

        TTM_ABS H'0...00        Specifies an absolute time
        TTM_REL H'0...01        Specifies a relative time

If TTM_ABS is specified, the alarm handler will be started at the clock time
specified by almtim.  If TTM_REL is specified, the alarm handler will be
started after the amount of time specified by almtim has elapsed.  An E_PAR
error will result if almtim is specified as time of the day which has already
passed (or if almtim is less than zero under TTM_REL).

The bit width of almtim is implementation dependent.  Although 48 bits are
recommended just as the system clock, a smaller bit width may sometimes be
used.

If the number of bits required to represent almtim is larger than that used
for an integer (int data type in C language) and the processor cannot handle
almtim as a single data, almtim may be split into high order and low order
parts (and even medium order if required) and handled in separate members of
the packet structure.  To implement a 48-bit almtim on a 16-bit processor,
for example, almtim is split into an upper 16 bits (ualmtim), medium 16 bits
(malmtim), and lower 16 bits (lalmtim) and pk_dalm packet includes each
separated members of almtim.  To implement a 48-bit almtim on a 32-bit
processor, almtim is split into an upper 16 bits (ualmtim) and lower 32 bits
(lalmtim) and pk_dalm packet includes each separated members of almtim.

Cyclic handlers and alarm handlers are generically called timer handlers.
Timer handlers terminate when the ret_tmr system call is issued.  The user
must save any registers used by the timer handler.

Even when a system call issued in an alarm handler results in a situation where
a task in RUN state should go to another state and another task should go to
RUN state, no task dispatching takes place while the alarm handler is running.
Even when dispatching is required, the alarm handler must finish executing
before dispatching.  In other words, even if a dispatch request occurs while an
alarm handler is executing, it is not processed immediately, but rather that
dispatching is delayed until the alarm handler finishes.  This is called
"delayed dispatching".

Alarm handlers are executed as task-independent portions.  As such, a
system call, which may result in a WAIT state or which specifies the issuing
task, cannot be executed from an alarm handler.

System calls which may be available from an alarm handler are
implementation dependent.  However, a method must be provided for waking up
tasks (releasing tasks from WAIT state) using system calls which can be
issued from an alarm handler.  The following restrictions may be provided
depending upon implementation-dependent specifications.

  - A system call may be restricted such that it is allowed to be issued only
    from task-independent portions (such as an alarm handler).

  - Performance may be increased by making separate versions of system
    calls depending on whether they are issued from task portions or task-
    independent portions.  In this case, the name of the system call issued
    from task-independent portions must be i???_??? when the equivalent
    system call issued from task portions is ???_???.
    For example, if there is a special version of sig_sem, which returns
    semaphore resources, has been provided for execution within an alarm
    handler.  The name of this system call would then be isig_sem.

Specifying pk_dalm = NADR = -1 cancels the definition of the previously
defined alarm handler.

It is possible to redefine an alarm handler for the alarm handler number
already defined.  When redefining an alarm handler, it is not necessary to
first cancel the handler definition which has that number.  No error will
result if a new alarm handler is defined using a almno for which a handler
has already been defined.

Alarm handlers do not necessarily have to be defined dynamically using this
system call.  Just as with the creation of objects, handlers may be defined
statically at system startup.

The definition of an alarm handler is canceled automatically when the specified
time comes and that the handler is started.

[Supplemental Information]

It is possible to implement a function similar to a timeout by issuing a
rel_wai (or irel_wai) on a waiting task to forcibly release that task's WAIT
state from an alarm handler.

Alarm handlers, being not objects, allow multiple handlers to be  identified
using a handler number (almno), not an ID number.

If more than one timer handler and/or interrupt handler are to be invoke at
the same time, it is implementation dependent whether they may either be run
serially (the execution of one handler will start after the first one
finishes) or they may be run nested (the execution of one handler will be
suspended, the other handler will execute, and when the other handler
finishes, the first handler will resume execution).  In both case, the
principle of delayed dispatching applies since both timer handlers and
interrupt handlers are considered task-independent portions.
 
Although the standard packet format of pk_dalm (the order and number of bits
associated with each member) is as stated above, packet format may be changed
as necessary for implementation on various systems as long as the
compatibility with other systems is not a problem.
 
When TA_HLNG is specified, a high-level language environment setting
program (a high-level language support routine) is called before branching
to the almhdr address.  The least significant bit (LSB) of the system
attribute bits is used for this specification.

At the time an alarm handler is started, the definition of that handler is
considered as already canceled.  Thus if ref_alm is used to refer to
information on the started handler in the handler, an E_NOEXS error will
result.  In an implementation allowing def_alm to be issued by a timer handler,
it is possible to redefine an alarm handler with the same alarm handler number
in the handler.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block cannot be allocated)
  E_RSATR   Reserved attribute (almatr was invalid or could not be used)
  E_PAR     Parameter error (almno, pk_dalm, almhdr, tmmode and/or almtim is
            invalid or could not be used)


========================================================================
|| [E] || ref_alm || Reference Alarm Handler Status
========================================================================
  ref_alm:        Reference Alarm Handler Status

[Parameters]
  HNO     almno   AlarmHandlerNumber
  T_RALM *pk_ralm Packet to ReferenceAlarmHandler

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_ralm members)-
  VP      exinf   ExtendedInformation
  ALMTIME lfttim  Time Left before Handler Runs
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_alm ( T_RALM *pk_ralm, HNO almno ) ;

[Description]

This system call refers to the state of the alarm handler specified by almno,
and returns the remaining time until the alarm handler is invoked (lfttim),
and its extended information (exinf).

An E_NOEXS error will result if the alarm handler specified by almno to
ref_alm is not defined.

[Supplemental Information]

Depending on the implementation, additional information besides lfttim (such
as alarm handler attributes, almatr) may also be referred.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOEXS   Object does not exist (the alarm handler specified by almno does
            not exist)
  E_PAR     Parameter error (almno was invalid or could not be used, the packet
            address for the return parameters could not be used)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The name of this system call has been changed from alh_sts to ref_alm.


========================================================================
|| [E] || ret_tmr || Return from Timer Handler
========================================================================
  ret_tmr:        Return from Timer Handler

[Parameters]
  None

[Return Parameters]
  Not returned to the context issuing the system call.

[C Language Interface]
  void ret_tmr ( ) ;

[Description]

This system call causes the invoked timer handler (cyclic or alarm) to finish.

Under ITRON and uITRON specifications, dispatching is not performed during
the execution of a timer handler even if system calls in the timer handler
request dispatching.  Instead such dispatching is delayed until the timer
handler finishes by issuing ret_tmr.  This is the principle of delayed
dispatching.  For this reason, ret_tmr processes any dispatch requests caused
by the issuing of system calls from the timer handler.

Code at the beginning and end of a timer handler must save and restore any
registers used by the timer handler.  For this reason, sometimes ret_tmr
cannot use the function code because the status of the stack and registers
at the time ret_tmr is executed must be the same as before the timer handler
started.  In this case, ret_tmr must be implemented using a trap instruction
of another vector different from that used for other system calls.

[Supplemental Information]

Ret_tmr is a system call which does not return any parameters to the original
issuing context.  Accordingly, even if an error code is returned due to the
detection of some error, the handlers making this system call do not usually
perform any error checking, and it is in fact possible that a program could
run out of control.  For this reason, even if an error is detected upon making
this system call, it is not returned to the issuer of the system call.  If
information on detected errors is required, it should be left in a message
buffer used as an error log.

Depending on the method of configuring the OS, it may be possible to implement
this system call using an assembler return from interrupt instruction or
return from subroutine instruction.  Under this implementation, the assembler
return instructions may be interpreted as realizing the ret_tmr system call.

Depending on the implementation, if the timer handler is written in a high-
level language, the high-level language's return instruction (such as C's
return statement or function end) allows automatic execution of ret_tmr
(through a high-level language support routine).

Operations are not guaranteed when ret_tmr is executed from other functions
or subroutines called from an timer handler.  Those operations include
returning from the timer handler as dictated by a system call, returning
to where the functions or subroutines are called, and reporting of errors.

E_CTX error checking when ret_tmr is called from a interrupt handler is
implementation dependent.  Depending on the implementation, control may return
from a different type of handler.

If ret_tmr is implemented using an assembler return from interrupt instruction
or a return from subroutine instruction, manipulating the stack becomes
difficult when this system call is invoked from a high-level language.  So,
the specification allows an implementation to interpret ret_tmr written in the
high-level language simply as a return statement, and have the corresponding
assembler return from interrupt instruction or return from subroutine
instruction execute in the high-level language support routine to which
control is returned.

It is necessary to execute ret_tmr at the top level of the timer handler
(rather than from a called function or subroutine) when writing timer
handlers which can be executed on all implementations of the OS (when writing
programs with broad compatibility).

Although both ret_tmr and ret_int are used for returning from task-
independent portions, they are not same because of difference in its OS
involvement when they start.  In other words, ret_int represents a return
from a task-independent handler directly started by CPU hardware, while
ret_tmr represents a return from a task-independent handler started by the OS.

[Error Codes]
  * No return is made to the context issuing the system call even if an error,
    as shown below, is detected.  Error codes therefore cannot be returned
    directly as a return parameter of the system call.  The behavior on error
    detection is implementation dependent.

  E_CTX     Context error (issued from portions other than timer
            handlers (implementation dependent))


****************************************************************************
***    3.8 System Management Functions                                   ***
****************************************************************************

System management functions are used to set and refer the overall system
environment.

These system calls include functions for getting the OS version,
referencing the system's dynamic status, referencing configuration
information (the system's static status), defining user-defined
system calls (extended SVC handlers), and defining exception handlers
such as division by zero.  System calls for referring configuration
information (ref_cfg), for defining extended SVC handlers (def_svc), and
for defining exception handlers (def_exc), are CPU-dependent [level C].

[Differences from uITRON 2.0 and ITRON2 Specifications]

Exception management functions have been included in the system management
functions.  The support level of def_exc, for defining exception handlers, and
def_svc, for defining extended SVC handlers, has been changed to CPU-dependent
[level C].


========================================================================
|| [R] || get_ver || Get Version Information
========================================================================
  get_ver:        Get Version Information

[Parameters]
  T_VER   *pk_ver Packet address representing Version Information

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_ver members)-
  UH      maker   OS Maker
  UH      id      Identification Number of the OS
  UH      spver   ITRON or uITRON Specification Version Number
  UH      prver   OS Product Version Number
  UH      prno[4] Product Number (Product Management Information)
  UH      cpu     CPU Information
  UH      var     Variation Descriptor

[C Language Interface]
  ER ercd = get_ver ( T_VER *pk_ver );

[Description]

This system call gets informations of the maker of the ITRON or uITRON
specification OS currently executing, the identification number of the OS,
the ITRON or uITRON specification version number which the OS is based on,
and the version number of the OS product.

The packet format and structure members used to get version information is
nearly identical for each of ITRON1, ITRON2, uITRON 2.0, uITRON 3.0 and BTRON
specifications.  The format is essentially the same even for processors
having different bit widths.

Maker represents the maker of the OS.  The maker format is shown in Figure 29
(a).  For details on the assignment of maker codes, see the appendix of this
document.



 [maker]
    +---------------+---------------+---------------+---------------+
    |                             MAKER                             |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

                          Figure 29(a) maker Format


Id gives the identification number used to identify the OS type.  The id
format is shown in Figure 29(b).  Id may be used to identify different
versions of the OS such as supporting MMU and not supporting MMU made by
the same maker.

Conventions for assigning id numbers may be up to each maker.  However, since
product identification is carried out based solely on this number, each maker
should carefully study how numbers are going to be assigned and select a rule-
based convention.



 [id]
    +---------------+---------------+---------------+---------------+
    |                              id                               |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

                            Figure 29(b) id Format


Spver identifies OS or CPU type as ITRON, uITRON, BTRON, CTRON specification
or TRON-specification chip and gives the version number of the specification
which the product is based on.  The spver format is shown in Figure 29(c).

For example, spver would appear as follows for a version corresponding to
uITRON 3.0 specification Ver 3.02.

        MAGIC   = H'5   (uITRON specification)
        SpecVer = H'302 (Ver 3.02)
        spver   = H'5302

Spver would appear as follows for a version corresponding to the draft version
Ver 3.A1.xx of uITRON 3.0 specification.

        MAGIC   = H'5   (uITRON specification)
        SpecVer = H'3A1 (Ver 3.A1)
        spver   = H'53A1



 [spver]
    +---------------+---------------+---------------+---------------+
    |      MAGIC    |                    SpecVer                    |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
    MAGIC:    Number identifying the TRON series
              H' 0  TRON common (such as TAD)
              H' 1  ITRON1, ITRON2 specification
              H' 2  BTRON specification
              H' 3  CTRON specification
              H' 4  Reserved
              H' 5  uITRON specification
              H' 6  uBTRON specification

    SpecVer:  The version number of the TRON specification documents on
              which this product is based.  Entered as a 3-digit BCD code
              in packed format.
              When draft versions are specified, the second digit may be
              A, B or C.  In this case, the hexadecimal code corresponding
              to A, B or C is used.

                          Figure 29(c) spver Format


Prver gives the version number of the internal implementation.  The prver
format is shown in Figure 29(d).  MAJOR gives the major version number, while
MINOR gives the minor version number.  Vendors are free to select the method
of assigning these numbers.



 [prver]
    +---------------+---------------+---------------+---------------+
    |             MAJOR             |            MINOR              |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

                          Figure 29(d) prver Format


Prno is a parameter which may be freely used by each maker to enter product
management information or a product number.  The prno format is shown in
Figure 29(e).



 [prno]
    +---------------+---------------+---------------+---------------+
    |                            prno[0]                            |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
    +---------------+---------------+---------------+---------------+
    |                            prno[1]                            |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
    +---------------+---------------+---------------+---------------+
    |                            prno[2]                            |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
    +---------------+---------------+---------------+---------------+
    |                            prno[3]                            |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

                           Figure 29(e) prno Format


Cpu indicates the processor which executes the OS.  The cpu format is shown in
Figure 29(f).  Some processors use the format given in Figure 29(f)(1).  The
format given in Figure 29(f)(2) is used for all other proprietary processors.

The assignment of the CPU1 code in the format given in Figure 29(f)(1) is
common to ITRON, uITRON, and BTRON specifications.  The same number is also
applicable to the CPU type in the standard object format of BTRON
specification operating systems implemented on TRON-specification chips.

When using the format given in Figure 29(f)(2), The MAKER1 code given in the
format in Figure 29(f)(1) corresponds to the lower 8 bits from the MAKER value
described previously.  Each vendor selects how the CPU2 code is assigned.

For details on how the CPU codes are assigned, see the appendix of this
document.



 [cpu]
     +---------------+---------------+---------------+---------------+
 (1) | 0   0   0   0   0   0   0   0 |              CPU1             |
     +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
     +---------------+---------------+---------------+---------------+
 (2) |             MAKER1            |              CPU2             |
     +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

                           Figure 29(f) cpu Format


Var gives an indication of which functions are available on this OS.  The var
format is shown in Figure 29(g).  Under the current specification, the M, V
and P fields are always filled with zeros.



 [var]
    +---------------+---+---+---+---+---+---+---+---+---+---+---+---+
    |      LEV      | - | M | V | P | - |    FIL    | - | - | - | - |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

        -:    reserved (0 is returned)

      LEV:    Kernel specification and connection function support level
              classification
              B' 0000  reserved
              B' 0001  reserved
              B' 0010  reserved
              B' 0011  reserved
              B' 0100  uITRON specification [level R]
              B' 0101  uITRON specification [level RN]
              B' 0110  uITRON specification [level RNs]
              B' 0111  uITRON specification [level RNe]
              B' 1000  uITRON specification [level S]
              B' 1001  uITRON specification reserved
              B' 1010  uITRON specification [level SN]
              B' 1011  uITRON specification [level SNe]
              B' 1100  uITRON specification [level E]
              B' 1101  reserved (uITRON specification)
              B' 1110  reserved (uITRON specification)
              B' 1111  uITRON specification [level EN]

        M:    Multiprocessor support (ITRON-MP specification)
              M=1      For tightly-coupled multiprocessors
              M=0      For single processors

        V:    Virtual memory support
              V=1      Supports virtual memory
              V=0      Does not support virtual memory

        P:    MMU support
              P=1      Supports MMU
              P=0      Does not support MMU

      FIL:    File support level classification (ITRON/FILE specification)
              B' 000   No file support
              B' 001   <<F10>> specification
              B' 010   <<F11>> specification
              B' 011 - B' 111
                       reserved

                           Figure 29(g) var Format


[Supplemental Information]

OS product type is identified using id.  Information given by var and cpu is
provided only for convenience.  This means that products having the same id
value but different var and cpu values must not exist.

SpecVer returned by invoking get_ver returns the upper three digits of the
specifications version number.  Since digits beyond the first three are used
to indicate notational changes such as revisions due to misprints, they are
not returned by get_ver.  The upper three digits of the specifications version
number should be sufficient in terms of correspondence to the description of
specifications.

When an operating systems is implemented based on draft versions of
specifications, the second digit of SpecVer will be A, B or C.  Note that in
such cases the release order of specifications and the relationship of numbers
of SpecVer will not necessarily match.  For example, while specifications may
be released in the order:

    Ver 3.A1 -> Ver3.A2 -> Ver3.B1 -> Ver3.C1 -> Ver 3.00 -> Ver 3.01 -> ...

the sequence of the number reverses at the point where specifications change
from draft to official versions (Ver 3.Cx will be updated to Ver 3.00).

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The detailed description of how maker codes and CPU codes are assigned has
been moved into the appendix.

The bit width of the LEV field of var has been increased, and codes have been
assigned for all levels, [R], [S], [E] and the connection function.


========================================================================
|| [E] || ref_sys || Reference System Status
========================================================================
  ref_sys:        Reference System Status

[Parameters]
  T_RSYS *pk_rsys PacketAddress to ReferenceSystem

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rsys members)-
  INT     sysstat SystemState
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_sys ( T_RSYS *pk_rsys ) ;

[Description]

This system call refers the execution state of the CPU and OS on the
requesting node, and returns information such as whether dispatching is
disabled and whether a task-independent portion is executing.

Sysstat may be the following values.

        sysstat := (TSS_TSK || TSS_DDSP || TSS_LOC || TSS_INDP)

        TSS_TSK   0     A task portion is executing and dispatching is enabled
                        (normal state)
        TSS_DDSP  1     A task portion is executing but dispatching is
                        disabled because dis_dsp has been executed
        TSS_LOC   3     A task portion is executing but both interrupt and
                        dispatching are disabled because loc_cpu has been
                        executed
        TSS_INDP  4     A task-independent portion (such as an interrupt or
                        timer handler) is executing

This system call, when implemented, should be made available from interrupt
and timer handlers as well as from tasks.

[Supplemental Information]

The relationship between the interrupt disable state and the associated value
returned by sysstat is processor dependent.  If, for example, dis_int or
chg_iXX is executed during dispatch disable state (TSS_DDSP) caused by
executing dis_dsp, the value returned in sysstat to ref_sys will either be
TSS_DDSP or TSS_LOC depending on the implementation.  The value returned by
sysstat to ref_sys is also implementation dependent in cases where interrupt
may be disabled by directly setting the interrupt mask (interrupt disable
flag) in the PSW of the processor instead of using a system call.  This is
because the specifications of dis_int and chg_iXX are dependent on the
interrupt-related architecture of the processor.

Depending on the implementation, additional information besides sysstat such
as the following may also be referred.

    iXXXX       interrupt disable state or interrupt mask (level or priority)
    runtskid    The ID of the currently executing task
    runtskpri   The priority of the currently executing task
    ring        Execution ring (privilege mode)
    psw         PSW value of the processor
    Other information dependent on CPU architecture

If a multiprocessor configuration is being used, ref_sys will return the
status of the processor on which the system call is issued.  Furthermore,
another system call for returning the status of other processors will be
implemented additionally.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)

[Differences from uITRON 2.0 and ITRON2 Specifications]

This system call corresponds to psw_sts under ITRON2 specification;
specification have been changed so they are no longer dependent on CPU
architecture.


========================================================================
|| [C] || ref_cfg || Reference Configuration Information
========================================================================
  ref_cfg:        Reference Configuration Information

[Parameters]
  T_RCFG *pk_rcfg PacketAddress to ReferenceConfiguration

[Return Parameters]
  ER      ercd    ErrorCode
 -(pk_rcfg members)-
  (CPU and/or implementation-dependent information is returned)

[C Language Interface]
  ER ercd = ref_cfg ( T_RCFG *pk_rcfg ) ;

[Description]

This system call refers static information regarding the system and
information specified at its configuration.

Information accessible with ref_cfg is shown below.  Available information and
its details are implementation dependent.

    Information not related to the connection function:

          - The range of ID numbers for each object
          - The maximum values for suscnt, wupcnt, etc.
          - Memory map outline and amount of usable memory
          - Information related to peripheral chips and I/O devices
          - The time unit used for SYSTIME, DLYTIME, TMO, etc.

    Information related to the connection function:

          - Information related to location node of objects
          - Information related to routing, I/O and communications
            Information on how to send packets to each node.
            Information about the correspondence of packet destination node
            to I/O devices, I/O handlers and low-level protocols.
          - Timeout specification for connection function response wait state.
            The timeout specification giving how long to wait for a reply
            packet (TR packet or TA packet) to be returned when processing is
            requested to another node.
            A same timeout specification may be used regardless of the type of
            system call to be issued; it is recommended, however, that the
            specification can be made separately for each target node.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)

[Differences from uITRON 2.0 and ITRON2 Specifications]

This is a new system call.


========================================================================
|| [C] || def_svc || Define Extended SVC Handler
========================================================================
  def_svc:        Define SupervisorCallHandler

[Parameters]
  FN      s_fncd  SVCFunctionCode
  T_DSVC *pk_dsvc Packet to Define SVCHandler
 -(pk_dsvc members)-
  ATR     svcatr  SVCHandlerAttributes
  FP      svchdr  SVCHandlerAddress
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode

[C Language Interface]
  ER ercd = def_svc ( FN s_fncd, T_DSVC *pk_dsvc ) ;

[Description]

This system call defines an extended system call handler (called an "extended
SVC handler") for the function code given by s_fncd.  Specifically, the system
call defines a correspondence between the function code given by s_fncd and
the extended SVC handler address svchdr and associated attributes.  Using
def_svc allows execution of user-defined extended SVC handlers based on
the same interface with the system calls of uITRON 3.0 specification.

The lower bits of svcatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of svcatr may be specified as follows.

        svcatr := (TA_ASM || TA_HLNG)

        TA_ASM  The handler of interest is written in assembler
        TA_HLNG The handler of interest is written in a high-level language

The format of svcatr is shown in Figure 30.




   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - H|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - H|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - H|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           svcatr is 16 bits or less.
        2. H=1 indicates that the SVC handler being defined is written
           in a high-level language (TA_HLNG).

                           Figure 30 svcatr Format


Availability of extended SVC handlers and details of their operation are
implementation dependent.  Specifically, the following considerations are
implementation dependent.

  - How to pass parameters
  - Saving of general-purpose registers
  - How to return from extended SVC handlers
  - Operations when extended SVC handlers are nested
  - Whether extended SVC handlers can be issued from task-independent portions
  - Indivisibility of extended SVC handlers
  - Operations when an extended SVC handler is redefined

[Supplemental Information]

The standard packet format of pk_dsvc (the order and number of bits associated
with each member) is as stated above; packet format may be changed as
necessary for implementation on various systems as long as the compatibility
with other systems is not a problem.

In general, extended SVC handlers are executed under relatively high privilege
levels (from the inner ring, in privileged mode, or in supervisor mode).  Note
that even when executed from user tasks having a tskid greater than
zero, extended SVC handlers may access system objects having IDs less than
zero.  No E_OACV error will result in this case.

When TA_HLNG is specified, a high-level language environment setting
program (a high-level language support routine) is called before branching
to the svchdr address.  The least significant bit (LSB) of the system
attribute bits is used for this specification.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block cannot be allocated)
  E_RSATR   Reserved attribute (svcatr was invalid or could not be used)
  E_PAR     Parameter error (s_fncd, pk_dsvc and/or svchdr is invalid or could
            not be used)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The extended SVC handler feature is now entirely implementation dependent.


========================================================================
|| [C] || def_exc || Define Exception Handler
========================================================================
  def_exc:        Define Exception Handler

[Parameters]
  INT     exckind ExceptionKind
  T_DEXC *pk_dexc Packet to Define ExceptionHandler
 -(pk_dexc members)-
  ATR     excatr  ExceptionHandlerAttributes
  FP      exchdr  ExceptionHandlerAddress
  (CPU and/or implementation-dependent information may also be included)

[Return Parameters]
  ER      ercd    ErrorCode
[C Language Interface]
  ER ercd = def_exc ( UINT exckind, T_DEXC *pk_dexc ) ;

[Description]

This system call defines an exception handler for the exception type given by
exckind.  An exception handler is started by the OS to cope with the abnormal
situations including CPU exceptions such as division by zero or system errors.

Exckind identifies the following types of exception causes.

    CPU exceptions:
        Memory access errors
        Division by zero and invalid parameters
        Execution of an undefined instruction
        Execution of a privileged instruction

    Task errors:
        Abnormal termination upon issuing ter_tsk (termination handler)

    System errors:
        Unrecoverable fatal error
        Critical error with no place to report error status
        Detection of data inconsistencies during OS execution
        Critical errors during execution of task-independent portions

It is implementation dependent as to how to classify the above exception
causes, and how exception handlers for them are defined.  All of the above
exceptions may not be provided with exception handlers for definition.
The correspondence between the above exceptions and the actual exckind code
is also implementation dependent.

The lower bits of excatr represent system attributes, while the upper bits
represent implementation-dependent attributes.  The system attribute part
of excatr may be specified as follows.

        excatr := (TA_ASM || TA_HLNG)

        TA_ASM  The handler of interest is written in assembler
        TA_HLNG The handler of interest is written in a high-level language

The format of excatr is shown in Figure 31.



   Most Significant Bits                             Least Significant Bits
      +---------------+---------------+---------------+---------------+
32-bit|   Implementation-Dependent    |       System Attributes       |
 ATR  |           Attributes          |                - - - - - - - H|
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                  Most Significant        Least Significant
                                  Bits                    Bits
                                      +---------------+---------------+
                                      |Implementation-|    System     |
                                16-bit|  Dependent    |  Attributes   |
                                 ATR  |  Attributes   |- - - - - - - H|
                                      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                                                  Most          Least
                                                  Significant   Significant
                                                  Bits          Bits
                                                      +---------------+
                                                      |    System     |
                                                 8-bit|  Attributes   |
                                                  ATR |- - - - - - - H|
                                                      +-+-+-+-+-+-+-+-+

 Notes: 1. There is no clear distinction between system attributes and
           implementation-dependent attributes when the bit length of
           excatr is 16 bits or less.
        2. H=1 indicates that the exception handler being defined is
           written in a high-level language (TA_HLNG).

                           Figure 31 excatr Format


Availability of exception handlers and details of their operation are
implementation dependent.  Specifically, the following considerations are
implementation dependent.

  - The meaning of exckind codes
  - How parameters (such as error codes) are passed
  - Saving of general-purpose registers
  - How to return from exception handlers
  - Operations when exception handlers are nested
  - The scope of defined exception handlers (whether they are defined for each
    task or whether exception handlers for extended SVC handlers are separate)
  - Operations invoked from task-independent portions
  - The execution mode (privilege mode, ring or level) required for executing
    exception handlers
  - Operations when an exception handler is redefined

[Supplemental Information]

The standard packet format of pk_dexc (the order and number of bits associated
with each member) is as stated above; packet format may be changed as
necessary for implementation on various systems as long as the compatibility
with other systems is not a problem.

When TA_HLNG is specified, a high-level language environment setting
program (a high-level language support routine) is called before branching
to the exchdr address.  The least significant bit (LSB) of the system
attribute bits is used for this specification.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_NOMEM   Insufficient memory (Memory for control block cannot be allocated)
  E_RSATR   Reserved attribute (excatr was invalid or could not be used)
  E_PAR     Parameter error (exckind, pk_dexc, and/or exchdr is invalid or
            could not be used)

[Differences from uITRON 2.0 and ITRON2 Specifications]

The exception handler and termination handler features are now entirely
implementation dependent.  All functions are now included in a single system
call for defining exception handlers.

****************************************************************************
***    3.9 Network Support Functions                                     ***
****************************************************************************

Network support function provide support and management of loosely-coupled
networks connected by the connection function of uITRON 3.0 specification.
It is possible under uITRON 3.0 specification to manipulate objects on another
node using normal system calls, and there usually is little need to be aware
of nodes in this case.  Network support functions provide processing
explicitly aware of nodes.

[Differences from uITRON 2.0 and ITRON2 Specifications]

This is a new system call.


========================================================================
|| [SN] || nrea_dat || Read Data from another Node
========================================================================
  nrea_dat:       Read Data from another Node

[Parameters]
  NODE    srcnode SourceNodeNumber
  VP      srcadr  SourceAddress
  VP      dstadr  DestinationAddress (local node)
  INT     datsz   DataSize (in bytes)

[Return Parameters]
  ER      ercd    ErrorCode
  INT     reasz   ReadDataSize (in bytes)

[C Language Interface]
  ER ercd = nrea_dat ( INT *p_reasz, VP dstadr, NODE srcnode, VP srcadr, INT
                       datsz ) ;

[Description]

Data in datsz byte is transferred from the address given by srcadr on the node
specified by srcnode into the address given by dstadr on the local node.

Data size actually transferred are returned to reasz.  Reasz and datsz
should be equal when the system call is successfully executed.  Reasz will
be smaller than datsz if only part of the data can be transferred
for some reason.  In both cases, the error code E_OK will be returned.

TND_SELF = 0 for srcnode is identical to the specification of the local node.

[Supplemental Information]

An EN_PAR error will result if the bit width used on the requesting node
is larger than that used on the target node and a value not supported by the
target node is specified for srcadr or datsz.

Sometimes data may not be transferred properly if srcnode specifies the local
node and part of the source memory area overlaps part of the destination
memory area.

TND_OTHR = -1 for srcnode may specify a default remote node.  This feature is
useful when the target node of the connection function is uniquely defined
such as in a star configuration where the central node is seen from the
peripheral nodes.  The TND_OTHR = -1 specification can also be used in simple
networks where two nodes are connected by a single cable to simply represent
the other node.  Applicability of TND_OTHR specification may be dependent on
network configuration and implementation of network support function.

Note that the TND_SELF and TND_OTHR specifications may only be used in
parameters to system calls of the form n???_???.  They may not appear in
transmission packets with another node.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (dstadr and/or datsz cannot be used)
  E_CTX     Context error (issued from task-independent portions or issued
            in dispatch disabled state)
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for srcadr and/or datsz on
            the target node)


========================================================================
|| [SN] || nwri_dat || Write Data to another Node
========================================================================
  nwri_dat:       Write Data to another Node

[Parameters]
  VP      srcadr  SourceAddress (local node)
  NODE    dstnode DestinationNodeNumber
  VP      dstadr  DestinationAddress
  INT     datsz   DataSize (in bytes)

[Return Parameters]
  ER      ercd    ErrorCode
  INT     wrisz   WriteDataSize (in bytes)

[C Language Interface]
  ER ercd = nwri_dat ( INT *p_wrisz, NODE dstnode, VP dstadr, VP srcadr, INT
                       datsz ) ;

[Description]

Data in datsz bytes is transferred from the address on the local node given by
srcadr into the address given by dstadr on the node specified by dstnode.

Data size actually transferred are returned to wrisz.  Wrisz and datsz
should be equal when the system call is successfully executed.  Wrisz will
be smaller than datsz if only part of the data can be transferred
for some reason.  In both cases, the error code E_OK will be returned.

TND_SELF = 0 for dstnode is identical to the specification of the local node.

[Supplemental Information]

An EN_PAR error will result if the bit width used on the requesting node
is larger than that used on the target node and a value not supported by the
target node is specified for dstadr or datsz.

Sometimes data may not be transferred properly if dstnode specifies the local
node and part of the source memory area overlaps part of the destination
memory area.

TND_OTHR = -1 for dstnode may specify a default remote node.  This feature is
useful when the target node of the connection function is uniquely defined
such as in a star configuration where the central node is seen from the
peripheral nodes.  The TND_OTHER = -1 specification can also be used in simple
networks where two nodes are connected by a single cable to simply represent
the other node.  Applicability of TND_OTHR specification may be dependent on
network configuration and implementation of network support function.

Note that the TND_SELF and TND_OTHR specifications may only be used in
parameters to system calls of the form n???_???.  They may not appear in
transmission packets with another node.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (srcadr and/or datsz cannot be used)
  E_CTX     Context error (issued from task-independent portions or
            issued in dispatch disabled state)
  EN_PAR    A value outside the range supported by the target node and/or
            transmission packet format was specified as a parameter (a value
            outside supported range was specified for dstadr and/or datsz on
            the target node)


========================================================================
|| [SN] || nget_nod || Get Local Node Number
========================================================================
  nget_nod:       Get Local Node Number

[Parameters]
  None

[Return Parameters]
  ER      ercd    ErrorCode
  NODE    node    Node Number of the Local Node

[C Language Interface]
  ER ercd = nget_nod ( NODE *p_node ) ;

[Description]

This system call gets the local node number.

[Supplemental Information]

The assignment of node numbers depends on the specifications of each network
and system.  Absolute node numbers (whereby the node address looks the same
from every node) may not always be available.  It is therefore not always
guaranteed that the node number returned by this system call will remain valid
if sent to another node.

[Error Codes (ercd)]
  E_OK      Normal Completion


========================================================================
|| [SN] || nget_ver || Get Version Information of another Node
========================================================================
  nget_ver:       Get Version Information of Another Node

[Parameters]
  NODE    node    Target Node Number
  T_VER   *pk_ver Packet Address Representing Version Information

[Return Parameters]
  ER      ercd    ErrorCode

 -(pk_ver members)-
  UH      maker   OS Maker
  UH      id      ID Number of the OS
  UH      spver   ITRON or uITRON Specification Version Number
  UH      prver   OS Product Version Number
  UH      prno[4] Product Number (Product Management Information)
  UH      cpu     CPU Information
  UH      var     Variation Descriptor

[C Language Interface]
  ER ercd = nget_ver ( T_VER *pk_ver, NODE node );

[Description]

This system call gets information such as the vendor of the ITRON or uITRON
specification OS currently executing on the remote node, the ID number of the
OS, the ITRON or uITRON specification version number in conformance, and
support level information.

The meaning and format of the parameters representing the OS product vendor
(maker), OS ID number (id), ITRON or uITRON specification version number
(spver), OS product version number (prver), product number and product
management information (prno), CPU information (cpu), and variation descriptor
(var) are all identical to the same name parameters obtained using get_ver.
This information (packet contents) are automatically transferred from the
target node to the requesting node.

TND_SELF = 0 for node specifies the local node.

[Supplemental Information]

Since the data sizes of information returned by nget_ver are all fixed, its
execution never results in an EN_RPAR error.

TND_OTHR = -1 for node may specify a default remote node.  This feature is
useful when the target node of the connection function is uniquely defined
such as in a star configuration where the central node is seen from the
peripheral nodes.  The TND_OTHR = -1 specification can also be used in simple
networks where two nodes are connected by a single cable to simply represent
the other node.  Applicability of the TND_OTHR specification may be dependent
on network configuration and implementation of network support function.

Note that the TND_SELF and TND_OTHR specifications may only be used in
parameters to system calls of the form n???_???.  They may not appear in
transmission packets with other nodes.

[Error Codes (ercd)]
  E_OK      Normal Completion
  E_PAR     Parameter error (the packet address for the return parameters
            could not be used)
  E_CTX     Context error (issued from task-independent portions or
            issued in dispatch disabled state)

****************************************************************************
*****                                                                  *****
*****  Chapter 4 Connection Function Communication Protocol            *****
*****                                                                  *****
****************************************************************************

uITRON 3.0 specification provides the standard for the communications
protocol (packet format) to implement the connection function.
Standardization of this specification allows the connectivity with other
products based on uITRON 3.0 specification.  This chapter describes the
communication protocol (packet format) used under uITRON 3.0 specification
to implement the connection function.


****************************************************************************
***    4.1 Overview of Communications Protocols                          ***
****************************************************************************

***  Position of Communications Protocols **********************************

Figure 32 shows the position of communications protocols standardized under
uITRON 3.0 specification.

Under the scope of this specification, the interfaces (packet formats)
corresponding to (2) and (4) in Figure 32 are standardized.  They are called
connection interface.  The data contents (packet format) going through (3)
conforms to the interfaces determined for (2) and (4).  The low-level protocol
used for (3) may be borrowed from the protocol for the network and
communication media (such as start-stop protocol when using serial lines).
Specifics regarding the relationships between (2) and (3), or between
(4) and (3), must be determined separately based on the low-level protocol
used for (3).  Although this specification is beyond the scope of this
specification, specific protocols required for configuring a standard system
is expected to be included in another specification documents.

Part (1) in Figure 32 is standardized to conform to system call interface
specifications.



               Requesting Node                            Target Node
 +-----------------+     +-------------------+       +-------------------+
 |                 | (1) |                   |       |                   |
 | Requesting Task | ==> |    uITRON 3.0     |       |    uITRON 3.0     |
 |                 |     |   Spec. Kernel    |       |   Spec. Kernel    |
 +-----------------+     |        ||         |       |        /\         |
                         +------- || --------+       +------- || --------+
                         |        \/         |       |        ||         |
                         |Connection Function|       |Connection Function|
                         |   Processing      |       |   Processing      |
                         |        ||         |       |        /\         |
                         +------- ||(2) -----+       +------- ||(4) -----+
                         |        \/         |       |        ||         |
                         | I/O Drivers for   |  (3)  | I/O Drivers for   |
                         |   Communications  | ====> |   Communications  |
                         |   Processing      |       |   Processing      |
                         |                   |       |                   |
                         +-------------------+       +-------------------+

                Figure 32 Position of Communications Protocols



***  Design Concept for the Connection Interface ***************************

The specification design of the connection interface emphasizes the following
concepts.

  - Information is split into that supported by low-level protocol (such as
    packet size) and that which is not, to make classification based on low-
    level protocol easier.

  - Fixed length parts and variable length parts are split in order to make
    buffers easier to allocate.

  - Although packets are based on 32-bit units (information such as object
    numbers is represented in 32 bits), packets using 16-bit units are also
    prepared so that small-scale systems may be connected to the network.  If
    both the requesting node and target node support it, 16-bit packets may be
    used.  Note that since even most 8-bit processors provide 16-bit
    addressing, packets should be of at least 16 bits.  (Although 8-bit packets
    may be defined, they are not usually used.)

  - Only big-endian scheme is used as a byte order format.

  - System calls which may enter a WAIT state returns an acknowledge packet
    (TA packet) is returned when a requesting packet (TP packet) arrives at
    the target node in order that a distinction can be made between time
    elapse during waiting and transmission line errors.

  - A packet for canceling requests has been prepared so that recovery
    processing from forcible wait release caused by rel_wai or ter_tsk may be
    carried out.  However, there is no guarantee that resources can be
    consistently recovered.

***  Packet Types **********************************************************

The five following communication packet types are used to implement the
connection function.

  'TP'  Request - Parameter packet
  'TR'  Return - Packet for returning processing results; return packet
  'TE'  Error - Packet used when processing results in an error
  'TA'  Acknowledge - Packet indicating that a system call has resulted in a
        WAIT state
  'TC'  Cancel - Packets used to cancel requests when a WAIT state is forcibly
        released.  This is used when rel_wai is issued on a task which is
        waiting for an object on another node. [level X]

The 'TA' packet is not returned when a system call (such as wai_sem), though
having a latent possibility to enter a WAIT state, does not actually result in
a WAIT state (such as when the resource requested is immediately available or
when polling is being used).

In order to make it easier to allocate buffers on the packet-receiving node,
variable length parts are split into a separate subpacket.  For example, when
sending a message to a messagebuffer, a main packet is sent first, which
includes parameters such as the object ID of the target messagebuffer and
message size, followed by a subpacket containing the variable-length message
itself.  These two packets are related by the following parameters.

  - Request Number (reqno)
        The main packet and subpacket have the same request number (reqno).
        Main packets and subpackets can be correctly paired by matching their
        request numbers.
        Corresponding TP, TR, TE, TA and TC packets may exist for any given
        request number.  (But each type does not necessarily exist for every
        request number.)

  - Sequence Number (seq)
        A sequence number provided within each packet to represent whether the
        packet is a main packet, subpacket or n-th packet.  Seq = 1 indicates
        a main packet while seq = 2 a subpacket.  When more than one subpacket
        is used they are subsequently numbered seq = 3, seq = 4 ..., etc.

The reason subpackets are split from main packets is related to issues
regarding how buffer allocation is implemented.  Main packets and subpackets
combined together represent a single meaningful unit.  Even when different
sequence numbers are used, they are sent contiguously without discontinuity
between packets.

***  Configuration of the Connection Interface *****************************



  +--------+ +------------------+ +-------------+ +--------------------+
  |  Size  | | Destination Node | | Source Node | | Packet Body...     |
  | bodysz | | dstnode          | | srcnode     | | body               |
  +--------+ +------------------+ +-------------+ +--------------------+

             Figure 33 Configuration of the Connection Interface


The low-level protocol, which is expected to be reliable byte streams, is not
provided with checksums.  Recovery from errors will be handled by the low-
level protocol as necessary.

Since the following information will likely be supported by the low-level
protocol in most cases, it is not included in the packet structure called body.

  - Total number of bytes given by bodysz (packet size)

  - Packet destination node number given by dstnode
        A target node number for TP and TC packets
        A requesting node number for a TR, TE or TA packets

  - Packet source node given by srcnode
        A requesting node number for TP and TC packets
        A target node number for a TR, TE or TA packets

All of the above information (bodysz, srcnode, dstnode and body) are
transferred across the interfaces (2) and (4) given in Figure 32.  The exact
method by which the information given by bodysz, srcnode, dstnode and body is
represented by the low-level protocol (3) is dependent on the specifics of the
low-level protocol used (for example, its serial lines, a uBTRON bus).  The
rest of this chapter describes the contents of body.

In some cases, the node address of the low-level protocol may match the node
number used in uITRON 3.0 specification, and in others, it may not.  This
specific specification is determined by the relation with low-level protocol.

Size can be identified by interpreting the packet structure format.  In this
sense, the packet size given by bodysz is redundant information as a rule.
However, packet size is given separately by bodysz to make buffer allocation
easier and improve the flexibility (possibility of changes and additions) of
the packet structure format.

***  Bit Width of Data in Packets ******************************************

32 bits is the basic unit of measuring data included in packets, but 16-bit
packets are also provided for small-scale applications.

The packet bit length supported by each node (acceptable number of bits =
acpbits) is written in the object location table specified at system
configuration, and any internode coordination necessary are made.  The bit
width of the CPU and the value of acpbits do not necessarily have to match.
It is possible for acpbits to represent 16 bits when an 8-bit CPU uses 16-bit
ID numbers and object numbers.  Furthermore, there may be parameters and
return parameters (such as the return parameters of nget_ver) which always
have the same bit width regardless of the value given by acpbits.

Packets whose bit length may change are handled as follows.

 - Signed data types (such as INT, TMO and PRI) of language C interface under
   uITRON 3.0 specification are interpreted as sign extended when packets
   having a smaller bit width are accepted by a node having a larger acpbits
   value.  When packets having a larger bit width are accepted by a node having
   a smaller acpbits value, processing continues if the same value can be
   represented as a signed number, otherwise an EN_PAR or EN_RPAR error will
   result if the value as a signed number overflows.

  - Unsigned data types (such as UINT) of language C interface under uITRON 3.0
    specification are interpreted as zero extended when packets having a
    smaller bit width are accepted by a node having a larger acpbits value.
    When packets having a larger bit width are accepted by a node having a
    smaller acpbits value, processing continues if the same value can be
    represented as an unsigned number, otherwise an EN_PAR or EN_RPAR error
    will result if the value as an unsigned number overflows.

  - As a rule, data types of language C interface for which sign cannot be
    determined (such as FP and VP) under uITRON 3.0 specification are
    interpreted in the same way as described above for signed data types
    (such as INT).  However, they may be handled differently depending on
    the implementation.

***  Specific Packet Flow **************************************************

Specific packet flow is as follows (Figure 34).

  (1) A request packet (TP packet) is sent from the requesting node (the node
      on which the system call was issued) to the target node (the node on
      which the system call will be processed).  Any variable length
      parameters are sent in a separate packet (TP2 packet).

  (2) After the request packet arrives at the target node, an acknowledge (TA
      packet) is sent from the target node to the requesting node if the
      system call issued will result in a WAIT state for the issuing task.

  (3) After the system call has been processed on the target node, a return
      packet (TR packet) is sent from the target node to the requesting node.
      Any variable length parameters are sent in a separate packet (TR2
      packet).


 +------------------------------+
 | When sig_sem has been issued |
 +------------------------------+

     /---------------\                                 /---------------\
    ( Requesting Node )                               (   Target Node   )
     \---------------/                                 \---------------/
             |                                                 |
             v                                                 v
   sig_sem is issued                                           |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = sig_sem, semno                     >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
     /|      :                                        sig_sem is processed
    / +------------------------------------------------------------------+
   <   'TR', seq = 1, Function Code = sig_sem, ercd = E_OK               |
    \ +------------------------------------------------------------------+
     \|


 +------------------------------+
 | When wai_sem has been issued |
 +------------------------------+

     /---------------\                                 /---------------\
    ( Requesting Node )                               (   Target Node   )
     \---------------/                                 \---------------/
             |                                                 |
             v                                                 v
   wai_sem is issued                                           |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = wai_sem, semno                     >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
     /|      :                                        wai_sem is processed
    / +------------------------------------------------------------------+
   <   'TA', seq = 1, Function Code = wai_sem, tskwait = TTW_SEM, waino  |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                      WAIT State is released
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 1, Function Code = wai_sem, ercd = E_OK               |
    \ +------------------------------------------------------------------+
     \|

 Notes: 1. Protocol version and request numbers have been omitted.
        2. Semno represents the object number of the target semaphore on
           the target node.

                Figure 34 Packet Flow for sig_sem and wai_sem


 +-------------------------------+
 | When psnd_mbf has been issued |
 +-------------------------------+

     /---------------\                                 /---------------\
    ( Requesting Node )                               (   Target Node   )
     \---------------/                                 \---------------/
             |                                                 |
             v                                                 v
   psnd_mbf is issued                                          |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = psnd_mbf, mbfno, msgsz             >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 2, Function Code = psnd_mbf, message contents         >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
     /|      :                                       psnd_mbf is processed
    / +------------------------------------------------------------------+
   <   'TR', seq = 1, Function Code = psnd_mbf, ercd = E_OK              |
    \ +------------------------------------------------------------------+
     \|


 +------------------------------+
 | When rcv_mbf has been issued |
 +------------------------------+

     /---------------\                                 /---------------\
    ( Requesting Node )                               (   Target Node   )
     \---------------/                                 \---------------/
             |                                                 |
             v                                                 v
   rcv_mbf is issued                                           |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = rcv_mbf, mbfno                     >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
     /|      :                                        rcv_mbf is processed
    / +------------------------------------------------------------------+
   <   'TA', seq = 1, Function Code = rcv_mbf, tskwait = TTW_MBF, waino  |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                      WAIT State is released
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 1, Function Code = rcv_mbf, ercd = E_OK, msgsz        |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 2, Function Code = rcv_mbf, message contents          |
    \ +------------------------------------------------------------------+
     \|

 Notes: 1. Protocol version and request numbers have been omitted.
        2. Mbfno represents the object number of the target messagebuffer
           on the target node.

                Figure 35 Packet Flow for psnd_mbf and rcv_mbf

****************************************************************************
***    4.2 Communication Packet                                          ***
****************************************************************************

***  Packet Structure ******************************************************

Contents of the communication packet structure (body) are as follows.


 +------------------------------------------------------------------------+
 | Header (Common to All Packets)                                         |
 +--------+-------+-------------------------------------------------------+
 | offset | bytes | Description                                           |
 +--------+-------+-------------------------------------------------------+
 |   +0   |  1+1  | Communication packet type and magic number (magic)    |
 |        |       |                                                       |
 |        |       | One of 'TP', 'TR', 'TE', 'TA' or 'TC' is inserted     |
 |        |       | here.  'T', 'P', 'R', 'E', 'A' and 'C' are represented|
 |        |       | by ASCII code.                                        |
 |        |       |                                                       |
 |        |       | 'T' appearing at the beginning indicates big-endian.  |
 |        |       | However, little-endian is not used in principle.      |
 |        |       | A similar format is used for the record ID of the     |
 |        |       | BTRON/CHIP object format.                             |
 |        |       |                                                       |
 |        |       | An 'I' is used instead of 'T' if an implementation-   |
 |        |       | dependent format has been used instead of the standard|
 |        |       | specification communication format described hereafter|
 |        |       | (such as when the format has been changed for overall |
 |        |       | network tuning).                                      |
 +--------+-------+-------------------------------------------------------+
 |   +2   |   1   | Bit width used as standard unit and existence of      |
 |        |       | subpackets                                            |
 |        |       |                                                       |
 |        |       |   +---------+--------------+--------------+           |
 |        |       |   |  bits   |    total     |     seq      |           |
 |        |       |   +----+----+----+----+----+----+----+----+           |
 |        |       |                                                       |
 |        |       |   bits:    B' 00   8-bit packets (not actually used)  |
 |        |       |            B' 01  16-bit packets                      |
 |        |       |            B' 10  32-bit packets (standard)           |
 |        |       |   total:   Total number of packets (main packet plus  |
 |        |       |            subpackets)                                |
 |        |       |   seq:     Sequential number representing packet order|
 |        |       |                                                       |
 |        |       | Total and seq are used when variable-length data has  |
 |        |       | been put into subpackets.  When there are no          |
 |        |       | subpackets, with just a main packet, total = 1 and    |
 |        |       | seq = 1.  Although packets may be split into up to 8  |
 |        |       | parts, actually only two parts (one for fixed-length  |
 |        |       | data and one for variable-length data) are used.      |
 |        |       | The main packet and all of the subpackets have the    |
 |        |       | same request number (reqno).                          |
 +--------+-------+-------------------------------------------------------+
 |   +3   |   1   | Protocol level and version                            |
 |        |       |                                                       |
 |        |       |   +-------------------+-------------------+           |
 |        |       |   |     proto_lev     |     proto_ver     |           |
 |        |       |   +----+----+----+----+----+----+----+----+           |
 |        |       |                                                       |
 |        |       |   proto_lev:    Protocol level                        |
 |        |       |   proto_ver:    Protocol version                      |
 |        |       |                                                       |
 |        |       | Under a first version, proto_lev = H'1 and            |
 |        |       | proto_ver = H'1.                                      |
 +--------+-------+-------------------------------------------------------+
 |   +4   |   4   | Request number (reqno)                                |
 |        |       |                                                       |
 |        |       | This value, specified for the parameter packet, is    |
 |        |       | returned in a return packet as it was.  The bytes     |
 |        |       | semantically include information for requesting task  |
 |        |       | ID and the data to uniquely identify each request.    |
 |        |       | The encoding method used, however, is implementation  |
 |        |       | dependent.  For example, the lower 2 bytes of the     |
 |        |       | request number may represent the requesting task ID,  |
 |        |       | while the upper 2 bytes represent a sequential number.|
 |        |       |                                                       |
 |        |       | When system call processing has been completed on the |
 |        |       | target node, processing results can be returned to the|
 |        |       | requesting task on the requesting node using the      |
 |        |       | requesting task ID included in the request number of  |
 |        |       | the return packet.  When a request is canceled by     |
 |        |       | rel_wai or due to a timeout on the requesting task,   |
 |        |       | the request number can be used to identify which task |
 |        |       | made the request.                                     |
 |        |       |                                                       |
 |        |       | All packets related to a single system call (TP, TP2, |
 |        |       | TR, TR2, TE, TA and TC packets) have the same request |
 |        |       | number.                                               |
 +--------+-------+-------------------------------------------------------+
 |   +8   |   2   | Requesting function code (reqfncd)                    |
 |        |       |                                                       |
 |        |       | All packets (TP, TP2, TR, TR2, TE, TA and TC packets) |
 |        |       | related to a single system call have the same request |
 |        |       | number.  Although this is redundant information except|
 |        |       | for the TP packet, this may be used as additional     |
 |        |       | information for the request number.  Furthermore, in  |
 |        |       | the case of the TP2, TR and TR2 packets, the          |
 |        |       | requesting function code can be used to determine the |
 |        |       | format of the packet to follow, thus serving to       |
 |        |       | increase reliability.  The requesting function code in|
 |        |       | the TP packet can be returned to the TE packet also   |
 |        |       | when an EN_RSFN error is returned with no             |
 |        |       | corresponding system call identified on the target    |
 |        |       | node.                                                 |
 +--------+-------+-------------------------------------------------------+
 |   +10  |   1   | [level X] information (levelx)                        |
 |        |       |                                                       |
 |        |       | This is a bitmap representing whether or not the      |
 |        |       | packet contains [level X] data.                       |
 |        |       |                                                       |
 |        |       | For example, in the case of a cre_sem parameter       |
 |        |       | packet, it represents whether or not isemcnt and      |
 |        |       | maxsem data are included in parts of the packet to    |
 |        |       | follow.                                               |
 |        |       |                                                       |
 |        |       | This field is 0 if no [level X] data is included.     |
 |        |       |                                                       |
 |        |       | The levelx field of the parameter packet and return   |
 |        |       | packet represent independent information. For example,|
 |        |       | returning additional [level X] data in ref_??? is only|
 |        |       | indicated in the levelx field of the return packet,   |
 |        |       | not in the levelx field of the parameter packet.      |
 +--------+-------+-------------------------------------------------------+
 |   +11  |   1   | reserved                                              |
 |        |       |                                                       |
 |        |       | Padded with zeros.                                    |
 +--------+-------+-------------------------------------------------------+
 | Note: The fields given up to this point make up a 12-byte, fixed-length|
 |       header.  The field format to follow may change depending on the  |
 |       packet type in question and the value given in the header for    |
 |       bits, reqfncd and levelx.                                        |
 +------------------------------------------------------------------------+


 +------------------------------------------------------------------------+
 | TE Packet                                                              |
 +------------------------------------------------------------------------+
 | offset/bytes                                                           |
 |                                                                        |
 | /---bits----\                                                          |
 |/             \                                                         |
 |16bits   32bits  Description                                            |
 +-------+-------+--------------------------------------------------------+
 |+12/2B |+12/4B | Error code (ercd)                                      |
 |       |       |                                                        |
 |       |       | A reply conforming to this TE packet format is made    |
 |       |       | whenever any error occurs.  This is the same for both  |
 |       |       | connection function errors and other common errors.    |
 |       |       | No other return parameters are simultaneously sent.    |
 +-------+-------+--------------------------------------------------------+


 +------------------------------------------------------------------------+
 | TA Packet                                                              |
 +------------------------------------------------------------------------+
 | offset/bytes                                                           |
 |                                                                        |
 | /---bits----\                                                          |
 |/             \                                                         |
 |16bits   32bits  Description                                            |
 +-------+-------+--------------------------------------------------------+
 |+12/2B |+12/4B | Task wait cause (tskwait)                              |
 |       |       |                                                        |
 |       |       | This field indicates the cause of the WAIT state on the|
 |       |       | target node.  The value inserted here is the same as   |
 |       |       | that referred to by tskwait for the ref_tsk system     |
 |       |       | call.  This information is handled as an unsigned      |
 |       |       | number.                                                |
 +-------+-------+--------------------------------------------------------+
 |+14/2B |+16/4B | Wait number (waino) [level X]                          |
 |       |       |                                                        |
 |       |       | This information is used when sending a TC packet.     |
 |       |       | This information is [level X]; but the TA packet       |
 |       |       | format does not change even if this function is not    |
 |       |       | supported.  In such cases waino = 0 is  returned.      |
 +-------+-------+--------------------------------------------------------+
 | Notes: 1. Under polling system calls of the form p???_???, a TR packet |
 |           is returned when polling succeeds (when resources can be     |
 |           allocated), while a TE packet is returned when polling fails |
 |           (when resources cannot be allocated).  In neither case is  a |
 |           TA packet returned to a system call of the form p???_???     |
 |           (except for in the case of pcal_por).                        |
 |        2. A TA packet is returned if polling succeeds (when a          |
 |           rendezvous is established) for pcal_por because the system   |
 |           call results in a WAIT state.                                |
 +------------------------------------------------------------------------+


 +------------------------------------------------------------------------+
 | TC Packet [level X]                                                    |
 +------------------------------------------------------------------------+
 | offset/bytes                                                           |
 |                                                                        |
 | /---bits----\                                                          |
 |/             \                                                         |
 |16bits   32bits  Description                                            |
 +-------+-------+--------------------------------------------------------+
 |+12/2B |+12/4B | Wait number (waino)                                    |
 |       |       |                                                        |
 |       |       | The values returned by the TA packet are used as-is.   |
 +-------+-------+--------------------------------------------------------+


 +------------------------------------------------------------------------+
 | TP and TR Packets (by system call)                                     |
 +------------------------------------------------------------------------+
 | Notes:  - Packets with no additional symbol represents signed data,    |
 |           while those appended with + indicate unsigned.               |
 |         - TP and TP2 are request (parameter) packets; TR and TR2 are   |
 |           return packets.                                              |
 |         - TP2 and TR2 are packets for seq = 2 (all other packets are   |
 |           main packets for seq = 1).                                   |
 |         - The following ercd* contents are actually limited to E_OK    |
 |           (but not limited to E_OK when extended to ITRON/FILE         |
 |            specification, etc.).                                       |
 +------------------------------------------------------------------------+
 | bits=16bit =>  +12/2B +14/2B +16/2B +18/2B +20/2B +22/2B +24/2B +26/2B |
 | bits=32bit =>  +12/4B +16/4B +20/4B +24/4B +28/4B +32/4B +36/4B +40/4B |
 |                  ||     ||     ||     ||     ||     ||     ||     ||   |
 |                  \/     \/     \/     \/     \/     \/     \/     \/   |
 +----------+-------------------------------------------------------------+
 | cre_tsk  | TP  tskno  exinf  tskatr+ task  itskpri stksz               |
 |          | TR  ercd*                                                   |
 | del_tsk  | TP  tskno                                                   |
 |          | TR  ercd*                                                   |
 | sta_tsk  | TP  tskno  stacd                                            |
 |          | TR  ercd*                                                   |
 | ext_tsk  | No-connection-function                                      |
 | exd_tsk  | No-connection-function                                      |
 | ter_tsk  | TP  tskno                                                   |
 |          | TR  ercd*                                                   |
 | dis_dsp  | No-connection-function                                      |
 | ena_dsp  | No-connection-function                                      |
 | chg_pri  | TP  tskno  tskpri                                           |
 |          | TR  ercd*                                                   |
 | rot_rdq  | No-connection-function                                      |
 | rel_wai  | TP  tskno                                                   |
 |          | TR  ercd*                                                   |
 | get_tid  | No-connection-function                                      |
 | ref_tsk  | TP  tskno                                                   |
 |          | TR  ercd* exinf tskpri tskstat+ (tskwait+ wid wupcnt suscnt)|
 |          |     Note: Parameters indicated inside parentheses represent |
 |          |           [level X] features.                               |
 | sus_tsk  | TP  tskno                                                   |
 |          | TR  ercd*                                                   |
 | rsm_tsk  | TP  tskno                                                   |
 |          | TR  ercd*                                                   |
 | frsm_tsk | TP  tskno                                                   |
 |          | TR  ercd*                                                   |
 | slp_tsk  | No-connection-function                                      |
 | tslp_tsk | No-connection-function                                      |
 | wup_tsk  | TP  tskno                                                   |
 |          | TR  ercd*                                                   |
 | can_wup  | TP  tskno                                                   |
 |          | TR  ercd*  wupcnt                                           |
 | cre_sem  | TP  semno  exinf  sematr+ (isemcnt maxsem)                  |
 |          | TR  ercd*                                                   |
 |          |     Note: Parameters indicated inside parentheses represent |
 |          |           [level X] features.                               |
 | del_sem  | TP  semno                                                   |
 |          | TR  ercd*                                                   |
 | sig_sem  | TP  semno                                                   |
 |          | TR  ercd*                                                   |
 | wai_sem  | TP  semno                                                   |
 |          | TR  ercd*                                                   |
 | preq_sem | TP  semno                                                   |
 |          | TR  ercd*                                                   |
 | twai_sem | TP  semno  tmout                                            |
 |          | TR  ercd*                                                   |
 | ref_sem  | TP  semno                                                   |
 |          | TR  ercd*  exinf  wtsk    semcnt                            |
 +----------+-------------------------------------------------------------+
 | cre_flg  | TP  flgno  exinf  flgatr+ iflgptn+                          |
 |          | TR  ercd*                                                   |
 | del_flg  | TP  flgno                                                   |
 |          | TR  ercd*                                                   |
 +----------+-------------------------------------------------------------+
 | set_flg  | TP  flgno  setptn+                                          |
 |          | TR  ercd*                                                   |
 | clr_flg  | TP  flgno  clrptn+                                          |
 |          | TR  ercd*                                                   |
 | wai_flg  | TP  flgno  waiptn+ wfmode+                                  |
 |          | TR  ercd*  flgptn+                                          |
 | pol_flg  | TP  flgno  waiptn+ wfmode+                                  |
 |          | TR  ercd*  flgptn+                                          |
 | twai_flg | TP  flgno  waiptn+ wfmode+ tmout                            |
 |          | TR  ercd*  flgptn+                                          |
 | ref_flg  | TP  flgno                                                   |
 |          | TR  ercd*  exinf   wtsk   flgptn+                           |
 +----------+-------------------------------------------------------------+
 | cre_mbx  | No-connection-function                                      |
 | del_mbx  | No-connection-function                                      |
 | snd_msg  | No-connection-function                                      |
 | rcv_msg  | No-connection-function                                      |
 | prcv_msg | No-connection-function                                      |
 | trcv_msg | No-connection-function                                      |
 | ref_mbx  | No-connection-function                                      |
 +----------+-------------------------------------------------------------+
 | cre_mbf  | TP  mbfno  exinf  mbfatr+ bufsz   maxmsz                    |
 |          | TR  ercd*                                                   |
 | del_mbf  | TP  mbfno                                                   |
 |          | TR  ercd*                                                   |
 | snd_mbf  | TP  mbfno  msgsz                                            |
 |          | TP2 send-message-body (byte length = msgsz)                 |
 |          | TR  ercd*                                                   |
 | psnd_mbf | TP  mbfno  msgsz                                            |
 |          | TP2 send-message-body (byte length = msgsz)                 |
 |          | TR  ercd*                                                   |
 | tsnd_mbf | TP  mbfno  msgsz  tmout                                     |
 |          | TP2 send-message-body (byte length = msgsz)                 |
 |          | TR  ercd*                                                   |
 | rcv_mbf  | TP  mbfno                                                   |
 |          | TR  ercd*  msgsz                                            |
 |          | TR2 receive-message-body (byte length = msgsz)              |
 | prcv_mbf | TP  mbfno                                                   |
 |          | TR  ercd*  msgsz                                            |
 |          | TR2 receive-message-body (byte length = msgsz)              |
 | trcv_mbf | TP  mbfno  tmout                                            |
 |          | TR  ercd*  msgsz                                            |
 |          | TR2 receive-message-body (byte length = msgsz)              |
 | ref_mbf  | TP  mbfno                                                   |
 |          | TR  ercd*  exinf  wtsk    stsk    msgsz   frbufsz           |
 +----------+-------------------------------------------------------------+
 | cre_por  | TP  porno  exinf  poratr+ maxcmsz maxrmsz                   |
 |          | TR  ercd*                                                   |
 | del_por  | TP  porno                                                   |
 |          | TR  ercd*                                                   |
 | cal_por  | TP  porno  cmsgsz calptn+                                   |
 |          | TP2 call-message-body (byte length = cmsgsz)                |
 |          | TR  ercd*  rmsgsz                                           |
 |          | TR2 reply-message-body (byte length = rmsgsz)               |
 | pcal_por | TP  porno  cmsgsz calptn+                                   |
 |          | TP2 call-message-body (byte length = cmsgsz)                |
 |          | TR  ercd*  rmsgsz                                           |
 |          | TR2 reply-message-body (byte length = rmsgsz)               |
 | tcal_por | TP  porno  cmsgsz calptn+ tmout                             |
 |          | TP2 call-message-body (byte length = cmsgsz)                |
 |          | TR  ercd*  rmsgsz                                           |
 |          | TR2 reply-message-body (byte length = rmsgsz)               |
 |          |     Note: Information representing subpacket size such as   |
 |          |           msgsz, cmsgsz and rmsgsz is all given in the      |
 |          |           second parameter.                                 |
 | acp_por  | No-connection-function                                      |
 | pacp_por | No-connection-function                                      |
 | tacp_por | No-connection-function                                      |
 | fwd_por  | No-connection-function                                      |
 | rpl_rdv  | No-connection-function   (see the TR packet of cal_por)     |
 | ref_por  | TP  porno                                                   |
 |          | TR  ercd*  exinf  wtsk    atsk                              |
 +----------+-------------------------------------------------------------+
 | def_int  | No-connection-function                                      |
 | ret_int  | No-connection-function                                      |
 | ret_wup  | No-connection-function                                      |
 | loc_cpu  | No-connection-function                                      |
 | unl_cpu  | No-connection-function                                      |
 | dis_int  | No-connection-function                                      |
 | ena_int  | No-connection-function                                      |
 | chg_iXX  | No-connection-function                                      |
 | ref_iXX  | No-connection-function                                      |
 +----------+-------------------------------------------------------------+
 | cre_mpl  | No-connection-function                                      |
 | del_mpl  | No-connection-function                                      |
 | get_blk  | No-connection-function                                      |
 | pget_blk | No-connection-function                                      |
 | tget_blk | No-connection-function                                      |
 | rel_blk  | No-connection-function                                      |
 | ref_mpl  | No-connection-function                                      |
 | cre_mpf  | No-connection-function                                      |
 | del_mpf  | No-connection-function                                      |
 | get_blf  | No-connection-function                                      |
 | pget_blf | No-connection-function                                      |
 | tget_blf | No-connection-function                                      |
 | rel_blf  | No-connection-function                                      |
 | ref_mpf  | No-connection-function                                      |
 +----------+-------------------------------------------------------------+
 | set_tim  | No-connection-function                                      |
 | get_tim  | No-connection-function                                      |
 | dly_tsk  | No-connection-function                                      |
 | def_cyc  | No-connection-function                                      |
 | act_cyc  | No-connection-function                                      |
 | ref_cyc  | No-connection-function                                      |
 | def_alm  | No-connection-function                                      |
 | ref_alm  | No-connection-function                                      |
 | ret_tmr  | No-connection-function                                      |
 +----------+-------------------------------------------------------------+
 | get_ver  | No-connection-function                                      |
 | ref_sys  | No-connection-function                                      |
 | ref_cfg  | No-connection-function                                      |
 | def_svc  | No-connection-function                                      |
 | def_exc  | No-connection-function                                      |
 | nrea_dat | TP  srcadr  datsz                                           |
 |          | TR  ercd*   reasz                                           |
 |          | TR2 Read-memory-data (byte length = reasz)                  |
 |          |     Note: reasz included in TR is the byte length of data   |
 |          |           actually read                                     |
 | nwri_dat | TP  dstadr  datsz                                           |
 |          | TP2 Write-memory-data (byte length = datsz)                 |
 |          | TR  ercd*   wrisz                                           |
 |          |     Note: wrisz included in TR is the byte length of data   |
 |          |           actually written                                  |
 | nget_nod | No-connection-function                                      |
 | nget_ver | TP  (none)                                                  |
 |          | TR  pk_ver-contents (byte length = 20)                      |
 |          |     Note: As far as this packet is concerned, the format    |
 |          |           (byte length of the packet) does not depend on    |
 |          |           the bit width of the node.                        |
 +----------+-------------------------------------------------------------+


***  [level X] Information *************************************************

The following values can be inserted in the [level X] information field
(levelx) of the header.

 [TR packet for ref_tsk]

    +---------+---------+---------+---------+--------------------------+
    | tskwait |   wid   | wupcnt  | suscnt  | Value Inserted in levelx |
    +---------+---------+---------+---------+--------------------------+
    |   No    |   No    |   No    |   No    |    B'00000000 = H'00     |
    |   Yes   |   No    |   No    |   No    |    B'00000001 = H'01     |
    |   Yes   |   Yes   |   No    |   No    |    B'00000011 = H'03     |
    |   Yes   |   Yes   |   Yes   |   No    |    B'00000111 = H'07     |
    |   Yes   |   Yes   |   Yes   |   Yes   |    B'00001111 = H'0f     |
    +---------+---------+---------+---------+--------------------------+

 [TP packet for cre_sem]

         +---------+---------+--------------------------+
         | isemcnt | maxsem  | Value Inserted in levelx |
         +---------+---------+--------------------------+
         |   No    |   No    |    B'00000000 = H'00     |
         |   Yes   |   No    |    B'00000001 = H'01     |
         |   Yes   |   Yes   |    B'00000011 = H'03     |
         +---------+---------+--------------------------+

***  Connection Function-Related Errors ************************************

A TE packet is returned whenever a system call is executed on the target node
and an EN_xxxx or E_xxxx error other than E_OK is results.  Having a format
independent of the system call in question, the TE packet only returns ercd
error code data.  As such, no other parameters can be returned simultaneously
when an error occurs.

In addition to errors explicitly returned from the target node in a TE packet,
some connection function errors such as those due to packet loss or the system
going down are detected on the requesting node.  Table 8 lists error codes,
packet flows, and whether or not the system call in question executed for
each error.

In Table 8, EN_PAR (*1) indicates an error caused at a packet creation in
which the requesting node attempts to use a small 8-bit or 16-bit packet but
actual parameter size is larger.  Also, EN_PAR (*2) represents the case where
a packet was successfully created, and a request sent to the target node,
but an error resulted because the size of one or more parameters once on the
target node was too large to be processed.  This difference is outlined in
Figure 36.


           Table 8 Connection Function Error Codes and Packet Flow

 +-----------------+-------------+---------------+------------------------+
 | Error Codes     | Is the TP   | Are the       | Is the System Call     |
 | Detected on the | Packet      | TR and/or TE  | Executed on the Target |
 | Requesting Node | Used?       | Packets Used? | Node?                  |
 +-----------------+-------------+---------------+------------------------+
 |    E_OK         |  Yes        |  TR, (+TR2)   | Executes and completes |
 |                 |             |               | normally               |
 |    E_xxx        |  Yes        |      TE       | Executes but results   |
 |                 |             |               | in an error            |
 |    EN_NOND      |  No         |      No       | Does not execute       |
 |    EN_OBJNO     |  Yes        |      TE       | Does not execute       |
 |    EN_PROTO     |  Yes        |      TE       | Does not execute       |
 |    EN_RSFN      |  Yes        |      TE       | Does not execute       |
 |    EN_COMM      |  Yes ? (*5) |   No ? (*6)   | Unclear as seen from   |
 |                 |             |               | the requesting node    |
 |    EN_RLWAI     |  Yes ? (*5) |   No ? (*6)   | Unclear as seen from   |
 |                 |             |               | the requesting node    |
 |    EN_PAR  (*1) |  No         |      No       | Does not execute       |
 |            (*2) |  Yes        |      TE       | Does not execute       |
 |    EN_RPAR (*3) |  Yes        |      TE       | Executes and completes |
 |                 |             |               | normally               |
 |            (*4) |  Yes        |  TR, (+TR2)   | Executes and completes |
 |                 |             |               | normally               |
 |    EN_CTXID     |  No         |      No       | Does not execute       |
 |    EN_EXEC      |  Yes        |      TE       | Does not execute       |
 +-----------------+-------------+---------------+------------------------+



   /--------------\ (1)                            |\ (2) /--------------\
  /   Requesting   \  +----------------------------+ \   /     Target     \
 (  Node Bit Width  ) |   Bit Width in Packet = p     > (  Node Bit Width  )
  \         = a    /  +----------------------------+ /   \         = b    /
   \--------------/                                |/     \--------------/

                                 EN_PAR (*1) if an overflow results at (1).
                                 EN_PAR (*2) if an overflow results at (2).

                   Figure 36 The Two Types of EN_PAR Error


In Table 8, EN_RPAR (*3) represents the case where an error results because
the target node attempts to return a small 8-bit or 16-bit packet but actual
return parameter size is larger.  Also, EN_RPAR (*4) represents the case where
a return packet was successfully created, and results returned to the
requesting node, but an error resulted because the size of one or more
parameters once on the requesting node was too large to be processed.  In this
case, no error is interpreted on the target node.

EN_COMM and EN_RLWAI (*5) indicate that although the requesting node
supposedly sent a parameter packet, it is unclear whether or not one was
actually sent.  (*6) indicates that although the requesting node recognize
that it has not received a return packet, it is unclear whether or not
one wasn't actually arrived.  In this case, it is possible that a delayed
return packet will arrive after the system call ends on an error on the
requesting node.

***  TC Packet *************************************************************

The TC packet is issued to release tasks from waiting for objects; it is not
used to release them from waiting for connection function response.  The TC
packet is therefore always returned after the TA packet is received.  In order
to make the processing on the target node more efficient after the TC packet
is received, a wait number (waino) is inserted into the TA packet on the
target node and the same wait number is used when the requesting node returns
the TC packet.  Exact contents of the wait number, which are implementation
dependent, may include the ID of the task performing connection function
processing on the target node (called the "connection function processing
task") and be used as an index to a table representing connection function
processing status.

When a system call request is canceled before complete execution, the TC
packet releases as many resources (including the connection function
processing task itself and all types of resources used by it) as possible used
on the target node to carry out connection function processing so that they
may be used again.  It is also used to decrease as much as possible
inconsistencies in the number of resources on the target node.  Note however
that the specifications of the TC packet are [level X].  On system where
inconsistencies in the number of resources are not expected to be a problem
(such as systems which are restarted after a system call has halted),
specifications may call for no TC packet to be sent by the requesting node at
all or for the target node to ignore any TC packets received.  Even if the
target node will successfully process TC packets, it may not be possible to
avoid inconsistencies in the number of resources due to the timing of packets
being received and sent.  Since the error EN_RLWAI is always returned to the
requesting task in this situation, this can be taken as representing the
possibility that inconsistencies have developed in the number of resources on
the target node.

Figure 37 shows specifically how the TC packet is used.



 +------------------------------------------------------------------+
 |      When rel_wai releases a WAIT state caused by wai_sem        |
 +------------------------------------------------------------------+

     /---------------\                                 /---------------\
    ( Requesting Node )                               (   Target Node   )
     \---------------/                                 \---------------/
             |                                                 |
             v                                                 v
   wai_sem is issued                                           |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = wai_sem, semno                     >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
   TTW_NOD wait state results               wai_sem is processed by the OS
             :                                                 |
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TA', seq = 1, Function Code = wai_sem, waino, tskwait = TTW_SEM  |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
             :                                                 |
   TTW_SEM wait state results                                  |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
  rel_wai => :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TC', seq = 1, Function Code = wai_sem, waino                     >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
   EN_RLWAI is returned          The WAIT state of the connection function
                                 processing task is released (halted
                                 without obtaining resources)

                      Figure 37 How TC Packets are Used


If a system call from the requesting node is halted by rel_wai before the TA
packet is received, the requesting node does not notify the target node of
anything.  The same is true for system calls (such as sig_sem) targeting other
nodes which do not result in waiting for an object.  However, the following
actions should be taken in order to decrease the most possible inconsistencies
in the number of resources on the target node.

  - If the parameter packets for the system call request are being accumulated
    on the send queue of the requesting node, they should be deleted.

  - If the TA packet associated with the canceled request is received later, a
    TC packet should be returned in response (so that no unnecessary resources
    are allocated on the target node).

There is no possibility that a reply in response to the TC packet will be
returned from the target node, while TR packet may be sent in delayed timing
before TC packet reaches the target node.

[Rationale]

The TC packet is issued to release tasks from waiting for objects on another
node, not from waiting for connection function response.  No particular packet
is available for notification of cancellation when rel_wai is issued on a task
in wait for connection function response state.  This is for the following
reasons.

  - Preparing and sending a packet for cancelling the parameter packets will
    be meaningless if both packets are transferred to the target node at the
    same speed and, as a result, cancelling (TC) packet cannot catch up with
    the parameter (TP) packet.

  - It is possible that one might wish to cancel a request using rel_wai in
    cases where processing of the connection function would take too much time
    because the parameter packet could not be sent properly due to a
    communication line or target node error.  However, since the probability
    is high in this case that the parameter packet could not be sent (is
    waiting on the send queue), all cancel processing in this case can be
    handled within the requesting node rendering a cancel packet preparation
    meaningless.

  - On networks where there are intermediate nodes, errors at the intermediate
    node or in part of the communication line may cause the congestion of
    packets on the communication line.  In such cases, the requesting node
    will think the parameter packet has been sent properly when in fact it has
    not been received at the target node.  In this case, there is a chance
    that cancel processing can be carried out because a cancel packet, even
    though sent later, can catch up to the parameter packet stuck in the
    middle.  However, since this type of processing is too complicated for
    applications envisioned under uITRON 3.0 specification, there is no
    standard packet format defined for this purpose.  (However, such a packet
    format may be created as an additional feature as necessary.)

***  Packet Flow When Using Rendezvous *************************************

Since cal_por supports the connection function, it may be executed targeting a
port on another node.

However, no packet is sent from the target node to notify the requesting node
that the rendezvous state on the target node has changed from wait on
rendezvous call to wait for RENDEZVOUS completion state.  It is therefore not
possible for a task carrying out a rendezvous at the port of another node to
distinguish between these two WAIT states.  For details, see the related
system call description.




 +---------------------------------------------------+
 | When cal_por immediately establishes a rendezvous |
 +---------------------------------------------------+

    /------------------------\                 /------------------------\
   /     Requesting Node      \               /       Target Node        \
  ( the node on which the task )             (   the node on which the    )
   \  issuing cal_por exists  /               \  specified port exists   /
    \------------------------/                 \------------------------/
             |                                                 |
             v                                                 v
   cal_por is issued                                           |<= acp_por
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = cal_por, porno, cmsgsz, calptn     >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 2, Function Code = cal_por, call message              >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
   TTW_NOD wait state results           Call rendezvous processing is done
             :                          by the OS
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TA', seq = 1, Function Code = cal_por, (TTW_CAL|TTW_RDV), waino  |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
             :                                                 |
   (TTW_CAL | TTW_RDV) wait state        Rendezvous accept task processing
   (actually TTW_RDV)                                          |
             :                                                 |
             :                                                 |
             :                                           rpl_rdv is issued
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 1, Function Code = cal_por, ercd, rmsgsz              |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 2, Function Code = cal_por, reply message             |
    \ +------------------------------------------------------------------+
     \|

   Figure 38 Packet Flow When cal_por Immediately Establishes a Rendezvous


The TC packet used for cal_por applies to both the wait on rendezvous call
state and the wait for rendezvous completion state.  Since the node on which
cal_por is executed cannot tell the difference between these two states,
discrimination between the two packets sent in both cases is meaningless.
Furthermore, it is useful to send the TC packet for both wait on rendezvous
call state and wait for rendezvous completion state for releasing the
connection function processing task on the target node and any related
resources.

Several examples of packet flow related to the rendezvous feature are
illustrated in the figures below.




 +----------------------------------------------------------+
 | When cal_por does not immediately establish a rendezvous |
 +----------------------------------------------------------+

    /------------------------\                 /------------------------\
   /     Requesting Node      \               /       Target Node        \
  ( the node on which the task )             (   the node on which the    )
   \  issuing cal_por exists  /               \  specified port exists   /
    \------------------------/                 \------------------------/
             |                                                 |
             v                                                 v
   cal_por is issued                                           |
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = cal_por, porno, cmsgsz, calptn     >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 2, Function Code = cal_por, call message              >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
   TTW_NOD wait state                   Call rendezvous processing is done
             :                          by the OS
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TA', seq = 1, Function Code = cal_por, (TTW_CAL|TTW_RDV), waino  |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
             :                                                 |
   (TTW_CAL | TTW_RDV) wait state            Wait on rendezvous call state
   (actually TTW_CAL)                                          |
             :                                                 |
             :                                                 |
   (The requesting node does not              The rendezvous is <= acp_por
    know the rendezvous has been              established
    established)                                               |
             :                                                 |
             :                                                 |
   (TTW_CAL | TTW_RDV) wait state        Rendezvous accept task processing
   (actually TTW_RDV)                                          |
             :                                                 |
             :                                           rpl_rdv is issued
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 1, Function Code = cal_por, ercd, rmsgsz              |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 2, Function Code = cal_por, reply message             |
    \ +------------------------------------------------------------------+
     \|

           Figure 39 Packet Flow When cal_por Does Not Immediately
                            Establish a Rendezvous




 +---------------------------------------------------------------------+
 | When cal_por immediately establishes a rendezvous, but is forwarded |
 | and results in CALL WAIT                                            |
 +---------------------------------------------------------------------+

    /------------------------\                 /------------------------\
   /     Requesting Node      \               /       Target Node        \
  ( the node on which the task )             (   the node on which the    )
   \  issuing cal_por exists  /               \  specified port exists   /
    \------------------------/                 \------------------------/
             |                                                 |
             v                                                 v
   cal_por is issued                                           |<= acp_por
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = cal_por, porno, cmsgsz, calptn     >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 2, Function Code = cal_por, call message              >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
   TTW_NOD wait state                   Call rendezvous processing is done
             :                          by the OS
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TA', seq = 1, Function Code = cal_por, (TTW_CAL|TTW_RDV), waino  |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
             :                                                 |
   (TTW_CAL | TTW_RDV) wait state             Rendezvous accept task
   (actually TTW_CAL)                         processing before forwarding
             :                                                 |
             :                                                 |
   (The requesting node does not             The rendezvous is  <= fwd_por
    know the rendezvous has been             forwarded
    forwarded)                                                 |
             :                                                 |
             :                                                 |
   (TTW_CAL | TTW_RDV) wait state            Wait on rendezvous call state
   (actually TTW_CAL)                                          |
             :                                                 |

             :                                                 |
    (The requesting node does not            A rendezvous is    <= acp_por
     know the rendezvous has been            established again
     established again)                                        |
             :                                                 |
             :                                                 |
   (TTW_CAL | TTW_RDV) wait state        Rendezvous accept task processing
   (actually TTW_RDV)                    after forwarding
             :                                                 |
             :                                           rpl_rdv is issued
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 1, Function Code = cal_por, ercd, rmsgsz              |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 2, Function Code = cal_por, reply message             |
    \ +------------------------------------------------------------------+
     \|

     Figure 40 Packet Flow When a Rendezvous is Forwarded to Another Node




 +------------------------------------------------------------------+
 | When tcal_por results timeout in a wait on rendezvous call state |
 +------------------------------------------------------------------+

    /------------------------\                 /------------------------\
   /     Requesting Node      \               /       Target Node        \
  ( the node on which the task )             (   the node on which the    )
   \ issuing tcal_por exists  /               \  specified port exists   /
    \------------------------/                 \------------------------/
             |                                                 |
             v                                                 v
   tcal_por is issued                                          |
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |  'TP', seq=1, Function Code=tcal_por, porno, cmsgsz, calptn, tmout  >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 2, Function Code = tcal_por, call message             >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
   TTW_NOD wait state                   Call rendezvous processing is done
             :                          by the OS
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TA', seq = 1, Function Code = tcal_por, (TTW_CAL|TTW_RDV), waino |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
             :                                                 |
   (TTW_CAL | TTW_RDV) wait state                              |
             :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
     /|      :                                              Timeout
    / +------------------------------------------------------------------+
   <   'TE', seq = 1, Function Code = tcal_por, ercd = E_TMOUT           |
    \ +------------------------------------------------------------------+
     \|

 Note: Packet flow is the same for other system calls which include a
       timeout feature.

           Figure 41 Packet Flow When tcal_por Results in a Timeout




 +----------------------------------------+
 | When pcal_por establishes a rendezvous |
 +----------------------------------------+

    /------------------------\                 /------------------------\
   /     Requesting Node      \               /       Target Node        \
  ( the node on which the task )             (   the node on which the    )
   \ issuing pcal_por exists  /               \  specified port exists   /
    \------------------------/                 \------------------------/
             |                                                 |
             v                                                 v
   pcal_por is issued                                          |<= acp_por
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = pcal_por, porno, cmsgsz, calptn    >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 2, Function Code = pcal_por, call message             >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
   TTW_NOD wait state                   Call rendezvous processing is done
             :                          by the OS
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TA', seq = 1, Function Code = pcal_por, (TTW_CAL|TTW_RDV), waino |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
             :                                                 |
   (TTW_CAL | TTW_RDV) wait state        Rendezvous accept task processing
             :                                                 |
             :                                                 |
             :                                                 |
             :                                           rpl_rdv is issued
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 1, Function Code = pcal_por, ercd, rmsgsz             |
    \ +------------------------------------------------------------------+
     \|      :                                                 |
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TR', seq = 2, Function Code = pcal_por, reply message            |
    \ +------------------------------------------------------------------+
     \|

 Note: pcal_por, which is a system call which conducts polling, enters a
       WAIT state even when polling succeeds (when a rendezvous is
       established) causes a TA packet to be returned.  A TA packet is
       never returned on other system calls other than pcal_por of the
       form p???_??? which conduct polling.

         Figure 42 Packet Flow When pcal_por Establishes a Rendezvous




 +-----------------------------------------------+
 | When pcal_por does not establish a rendezvous |
 +-----------------------------------------------+

    /------------------------\                 /------------------------\
   /     Requesting Node      \               /       Target Node        \
  ( the node on which the task )             (   the node on which the    )
   \ issuing pcal_por exists  /               \  specified port exists   /
    \------------------------/                 \------------------------/
             |                                                 |
             v                                                 v
   pcal_por is issued                                          |
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 1, Function Code = pcal_por, porno, cmsgsz, calptn    >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |      |\
   +------------------------------------------------------------------+ \
   |   'TP', seq = 2, Function Code = pcal_por, call message             >
   +------------------------------------------------------------------+ /
             :                                                 |      |/
             :                                                 |
   TTW_NOD wait state                   Call rendezvous processing is done
             :                          by the OS
             :                                                 |
             :                                                 |
             :                                                 |
             :                                                 |
     /|      :                                                 |
    / +------------------------------------------------------------------+
   <   'TE', seq = 1, Function Code = pcal_por, ercd = E_TMOUT           |
    \ +------------------------------------------------------------------+
     \|

 Note: TE packet, in stead of TA packet, returns an error.  The processing
       in this case is the same as the other polling system call.

     Figure 43 Packet Flow When pcal_por Does Not Establish a Rendezvous

****************************************************************************
*****                                                                  *****
*****  Chapter 5 Standard Interfaces                                   *****
*****                                                                  *****
****************************************************************************

This chapter describes the system call interfaces used under uITRON 3.0
specification.  Specifically, it includes descriptions of the assembler
interface, C language interface and error codes used with system calls.  For
details on values used for function codes and error codes, refer to this
chapter and the reference included in the following chapter.


****************************************************************************
***    5.1 The Assembler Interface                                       ***
****************************************************************************

The assembler interface of each system call under uITRON 3.0 specification is
determined depending on the processor being used.  However, rules governing
the part of this interface concerning function codes and flag value changes
are described in this section.  These general rules should be followed as
closely as possible as long as there are no other restrictions preventing it.

***  How Parameters are Passed *********************************************

As a rule, parameters in the assembler interface are passed as follows.  These
rules should be followed as closely as possible when the performance overhead
in doing so is low.

  - As a rule, system call parameters and return parameters are placed in
    registers.  Somewhere between 4 to 6 registers are therefore used.

  - When system call type is represented by a function code, the code is
    placed in a register normally used as an accumulator.

  - All registers not used for return parameters should be saved.

***  Flag Value Changes in the PSW after System Calls have Executed ********

There is no particular specification regarding flag values in the PSW after
system calls have executed.  They are assumed to be undefined.

[Rationale]

Under ITRON1 specification, we recommended that the zero flag be set to
indicate whether or not an error occurred.  However, even if the OS does set
this flag, it will not necessarily be accessed and is in fact meaningless
when using the C language interface.  Furthermore, the overhead required to
set this flag cannot be overlooked.

Furthermore, some processors can spontaneously save flags using hardware
processing of a trap instruction without specifically having the OS control the
flag.  However, if system calls are to be handled in hardware in the future, it
may be more desirable to have the flag set.  It is therefore impossible to say
that saving the flag is always preferable.  uITRON 3.0 specification at the
present time therefore do not include any specification concerning flag values
after system calls have executed.

***  Function Code *********************************************************

Under ITRON specification, a number called a "function code" is used to
identify system call types.  This function code is placed in a register and
the corresponding system call is executed when a subsequent trap instruction
is issued.

Under uITRON 3.0 specification, depending on the processor architecture and
development environment being used, system calls may be executed by directly
jumping to a system call processing routine in the OS using a subroutine jump
instruction rather than a trap instruction (software interrupt instruction).
Function codes are not needed in such cases.  However, if a system call
interface using function codes is to be implemented, the standardized
function code values should be used unless otherwise constrained.  It is also
mandatory to use the standardized function code values in the communications
protocol used to implement the connection function.

The assignment of standard function code values is given below.

[Function Code Assignment]

  - In coordination with standard TRON policy, negative values are used for
    all standard function code values.

  - Consideration has been given to alignment for multiple of eight bytes and
    common bit patterns for common functions (cre_???, ref_???, etc.).

  - A meaningful set of function codes are assigned in most possible way to
    all function groups covered in the specifications.
  - It is not absolutely necessary to assign function codes in the order they
    appear in the specifications.  Order of description in the specifications
    is not related with the function codes.

  - System calls of the form i???_??? and p???_??? each form a single group by
    themselves.  As such, they are separated from other system calls and form
    other groups to which unique numbers are given.

The actual function code value used by each system call is given in the
following pages.  A list of function code table is also given in the next
chapter "Reference".


 Task Management Functions ================================================

 +----------------------------------+  +----------------------------------+
 | System        Function Code      |  | System        Function Code      |
 |  Call    [Hexadecimal] [Decimal] |  |  Call    [Hexadecimal] [Decimal] |
 +----------------------------------+  +----------------------------------+

  cre_tsk      H'ffef      (-17)         chg_pri     H'ffe5      (-27)
  del_tsk      H'ffee      (-18)         ichg_pri    H'ff8b      (-117)
  sta_tsk      H'ffe9      (-23)         rot_rdq     H'ffe4      (-28)
  ext_tsk      H'ffeb      (-21)         irot_rdq    H'ff8a      (-118)
  exd_tsk      H'ffea      (-22)         rel_wai     H'ffe1      (-31)
  ter_tsk      H'ffe7      (-25)         irel_wai    H'ff81      (-127)
  dis_dsp      H'ffe2      (-30)         get_tid     H'ffe8      (-24)
  ena_dsp      H'ffe3      (-29)         ref_tsk     H'ffec      (-20)


 Task-Dependent Synchronization Functions =================================

 +----------------------------------+  +----------------------------------+
 | System        Function Code      |  | System        Function Code      |
 |  Call    [Hexadecimal] [Decimal] |  |  Call    [Hexadecimal] [Decimal] |
 +----------------------------------+  +----------------------------------+

   sus_tsk     H'ffdf      (-33)         slp_tsk     H'ffda      (-38)
   isus_tsk    H'ff8f      (-113)        tslp_tsk    H'ffdb      (-37)
   rsm_tsk     H'ffdd      (-35)         wup_tsk     H'ffd9      (-39)
   irsm_tsk    H'ff8d      (-115)        iwup_tsk    H'ff87      (-121)
   frsm_tsk    H'ffdc      (-36)         can_wup     H'ffd8      (-40)
   ifrsm_tsk   H'ff8c      (-116)


 Synchronization and Communication Functions ==============================

 +----------------------------------+  +----------------------------------+
 | System        Function Code      |  | System        Function Code      |
 |  Call    [Hexadecimal] [Decimal] |  |  Call    [Hexadecimal] [Decimal] |
 +----------------------------------+  +----------------------------------+

   cre_sem     H'ffcf      (-49)         cre_mbx     H'ffc7      (-57)
   del_sem     H'ffce      (-50)         del_mbx     H'ffc6      (-58)
   sig_sem     H'ffc9      (-55)         snd_msg     H'ffc1      (-63)
   isig_sem    H'ff85      (-123)        isnd_msg    H'ff84      (-124)
   wai_sem     H'ffcb      (-53)         rcv_msg     H'ffc3      (-61)
   preq_sem    H'ff95      (-107)        prcv_msg    H'ff94      (-108)
   twai_sem    H'ff55      (-171)        trcv_msg    H'ff54      (-172)
   ref_sem     H'ffcc      (-52)         ref_mbx     H'ffc4      (-60)
   cre_flg     H'ffd7      (-41)
   del_flg     H'ffd6      (-42)
   set_flg     H'ffd0      (-48)
   iset_flg    H'ff86      (-122)
   clr_flg     H'ffd1      (-47)
   wai_flg     H'ffd2      (-46)
   twai_flg    H'ff56      (-170)
   pol_flg     H'ff96      (-106)
   ref_flg     H'ffd4      (-44)


 Extended Synchronization and Communication Functions =====================

 +----------------------------------+  +----------------------------------+
 | System        Function Code      |  | System        Function Code      |
 |  Call    [Hexadecimal] [Decimal] |  |  Call    [Hexadecimal] [Decimal] |
 +----------------------------------+  +----------------------------------+

   cre_mbf     H'ff67      (-153)        cre_por     H'ff6f      (-145)
   del_mbf     H'ff66      (-154)        del_por     H'ff6e      (-146)
   snd_mbf     H'ff63      (-157)        cal_por     H'ff6b      (-149)
   psnd_mbf    H'ff93      (-109)        pcal_por    H'ff91      (-111)
   ipsnd_mbf   H'ff83      (-125)        tcal_por    H'ff51      (-175)
   tsnd_mbf    H'ff53      (-173)        acp_por     H'ff6a      (-150)
   rcv_mbf     H'ff62      (-158)        pacp_por    H'ff90      (-112)
   prcv_mbf    H'ff92      (-110)        tacp_por    H'ff50      (-176)
   trcv_mbf    H'ff52      (-174)        fwd_por     H'ff68      (-152)
   ref_mbf     H'ff64      (-156)        rpl_rdv     H'ff69      (-151)
                                         ref_por     H'ff6c      (-148)


 Interrupt Management Functions ===========================================

 +----------------------------------+  +----------------------------------+
 | System        Function Code      |  | System        Function Code      |
 |  Call    [Hexadecimal] [Decimal] |  |  Call    [Hexadecimal] [Decimal] |
 +----------------------------------+  +----------------------------------+

   def_int     H'ffbf      (-65)         dis_int     H'ffb8      (-72)
   ret_int     H'ffbb      (-69)         ena_int     H'ffb9      (-71)
   ret_wup     H'ffba      (-70)         chg_iXX     H'ffbd      (-67)
   loc_cpu     H'fff8      (-8)          ref_iXX     H'ffbc      (-68)
   unl_cpu     H'fff9      (-7)


 Memorypool Management Functions ==========================================

 +----------------------------------+  +----------------------------------+
 | System        Function Code      |  | System        Function Code      |
 |  Call    [Hexadecimal] [Decimal] |  |  Call    [Hexadecimal] [Decimal] |
 +----------------------------------+  +----------------------------------+

   cre_mpl     H'ff77      (-137)        cre_mpf     H'ffb7      (-73)
   del_mpl     H'ff76      (-138)        del_mpf     H'ffb6      (-74)
   get_blk     H'ff73      (-141)        get_blf     H'ffb3      (-77)
   pget_blk    H'ff98      (-104)        pget_blf    H'ff99      (-103)
   ipget_blk   H'ff88      (-120)        ipget_blf   H'ff89      (-119)
   tget_blk    H'ff58      (-168)        tget_blf    H'ff59      (-167)
   rel_blk     H'ff71      (-143)        rel_blf     H'ffb1      (-79)
   ref_mpl     H'ff74      (-140)        ref_mpf     H'ffb4      (-76)


 Time Management Functions ================================================

 +----------------------------------+  +----------------------------------+
 | System        Function Code      |  | System        Function Code      |
 |  Call    [Hexadecimal] [Decimal] |  |  Call    [Hexadecimal] [Decimal] |
 +----------------------------------+  +----------------------------------+

   set_tim     H'ffad      (-83)         def_cyc     H'ffa6      (-90)
   get_tim     H'ffac      (-84)         act_cyc     H'ffa2      (-94)
   dly_tsk     H'ffab      (-85)         ref_cyc     H'ffa4      (-92)
                                         def_alm     H'ffa7      (-89)
                                         ref_alm     H'ffa5      (-91)
                                         ret_tmr     H'ffa3      (-93)


 System Management Functions ==============================================

 +----------------------------------+  +----------------------------------+
 | System        Function Code      |  | System        Function Code      |
 |  Call    [Hexadecimal] [Decimal] |  |  Call    [Hexadecimal] [Decimal] |
 +----------------------------------+  +----------------------------------+

   get_ver     H'fff0      (-16)         def_svc     H'fff7      (-9)
   ref_sys     H'fff4      (-12)         def_exc     H'fff5      (-11)
   ref_cfg     H'fff2      (-14)


 Network Support Functions ================================================

 +----------------------------------+  +----------------------------------+
 | System        Function Code      |  | System        Function Code      |
 |  Call    [Hexadecimal] [Decimal] |  |  Call    [Hexadecimal] [Decimal] |
 +----------------------------------+  +----------------------------------+

   nrea_dat    H'ff9d      (-99)         nget_nod    H'ff9f      (-97)
   nwri_dat    H'ff9c      (-100)        nget_ver    H'ff9e      (-98)

****************************************************************************
***    5.2 C Language Interface and Mnemonics                            ***
****************************************************************************

***  Mnemonics *************************************************************

There is no compatibility between object codes on differing processors since
underlying machine architecture is not virtualized under ITRON specification.
It is necessary to write programs using a high-level language in order to port
application programs from one processor to another.  Under ITRON specification,
C language is currently used as the standard high-level language of choice.
The interface for executing system calls of uITRON 3.0 specification from C
language has been standardized.

The C language interface supported by ITRON specification conforms to the
following conventions.

  - All system calls are defined as C functions

  - The return value of these functions is in general the error code (ercd) of
    the system call.  Ercd is zero when a system call completes normally and
    non-zero (in fact negative by standard) when an error occurs.

  - When returning return parameters (???) for data other than an error code,
    a pointer (p_???) to the memory in which that data is to be placed is
    specified as a parameter.

  - Pointers to return parameters must be placed ahead of the parameters.
    This same rule applies to pointers (packet addresses) specified under the
    assembler interface if they semantically correspond to return parameters in
    the case of system calls such as ref_???.

Mnemonics used in C conform to the following conventions.

  - Names of parameters and return parameters
        The names of parameters and return parameters conform to the following
        conventions.

                p_      Pointer to memory in which return parameters
                        will be placed
                pk_     Packet addresses
                ???cd   ??? code
                i???    Initial value
                ???sz   Size (in bytes)
                ???cnt  Count

        When parameter names are the same for different system calls, they
        should in general be of the same type.  Note that parameter names of
        the form ???sz (such as blksz, frsz, msgsz, bufsz, stksz and datsz)
        represent items whose sizes are all measured in bytes.  Use names of
        the form ???cnt for parameters representing items measured in units
        other than bytes such as a number of blocks or messages.

  - Data type names
        All data type names, including data structures, are named in upper
        case.
        Pointer data type names take the form ???P.
        Data structure type names take the form T_???.

  - Mnemonics for constants
        Error code names take the form E_??? or EN_???.
        Object and handler attribute names take the form TA_???.
        Names of modes associated only with particular system calls or
        parameters take the form Txy_???.  The "xy" in the form changes
        depending on the system call or parameter in question.

***  Data Types ************************************************************

Standard specifications regarding data types, constant mnemonics and default
values, data structure packet formats, and the C language interface actually
used under uITRON 3.0 specification are given in the Reference found in the
next chapter.

[Supplemental Information]

Even parameters which are known never to be negative, such as stksz, wupcnt and
message sizes, are signed integers (INT) under uITRON 3.0 specification.
This specification is intended to satisfy an overall rule in TRON specification
(particularly for TRON-specification chips and ITRON2 specification) that
integers be handled as signed numbers.  In the case of a timeout parameter
(TMO tmout), the fact that it is a signed integer is used so that
TMO_FEVR = -1 carries the special meaning of waiting forever.  The only
parameters represented by unsigned data types are those which are handled as
bit patterns (such as object attributes and eventflags).

However, in some cases one may wish to handle the numbers known never to be
negative as unsigned numbers to expand the range of possible parameter values
in cases where uITRON 3.0 specification OS is being run on an 8- or 16-bit
processor (particularly an 8-bit one).  Such an interpretation may be applied
depending on the implementation (for each separate node).  However, this
interpretation is not allowed in regards to the packet format used to
implement the connection function due to the importance of maintaining
compatibility.  It is mandatory to observe strictly the data types written
in the specifications.

***  High-Level Language Support Routines **********************************

Under uITRON 3.0 specification, even when tasks and handlers are written in
a high-level language, a high-level language support routine feature may be
provided so that processing may be split into that handled by the kernel and
that handled by the language environment.  Whether or not a high-level
language support routine is being used is specified using an object attribute
and handler attribute (TA_HLNG).

If the TA_HLNG specification is not present, tasks and handlers are started
beginning directly at the start address specified by parameters for cre_tsk
and def_???.  If the TA_HLNG specification is present, a high-level language
startup routine (high-level language support routine) is started first and
then a jump is made from there to that start address specified by parameters
for cre_tsk and def_???.  In this case, task start addresses and handler
addresses are, if viewed from the OS, the parameters for the high-level
language support routine.  This method of running tasks and handlers allows
processing to be split into that handled by the kernel and that handled by the
language environment, and even allows simplified support of other language
environments.

In a high-level language support routine, with the tasks and handlers written
as C functions the execution of a return (return or "}") allows the automatic
execution of system either to exit a task or return from a handler.  This
feature allows normal execution to continue even when a programmer has
forgotten to include ext_tsk or ret_??? at the ending of his or her code.
This feature may be implemented by making a subroutine jump from the
high-level language support routine (h_???hdr) to a user-defined handler (???
hdr) written in a high-level language.  The ret_??? or ext_tsk system call may
then be executed from the support routine after control has been returned from
this handler.

Figure 44 shows the internal operation of a high-level language support
routine.



              .......Task as seen from the Kernel........
              .                                         .

               High-Level Language       Task Written as
 Kernel----+   Support Routine           a C Function
           |            :                      ||
           +----------->:            +-------->||
                        :            |         ||
                JSR or other jump----+         ||
                instruction                    ||
                        :<-----------+         ||
                        :            |         ||
                        :            |         ||
 Kernel<---------TRAPA [ext_tsk]     |         ||
                                     +-------return

         Figure 44 Operation of a High-Level Language Support Routine


Note that if routines written as C functions are called using the same
interface as assembly routines, use of high-level language support routines is
not necessarily required even when TA_HLNG is designated.

****************************************************************************
***    5.3 Error Codes                                                   ***
****************************************************************************

Under uITRON 3.0 specification, standard mnemonics and error code values have
been provided for each error which may occur when any given system call
executes.  The standard values of all error codes are negative.

Figure 45 shows the error code format used under uITRON 3.0 specification.



ercd(1)
 +-+-------------+---------------+---------------+---------------+ Normal
 |0|                        RETURN_CODE                          | Completion
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ (>0)

ercd(2)
 +---------------+---------------+---------------+---------------+ Normal
 |0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0| Completion
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ (=0)

ercd(3)
 +---------------+---------------+---------------+---------------+ Error
 |1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1|     ERRNO     | (<0)
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

 Notes: 1. The ercd (1) format, not used under uITRON 3.0 specification,
           is used under ITRON/FILE specification.
        2. If errno = ercd X (-1) in the ercd (3) format, 1 <= errno <= 255,
           and ERRNO can be made the two's complement of errno.

                         Figure 45 Error Code Formats


The following values may be used for error codes used to represent
implementation-dependent errors (EV_????) in the ercd (3) format shown in the
figure above.

        errno = 225-255, ERRNO = B'000????? (implementation-dependent)
        ercd = B'11...111000?????

The following values may be used for error codes used to represent user-
defined errors (such as for extended SVC handlers) in the ercd (3) format
shown in the figure above.

        errno = 193-223, ERRNO = B'001????? (user-defined)
        ercd = B'11...111001?????

Care should be exercised when using 8-bit CPUs, because these values look
positive when viewed as 8-bit signed integers.

The standard mnemonics and values of error codes used under uITRON 3.0
specification are described in the following pages.


============================================================================
 Normal Completion Error Class (EC_NONE, errno: 0)
============================================================================
-----+---------------------+----------------------------------------
E_OK | errno = 0 (decimal) | ercd = -0 (decimal) = -H'00 [H'0..0000]
-----+---------------------+----------------------------------------
        Normal Completion


============================================================================
 Error Class for System Error (EC_SYS, errno: 5 - 8)
============================================================================
------+---------------------+----------------------------------------
E_SYS | errno = 5 (decimal) | ercd = -5 (decimal) = -H'05 [H'f..fffb]
------+---------------------+----------------------------------------
        System error
        This indicates an error which affects the entire system and whose
        cause is unknown.


============================================================================
 Insufficient Memory Error Class (EC_NOMEM, errno: 9 - 16)
============================================================================
--------+----------------------+-----------------------------------------
E_NOMEM | errno = 10 (decimal) | ercd = -10 (decimal) = -H'0a [H'f..fff6]
--------+----------------------+-----------------------------------------
        Insufficient memory
        This error indicates that there is not enough memory to allocate
        for an object control block, user stack, memorypool, messagebuffer
        or other such item requiring memory.

    [Relationship to Error Codes of uITRON 2.0 and ITRON2 Specifications]
        This includes the E_NOSMEM error code used under ITRON2 and
        uITRON 2.0 specifications.


============================================================================
 Error Class for Reserved Feature Error (EC_RSV, errno: 17 - 32)
============================================================================
--------+----------------------+-----------------------------------------
E_NOSPT | errno = 17 (decimal) | ercd = -17 (decimal) = -H'11 [H'f..ffef]
--------+----------------------+-----------------------------------------
        Unsupported feature
        This error indicates that some feature of the system call (such as a
        [level X] feature) is not supported.  An E_RSATR or E_NOSPT error
        results when this feature is specified.  An E_NOSPT error results
        whenever the error does not correspond to E_RSATR.

---------+----------------------+-----------------------------------------
E_INOSPT | errno = 18 (decimal) | ercd = -18 (decimal) = -H'12 [H'f..ffee]
---------+----------------------+-----------------------------------------
        Feature not supported by ITRON/FILE specification

-------+----------------------+-----------------------------------------
E_RSFN | errno = 20 (decimal) | ercd = -20 (decimal) = -H'14 [H'f..ffec]
-------+----------------------+-----------------------------------------
        Reserved function code number
        This error results when an attempt is made to execute a system call by
        specifying a reserved function code (undefined function code).  This
        error also results when an attempt is made to execute an undefined
        extended SVC handler (if function code is positive).


--------+----------------------+-----------------------------------------
E_RSATR | errno = 24 (decimal) | ercd = -24 (decimal) = -H'18 [H'f..ffe8]
--------+----------------------+-----------------------------------------
        Reserved attribute
        This error results when an object attribute which is undefined or not
        supported is specified.
        Checking for this error may be omitted when making system-dependent
        adaptations.


============================================================================
 Error Class for Parameter Error (EC_PAR, errno: 33 - 48)
============================================================================
  * Nearly all these errors may be checked for statically.
------+----------------------+-----------------------------------------
E_PAR | errno = 33 (decimal) | ercd = -33 (decimal) = -H'21 [H'f..ffdf]
------+----------------------+-----------------------------------------
        Parameter error
        Checking for this error may be omitted when making system-dependent
        adaptations.

    [Relationship to Error Codes of uITRON 2.0 and ITRON2 Specifications]
        This includes the E_ILADR, E_TPRI, E_VECN, E_IMS, E_ILBLK, E_ILTIM,
        E_RSMD, E_SZOVR and E_ILFN error codes used under ITRON2 and uITRON
        2.0 specifications.

-----+----------------------+-----------------------------------------
E_ID | errno = 35 (decimal) | ercd = -35 (decimal) = -H'23 [H'f..ffdd]
-----+----------------------+-----------------------------------------
        Invalid ID number
        Since E_ID is only detected for objects which have IDs, it is never
        detected where interrupt vector numbers or handler numbers are
        concerned.  An E_PAR error will result when static error checking for
        out-of-range or reserved numbers is made for interrupt vector and
        handler numbers.

    [Relationship to Error Codes of uITRON 2.0 and ITRON2 Specifications]
        This includes the E_IDOVR and E_RSID error codes used under ITRON2 and
        uITRON 2.0 specifications.


============================================================================
 Invalid Object Specification Error Class (EC_OBJ, errno: 49 - 64)
============================================================================
--------+----------------------+-----------------------------------------
E_NOEXS | errno = 52 (decimal) | ercd = -52 (decimal) = -H'34 [H'f..ffcc]
--------+----------------------+-----------------------------------------
        Object does not exist

------+----------------------+-----------------------------------------
E_OBJ | errno = 63 (decimal) | ercd = -63 (decimal) = -H'3f [H'f..ffc1]
------+----------------------+-----------------------------------------
        Invalid object state

    [Relationship to Error Codes of uITRON 2.0 and ITRON2 Specifications]
        This includes the E_EXS, E_NODMT, E_DMT, E_SELF, E_NOWAI, E_NOSUS and
        E_NORDV error codes used under ITRON2 and uITRON 2.0 specifications.


============================================================================
 Access Violation Error Class (EC_ACV, errno: 65 - 68)
============================================================================
  * Access Violation
  * This includes object and memory access violations, but not file access
    violations.
-------+----------------------+-----------------------------------------
E_MACV | errno = 65 (decimal) | ercd = -65 (decimal) = -H'41 [H'f..ffbf]
-------+----------------------+-----------------------------------------
        Memory access disable, memory access violation

-------+----------------------+-----------------------------------------
E_OACV | errno = 66 (decimal) | ercd = -66 (decimal) = -H'42 [H'f..ffbe]
-------+----------------------+-----------------------------------------
        Object access violation
        This error results when a user task attempts to access a system
        object.
        Error detection is implementation dependent.


============================================================================
 Error Class for Context Error (EC_CTX, errno: 69 - 72)
============================================================================
------+----------------------+-----------------------------------------
E_CTX | errno = 69 (decimal) | ercd = -69 (decimal) = -H'45 [H'f..ffbb]
------+----------------------+-----------------------------------------
        Context error
        This error indicates that the system call in question cannot be issued
        from the current context (due to a task portion/task-independent
        portion distinction, or handler execution state).
        This error must be detected whenever a semantic mistake concerning
        system call execution context has been made such as when a system call
        (such as wai_sem) which causes an issuing task to enter a WAIT state
        has been issued from a task-independent portion.  This error is also
        detected whenever a system call is not allowed to be issued from a
        given context (such as an interrupt handler) due to implementation-
        dependent restrictions.

    [Relationship to Error Codes of uITRON 2.0 and ITRON2 Specifications]
        This includes the E_XNOSPT error code used under ITRON2 and
        uITRON 2.0 specifications.


============================================================================
 Error Class for Execution Error (EC_EXEC, errno: 73 - 80)
============================================================================
-------+----------------------+-----------------------------------------
E_QOVR | errno = 73 (decimal) | ercd = -73 (decimal) = -H'49 [H'f..ffb7]
-------+----------------------+-----------------------------------------
        Queuing or nesting overflow


============================================================================
 Error Class for Execution Completed Error (EC_EXCMP, errno: 81 - 84)
============================================================================
  * Execution Completed
------+----------------------+-----------------------------------------
E_DLT | errno = 81 (decimal) | ercd = -81 (decimal) = -H'51 [H'f..ffaf]
------+----------------------+-----------------------------------------
        Object being waited for was deleted


============================================================================
 Release Wait Error Class (EC_RLWAI, errno: 85 - 88)
============================================================================
  * Release Wait
--------+----------------------+-----------------------------------------
E_TMOUT | errno = 85 (decimal) | ercd = -85 (decimal) = -H'55 [H'f..ffab]
--------+----------------------+-----------------------------------------
        Polling failure or timeout

    [Relationship to Error Codes of uITRON 2.0 and ITRON2 Specifications]
        This includes the E_PLFAIL error code used under ITRON2 and
        uITRON 2.0 specifications.

--------+----------------------+-----------------------------------------
E_RLWAI | errno = 86 (decimal) | ercd = -86 (decimal) = -H'56 [H'f..ffac]
--------+----------------------+-----------------------------------------
        WAIT state was forcibly released


============================================================================
 Connection Function-Related Error Class (EC_NODE, errno: 113 - 128)
============================================================================
--------+-----------------------+------------------------------------------
EN_NOND | errno = 113 (decimal) | ercd = -113 (decimal) = -H'71 [H'f..ff8f]
--------+-----------------------+------------------------------------------
        Target node does not exist or cannot be accessed
        This error can be determined by looking at the Object Location Table
        on the requesting node, the Configuration Table and the Routing Tables
        along the communication line.

---------+-----------------------+------------------------------------------
EN_OBJNO | errno = 114 (decimal) | ercd = -114 (decimal) = -H'72 [H'f..ff8e]
---------+-----------------------+------------------------------------------
        Specifies an object number which could not be accessed on the target
        node
        This error results when a requesting node sends a packet for the
        purpose of accessing an object on another node, but it is found after
        arrival on the target node that that object number cannot be used on
        the target node either because it does not exist or because it may not
        be accessed by other nodes.  This error indicates that there is a
        contradiction in the Object Location Tables of the requesting and
        target nodes.

---------+-----------------------+------------------------------------------
EN_PROTO | errno = 115 (decimal) | ercd = -115 (decimal) = -H'73 [H'f..ff8d]
---------+-----------------------+------------------------------------------
        Protocol not supported on target node

--------+-----------------------+------------------------------------------
EN_RSFN | errno = 116 (decimal) | ercd = -116 (decimal) = -H'74 [H'f..ff8c]
--------+-----------------------+------------------------------------------
        System call not supported on target node
        An EN_RSFN error results when a system call of a support level which
        cannot be processed on the target node is issued over the connection
        function.  For example, an EN_RSFN error will result if a system call
        of support level [EN] is issued to a target node of [level SN].


--------+-----------------------+------------------------------------------
EN_COMM | errno = 117 (decimal) | ercd = -117 (decimal) = -H'75 [H'f..ff8b]
--------+-----------------------+------------------------------------------
        No response from target node
        This error is detected in cases such as when the target node is not
        operating; the target node is broken; communication lines are not open;
        and an unrecoverable communication line error has occurred.

---------+-----------------------+------------------------------------------
EN_RLWAI | errno = 118 (decimal) | ercd = -118 (decimal) = -H'76 [H'f..ff8a]
---------+-----------------------+------------------------------------------
        Connection function response wait state was forcibly released
        This error is returned to the task when rel_wai has been issued on
        that task while it is in connection function response wait state or
        waiting for an object on another node.  It is unclear when this error
        is returned whether waiting has been released with or without the task
        specified to rel_wai being allocated (or returning) the resources
        being waited for.
        By contrast, when the E_RLWAI error is returned, it is guaranteed that
        the task specified by rel_wai is released from waiting without being
        allocated resources.  (A normal completion will occur when the
        specified task has been allocated the resources it was waiting for.)

-------+-----------------------+------------------------------------------
EN_PAR | errno = 119 (decimal) | ercd = -119 (decimal) = -H'77 [H'f..ff89]
-------+-----------------------+------------------------------------------
        A value outside the range supported by the target node and/or
        transmission packet format was specified as a parameter

--------+-----------------------+------------------------------------------
EN_RPAR | errno = 120 (decimal) | ercd = -120 (decimal) = -H'78 [H'f..ff88]
--------+-----------------------+------------------------------------------
        A value outside the range supported by the issuing node and/or
        transmission packet format was returned as a return parameter

---------+-----------------------+------------------------------------------
EN_CTXID | errno = 121 (decimal) | ercd = -121 (decimal) = -H'79 [H'f..ff87]
---------+-----------------------+------------------------------------------
        An object on another node was specified by a system call issued from a
        task in dispatch disabled state or from a task-independent portion
        Note that the condition of checking this error depends on whether
        the target object is on the issuing node or remote node.   If the
        target object was on the issuing node, the system call would be
        able to be executed (without resulting in an error).   An E_CTX error
        will result rather than an EN_CTXID error for system calls which are
        never allowed to be issued from a task-independent portion or a task
        in dispatch disabled state, regardless of whether the target object
        is on the issuing node or a remote node.

--------+-----------------------+------------------------------------------
EN_EXEC | errno = 122 (decimal) | ercd = -122 (decimal) = -H'7a [H'f..ff86]
--------+-----------------------+------------------------------------------
        System call could not be executed due to insufficient resources on the
        target node
        Resources such as memory and tasks are used when implementing the
        a connection function on a target node.  It is therefore possible that
        system call will not be able to be executed on a target node due to
        insufficient resources on that node.  This means that a system call,
        even though invoked correctly, may not always be able to be executed
        due to insufficient resources on the target node.  This error results
        when this situation arises.
        The only thing to do when this error is detected is to retry the
        system call after a little while has passed.


---------+-----------------------+------------------------------------------
EN_NOSPT | errno = 123 (decimal) | ercd = -123 (decimal) = -H'7b [H'f..ff85]
---------+-----------------------+------------------------------------------
        Connection function not supported


[Differences from uITRON 2.0 and ITRON2 Specifications]

  - Error codes have been greatly integrated.

  - Assignment of error code values used for system calls under ITRON2 and
    uITRON 2.0 specifications is succeeded to uITRON 3.0 specification.
        Even error codes whose names have been changed use the same values as
        long as they still represent the same error.

  - Since the system call exception and exception mask features are no longer
    necessary, the feature whereby exception class (EXCLS) could be indicated
    in the second byte from the bottom has been eliminated.  This has allowed
    error code format to be simplified making it more adaptable to 8-bit CPUs.
        Just multiplying errno by -1 gives the associated ercd.
        Although the concept of exception class remains for error
        classification purposes, the terminology has been changed to "error
        class".

  - The error class reserved for conventional MMUs is now used for connection
    function-related error codes (EN_xxxx).  Error classes and error numbers
    for MMUs have been relocated after this.
        The reason for this is that in order to be interpreted as negative
        values on an 8-bit CPU error codes must be represented in the earlier
        region.  In this respect, connection function-related errors were
        viewed as more important than MMU-related errors.

  - All error codes related to ITRON/FILE specification (EF_xxxx) remain
    unchanged.

****************************************************************************
*****                                                                  *****
*****  Chapter 6 References                                            *****
*****                                                                  *****
****************************************************************************

****************************************************************************
***    6.1 System Call Support Level Categories                          ***
****************************************************************************

+----------+--------------------------------------------------------------+
|          |                            Level                             |
+          +--------+--------+--------+--------+--------+--------+--------+
|          |   R    :   RN   |   S    :   SN   |   E    :   EN   |   C    |
+----------+--------+--------+--------+--------+--------+--------+--------+
|Task      |dis_dsp :        |ext_tsk :sta_tsk |exd_tsk :cre_tsk |        |
|Management|ena_dsp :        |rot_rdq :ter_tsk |        :del_tsk |        |
|          |        :        |get_tid :chg_pri |        :ref_tsk |        |
|          |        :        |        :rel_wai |        :        |        |
+----------+--------+--------+--------+--------+--------+--------+--------+
|Task-     |slp_tsk :wup_tsk |        :sus_tsk |tslp_tsk:frsm_tsk|        |
|Dependent |        :        |        :rsm_tsk |        :        |        |
|Synchroni-|        :        |        :can_wup |        :        |        |
|  zation  |        :        |        :        |        :        |        |
+----------+--------+--------+--------+--------+--------+--------+--------+
|Synchroni-|        :sig_sem |snd_msg :set_flg |cre_mbx :cre_sem |        |
|  zation  |        :wai_sem |rcv_msg :clr_flg |del_mbx :del_sem |        |
|   and    |        :preq_sem|prcv_msg:wai_flg |ref_mbx :ref_sem |        |
|Communi-  |        :        |        :pol_flg |trcv_msg:twai_sem|        |
|  cation  |        :        |        :        |        :cre_flg |        |
|          |        :        |        :        |        :del_flg |        |
|          |        :        |        :        |        :ref_flg |        |
|          |        :        |        :        |        :twai_flg|        |
+----------+--------+--------+--------+--------+--------+--------+--------+
|Extended  |        :        |        :        |acp_por :cre_mbf |        |
|Synchroni-|        :        |        :        |pacp_por:del_mbf |        |
|  zation  |        :        |        :        |tacp_por:snd_mbf |        |
|   and    |        :        |        :        |fwd_por :psnd_mbf|        |
|Communi-  |        :        |        :        |rpl_rdv :tsnd_mbf|        |
|  cation  |        :        |        :        |        :rcv_mbf |        |
|          |        :        |        :        |        :prcv_mbf|        |
|          |        :        |        :        |        :trcv_mbf|        |
|          |        :        |        :        |        :ref_mbf |        |
|          |        :        |        :        |        :cre_por |        |
|          |        :        |        :        |        :del_por |        |
|          |        :        |        :        |        :cal_por |        |
|          |        :        |        :        |        :pcal_por|        |
|          |        :        |        :        |        :tcal_por|        |
|          |        :        |        :        |        :ref_por |        |
+----------+--------+--------+--------+--------+--------+--------+--------+

+----------+--------+--------+--------+--------+--------+--------+--------+
|Interrupt |loc_cpu :        |        :        |ret_wup :        |dis_int |
|Management|unl_cpu :        |        :        |        :        |ena_int |
|          |ret_int :        |        :        |        :        |def_int |
|          |        :        |        :        |        :        |chg_iXX |
|          |        :        |        :        |        :        |ref_iXX |
+----------+--------+--------+--------+--------+--------+--------+--------+
|Memorypool|        :        |        :        |cre_mpf :        |        |
|Management|        :        |        :        |del_mpf :        |        |
|          |        :        |        :        |get_blf :        |        |
|          |        :        |        :        |pget_blf:        |        |
|          |        :        |        :        |tget_blf:        |        |
|          |        :        |        :        |rel_blf :        |        |
|          |        :        |        :        |ref_mpf :        |        |
|          |        :        |        :        |cre_mpl :        |        |
|          |        :        |        :        |del_mpl :        |        |
|          |        :        |        :        |get_blk :        |        |
|          |        :        |        :        |pget_blk:        |        |
|          |        :        |        :        |tget_blk:        |        |
|          |        :        |        :        |rel_blk :        |        |
|          |        :        |        :        |ref_mpl :        |        |
+----------+--------+--------+--------+--------+--------+--------+--------+
|Time      |        :        |set_tim :        |def_cyc :        |        |
|Management|        :        |get_tim :        |act_cyc :        |        |
|          |        :        |dly_tsk :        |ref_cyc :        |        |
|          |        :        |        :        |def_alm :        |        |
|          |        :        |        :        |ref_alm :        |        |
|          |        :        |        :        |ret_tmr :        |        |
+----------+--------+--------+--------+--------+--------+--------+--------+
|System    |get_ver :        |        :        |ref_sys :        |ref_cfg |
|Management|        :        |        :        |        :        |def_svc |
|          |        :        |        :        |        :        |def_exc |
+----------+--------+--------+--------+--------+--------+--------+--------+
|Network   |        :        |        :nrea_dat|        :        |        |
|Support   |        :        |        :nwri_dat|        :        |        |
|          |        :        |        :nget_nod|        :        |        |
|          |        :        |        :nget_ver|        :        |        |
+----------+--------+--------+--------+--------+--------+--------+--------+

****************************************************************************
***    6.2 System Calls                                                  ***
****************************************************************************

        The '=' symbol is appended to indicate return parameters.

============================================================================
/// Task Management Functions ///
----------------------------------------------------------------------------
Level   System Call   Parameters/         Description
                      Return Parameters
                      (indicated by =)
----------------------------------------------------------------------------
EN      cre_tsk       tskid   pk_ctsk     Create Task
EN      del_tsk       tskid               Delete Task
SN      sta_tsk       tskid   stacd       Start Task
S       ext_tsk                           Exit Task
E       exd_tsk                           Exit and Delete Task
SN      ter_tsk       tskid               Terminate Other Task
R       dis_dsp                           Disable Dispatch
R       ena_dsp                           Enable Dispatch
SN      chg_pri       tskid   tskpri      Change Task Priority
S       rot_rdq       tskpri              Rotate Tasks on the Ready Queue
SN      rel_wai       tskid               Release Wait of Other Task
S       get_tid       tskid=              Get Task Identifier
EN      ref_tsk       tskid   pk_rtsk     Reference Task Status


============================================================================
/// Task-Dependent Synchronization ///
----------------------------------------------------------------------------
Level   System Call   Parameters/         Description
                      Return Parameters
                      (indicated by =)
----------------------------------------------------------------------------
SN      sus_tsk       tskid               Suspend Other Task
SN      rsm_tsk       tskid               Resume Suspended Task
EN      frsm_tsk      tskid               Forcibly Resume Suspended Task
R       slp_tsk                           Sleep Task
E       tslp_tsk      tmout               Sleep Task with Timeout
RN      wup_tsk       tskid               Wakeup Other Task
SN      can_wup       tskid   wupcnt=     Cancel Wakeup Request


============================================================================
/// Synchronization and Communication Functions ///
----------------------------------------------------------------------------
Level   System Call   Parameters/         Description
                      Return Parameters
                      (indicated by =)
----------------------------------------------------------------------------
EN      cre_sem       semid   pk_csem     Create Semaphore
EN      del_sem       semid               Delete Semaphore
RN      sig_sem       semid               Signal Semaphore
RN      wai_sem       semid               Wait on Semaphore
RN      preq_sem      semid               Poll and Request Semaphore
EN      twai_sem      semid   tmout       Wait on Semaphore with Timeout
EN      ref_sem       semid   pk_rsem     Reference Semaphore Status
EN      cre_flg       flgid   pk_cflg     Create Eventflag
EN      del_flg       flgid               Delete Eventflag
SN      set_flg       flgid   setptn      Set Eventflag
SN      clr_flg       flgid   clrptn      Clear Eventflag
SN      wai_flg       flgid   waiptn  flgptn= wfmode
                                          Wait on Eventflag
SN      pol_flg       flgid   waiptn  flgptn= wfmode
                                          Poll Eventflag
EN      twai_flg      flgid   waiptn  flgptn= wfmode tmout
                                          Wait on Eventflag with Timeout
EN      ref_flg       flgid   pk_rflg     Reference Eventflag Status
E       cre_mbx       mbxid   pk_cmbx     Create Mailbox
E       del_mbx       mbxid               Delete Mailbox
S       snd_msg       mbxid   pk_msg      Send Message to Mailbox
S       rcv_msg       mbxid   pk_msg=     Receive Message from Mailbox
S       prcv_msg      mbxid   pk_msg=     Poll and Receive Message from
                                          Mailbox
E       trcv_msg      mbxid   pk_msg= tmout
                                          Receive Message from Mailbox with
                                          Timeout
E       ref_mbx       mbxid   pk_rmbx     Reference Mailbox Status


============================================================================
/// Extended Synchronization and communication Functions ///
----------------------------------------------------------------------------
Level   System Call   Parameters/         Description
                      Return Parameters
                      (indicated by =)
----------------------------------------------------------------------------
EN      cre_mbf       mbfid   pk_cmbf     Create Message Buffer
EN      del_mbf       mbfid               Delete Message Buffer
EN      snd_mbf       mbfid   msgsz   msg
                                          Send Message to Message Buffer
EN      psnd_mbf      mbfid   msgsz   msg
                                          Poll and Send Message to Message
                                          Buffer
EN      tsnd_mbf      mbfid   msgsz   msg     tmout
                                          Send Message to Message Buffer with
                                          Timeout
EN      rcv_mbf       mbfid   msgsz=  msg
                                          Receive Message from Message Buffer
EN      prcv_mbf      mbfid   msgsz=  msg
                                          Poll and Receive Message from
                                          Message Buffer
EN      trcv_mbf      mbfid   msgsz=  msg     tmout
                                          Receive Message from Message Buffer
                                          with Timeout
EN      ref_mbf       mbfid   pk_rmbf     Reference Message Buffer Status
EN      cre_por       porid   pk_cpor     Create Port for Rendezvous
EN      del_por       porid               Delete Port for Rendezvous
EN      cal_por       porid   calptn  msg     cmsgsz rmsgsz=
                                          Call Port for Rendezvous
EN      pcal_por      porid   calptn  msg     cmsgsz rmsgsz=
                                          Poll and Call Port for Rendezvous
EN      tcal_por      porid   calptn  msg     cmsgsz rmsgsz= tmout
                                          Call Port for Rendezvous with
                                          Timeout
E       acp_por       porid   acpptn  rdvno=  msg cmsgsz=
                                          Accept Port for Rendezvous
E       pacp_por      porid   acpptn  rdvno=  msg cmsgsz=
                                          Poll and Accept Port for Rendezvous
E       tacp_por      porid   acpptn  rdvno=  msg cmsgsz= tmout
                                          Accept Port for Rendezvous with
                                          Timeout
E       fwd_por       porid   calptn  rdvno   msg cmsgsz
                                          Forward Rendezvous to another Port
E       rpl_rdv       rdvno   msg     rmsgsz
                                          Reply Rendezvous
EN      ref_por       porid   pk_rpor     Reference Port Status


============================================================================
/// Interrupt Management Functions ///
----------------------------------------------------------------------------
Level   System Call   Parameters/         Description
                      Return Parameters
                      (indicated by =)
----------------------------------------------------------------------------
C       def_int       dintno  pk_dint     Define Interrupt Handler
R       ret_int                           Return from Interrupt Handler
E       ret_wup       tskid               Return and Wakeup Task
R       loc_cpu                           Lock CPU
R       unl_cpu                           Unlock CPU
C       dis_int       eintno              Disable Interrupt
C       ena_int       eintno              Enable Interrupt
C       chg_iXX       iXXXX               Change Interrupt Mask
                                          (Level and Priority)
C       ref_iXX       iXXXX=              Reference Interrupt Mask
                                          (Level and Priority)


============================================================================
/// Memorypool Management Functions ///
----------------------------------------------------------------------------
Level   System Call   Parameters/         Description
                      Return Parameters
                      (indicated by =)
----------------------------------------------------------------------------
E       cre_mpl       mplid   pk_cmpl     Create Variable-Size Memorypool
E       del_mpl       mplid               Delete Variable-Size Memorypool
E       get_blk       mplid   blksz   blk=
                                          Get Variable-Size Memory Block
E       pget_blk      mplid   blksz   blk=
                                          Poll and Get Variable-Size Memory
                                          Block
E       tget_blk      mplid   blksz   blk=    tmout
                                          Get Variable-Size Memory Block with
                                          Timeout
E       rel_blk       mplid   blk         Release Variable-Size Memory Block
E       ref_mpl       mplid   pk_rmpl     Reference Variable-Size Memorypool
                                          Status
E       cre_mpf       mpfid   pk_cmpf     Create Fixed-Size Memorypool
E       del_mpf       mpfid               Delete Fixed-Size Memorypool
E       get_blf       mpfid   blf=        Get Fixed-Size Memory Block
E       pget_blf      mpfid   blf=        Poll and Get Fixed-Size Memory Block
E       tget_blf      mpfid   blf=    tmout
                                          Get Fixed-Size Memory Block with
                                          Timeout
E       rel_blf       mpfid   blf         Release Fixed-Size Memory Block
E       ref_mpf       mpfid   pk_rmpf     Reference Fixed-Size Memorypool
                                          Status


============================================================================
/// Time Management Functions ///
----------------------------------------------------------------------------
Level   System Call   Parameters/         Description
                      Return Parameters
                      (indicated by =)
----------------------------------------------------------------------------
S       set_tim       pk_tim              Set System Clock
S       get_tim       pk_tim              Reference System Clock
S       dly_tsk       dlytim              Delay Task
E       def_cyc       cycno   pk_dcyc     Define Cyclic Handler
E       act_cyc       cycno   cycact      Activate Cyclic Handler
E       ref_cyc       cycno   pk_rcyc     Reference Cyclic Handler Status
E       def_alm       almno   pk_dalm     Define Alarm Handler
E       ref_alm       almno   pk_ralm     Reference Alarm Handler Status
E       ret_tmr                           Return from Timer Handler


============================================================================
/// System Management Functions ///
----------------------------------------------------------------------------
Level   System Call   Parameters/         Description
                      Return Parameters
                      (indicated by =)
----------------------------------------------------------------------------
R       get_ver       pk_ver              Get Version Information
E       ref_sys       pk_rsys             Reference System Status
C       ref_cfg       pk_rcfg             Reference Configuration Information
C       def_svc       s_fncd  pk_dsvc     Define Extended SVC Handler
C       def_exc       exckind pk_dexc     Define Exception Handler


============================================================================
/// Network Support Functions ///
----------------------------------------------------------------------------
Level   System Call   Parameters/         Description
                      Return Parameters
                      (indicated by =)
----------------------------------------------------------------------------
SN      nrea_dat      srcnode srcadr  dstadr  datsz reasz=
                                          Read Data from Another Node
SN      nwri_dat      srcadr  dstnode dstadr  datsz wrisz=
                                          Write Data to Another Node
SN      nget_nod      node=               Reference Local Node Number
SN      nget_ver      node    pk_ver      Get Version Information of Another
                                          Node

============================================================================

  Note: The 'XX' part of the names of system calls chg_iXX and ref_iXX, used
        for changing and referencing interrupt masks (level and priority), is
        chosen to match the CPU architecture in question.

****************************************************************************
***    6.3 Function Codes                                                ***
****************************************************************************

[Function Code Assignment]
  Reserved:                     H'fe00 - H'fe7f (-512)-(-385) 128 functions
  File and device management:   H'fe80 - H'febf (-384)-(-321)  64 functions
  Debug support:                H'fec0 - H'feff (-320)-(-257)  64 functions
  For system configuration:     H'ff00 - H'ff1f (-256)-(-225)  32 functions
  Standard system calls (including I/O, MMU):
                                H'ff20 - H'fffb (-224)-(-5)   220 functions
  Reserved:                     H'fffc - H'0000   (-4)-(0)      5 functions
  For user use (extended SVC):  H'0001 -             1-

    Note: The function codes of system calls of support levels [RN] and [SN]
          range from H'ff80 to H'ffff.

[Standard Function Code Values]
  * '-' indicates reserved function codes.
  * Depending on the CPU and the implementation, function codes may not be
    used for some system calls (such as ret_int).  Some implementations may use
    subroutine jump to call OS without even using any function codes at all.
  * There is no strict distinction between the "Open" and the "Closed"
    classifications given for "For System Configuration".

+--------+---------------+---------------+---------------+---------------+
|        | +H'0          | +H'4          | +H'8          | +H'c          |
+--------+---------------+---------------+---------------+---------------+
| H'ff00 | For System Configuration, Implementation-Dependent            |
|        | (v???_???) [Open for Application Programers]                  |
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ff10 | For System Configuration, Implementation-Dependent            |
|        | (v???_???) [Closed within Implementors]                       |
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ff20 |                    MMU Support - reserved                     |
|        |-   -   -   -   -   -   -   -   -   -   -   -   -   -   -   -  |
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ff30 |      Standard I/O Management - reserved       :   reserved    |
|        |-   -   -   -            -   -   -             :               |
|        |put get put get -   -   ctl ref req -   -   -  :-   -   -   -  |
|        |lin lin chr chr         cio cio gio            :               |
+--------+---------------+---------------+---------------+---------------+
| H'ff40 |            Network            :           reserved            |
|        |-   -   -   -   -   -   -   -  :-   -   -   -   -   -   -   -  |
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ff50 |                   Timeouts                    :   reserved    |
|        |t   t   t   t   t   t   t       t   t          :               |
|        |acp cal rcv snd rcv wai wai -   get get -   -  :               |
|        |por por mbf mbf msg sem flg     blk blf        :               |
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ff60 |        Message Buffers        :      Rendezvous (Ports)       |
|        |                               :                               |
|        |-   -   rcv snd ref -   del cre:fwd rpl acp cal ref ref del cre|
|        |        mbf mbf mbf     mbf mbf:por rdv por por por rdv por por|
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ff70 |   Variable-Size Memorypool    :            reserved           |
|        |-u      -u                     :                               |
|        |rel rel get get ref ref del cre:-   -   -   -   -   -   -   -  |
|        |blk blk blk blk mpl blk mpl mpl:                               |
+--------+---------------+---------------+---------------+---------------+

+--------+---------------+---------------+---------------+---------------+
| H'ff80 |           Exclusively for Task-Independent Portions           |
|        |    i       ip  i   i   i   i   ip  ip  i   i   if  i       i  |
|        |-   rel     snd snd sig set wup get get rot chg rsm rsm     sus|
|        |    wai     mbf msg sem flg tsk blk blf rdq pri tsk tsk     tsk|
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ff90 |                    Polling                    :    Network    |
|        |P   P   P   P   P   P           P   P          :n   n   n   n  |  ^
|        |acp cal rcv snd rcv req pol     get get        :wri rea get get|  |
|        |por por mbf mbf msg sem flg     blk blf        :dat dat ver nod| (*1)
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+---
| H'ffa0 |                        Time Management                        |
|        |                                -   -                          |
|        |-   -   act ret ref ref def def can cyc -   dly get set -   -  |
|        |        cyc tmr cyc alm cyc alm cyc wup     tsk tim tim        |
|        |               Name Name        V2  V2                         |
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ffb0 |     Fixed-Size Memorypool     :     Interrupt Management      |
|        |          Management           :                               |
|        |-u      -u          -          :                               |
|        |rel rel get get ref ref del cre:dis ena ret ret ref chg -   def|
|        |blf blf blf blf mpf blf mpf mpf:int int wup int iXX iXX     int|
|        |V2 Name V2 Name NameV2 NameName:                Name           |
+--------+---------------+---------------+---------------+---------------+
| H'ffc0 |           Mailboxes           :          Semaphores           |
|        |-u      -u                     :-u          -u                 |
|        |snd snd rcv rcv ref -   del cre:sig sig wai wai ref -   del cre|
|        |msg msg msg msg mbx     mbx mbx:sem sem sem sem sem     sem sem|
|        |V2      V2      Name           :V2      V2      Name           |
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ffd0 |           Eventflags          :Task-Dependent Synchronization |
|        |            -c                 :            t   f              |
|        |set clr wai wai ref -   del cre:can wup slp slp rsm rsm -   sus|
|        |flg flg flg flg flg     flg flg:wup tsk tsk tsk tsk tsk     tsk|
|        |            V2  Name           :            Name               |
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'ffe0 |                        Task Management                        |
|        |-                       -                           -          |
|        |ras rel dis ena rot chg abo ter get sta exd ext ref hdr del cre|
|        |ext wai dsp dsp rdq pri tsk tsk tid tsk tsk tsk tsk sts tsk tsk|
|        |V2      New New         V2                      Name V2        |
+--------+- - - - - - - -+- - - - - - - -+- - - - - - - -+- - - - - - - -+
| H'fff0 |    System Management, Interrupt Management    :   reserved    |
|        |            -           -s                     :               |
|        |get -   ref ret ref def def def loc unl -   -  :=   =   =   =  |
|        |ver     cfg svc sys exc svc svc cpu cpu        :               |
|        |        New V2 Name New V2      New New        :               |
+--------+---------------+---------------+---------------+---------------+

  (*1): Entirely updated from ITRON2 specification up to this place


[Differences from uITRON 2.0 and ITRON2 Specifications]

  - Function code assignments and values throughout the range H'ffa0 through
    H'ffff remain unchanged from those used in conventional ITRON2 and uITRON
    2.0 specifications.

        This part corresponds to the basic functions of ITRON2 specification
        (excluding for exception management).

        Fixed-size memorypool management functions are assigned in the range
        H'ffb0 through H'ffb7 associated with memorypool management.

        Even system calls whose names have been changed sometimes use the same
        function code value as long as they still represent the same function.
        These are indicated in the table by 'Name'.  (such system calls as
        ???_sts and ref_???.)

        System calls which have been newly added under uITRON 3.0
        specification are indicated in the table by 'New'.  System calls used
        under ITRON2 and uITRON 2.0 specifications (including reserved
        function codes), but not used under uITRON 3.0 specification, are
        indicated by 'V2'.

  - Function code assignments and values throughout the range H'ff20 through
    H'ff9f have been completely changed from those used in conventional ITRON2
    and uITRON 2.0 specifications.

        This part corresponds to the region used for exception management,
        extended features (rendezvous and messagebuffers) of ITRON2
        specification, MMU support functions, and polling functions (p???_???).
        The function codes for these system calls are reconsidered since many
        of these functions are meaningless under uITRON 3.0 specification.

****************************************************************************
***    6.4 Data Types                                                    ***
****************************************************************************

***  General-Purpose Data Types ********************************************

    B       signed 8-bit integer
    H       signed 16-bit integer
    W       signed 32-bit integer
    UB      unsigned 8-bit integer
    UH      unsigned 16-bit integer
    UW      unsigned 32-bit integer

    VW      unpredictable data type (32-bit size)
    VH      unpredictable data type (16-bit size)
    VB      unpredictable data type (8-bit size)

    VP      pointer to an unpredictable data type

    FP      program start address

      * The difference between VB, VH and VW and B, H and W is that only the
        number of bits is known for the former, not the data type of the
        contents.  The latter clearly represent integers.

***  Data Types Dependent on ITRON Specification ***************************

In order to clarify the meanings of certain parameters, the following names
are used for data types which appear frequently and/or have special meanings.

    INT     Signed integer (bit width of processor)
    UINT    Unsigned integer (bit width of processor)
    BOOL    Boolean value.  TRUE (1) or FALSE (0).
    FN      Function code.  Signed integer.  Maximum 2 bytes.
    ID      Object ID number (???id)
            Value range depends on the system.  Usually a signed integer.
            Certain ID values may represent objects on other nodes when the
            connection function is supported.
    BOOL_ID Boolean value or ID number
    HNO     Handler number
    RNO     Rendezvous number
    NODE    Node Number.  Usually a signed integer.
    ATR     Object or handler attribute.  An unsigned integer.
    ER      Error code.  A signed integer.
    PRI     Task priority.  A signed integer.
    T_MSG   Message packet data structure used for mailboxes
    TMO     Timeout value.  A signed integer.
            TMO_POL = 0 indicates polling, while TMO_FEVR = -1 indicates wait
            forever.
    SYSTIME, CYCTIME, ALMTIME, DLYTIME
            Data types used for specifying times.  Often split into upper and
            lower sections.  For details, see the chapter giving system call
            descriptions.

      * The bit width of these data types and associated range of values
        depends on the processor and the implementation.

      * Since the bit width of the processor being used is varied under
        uITRON 3.0 specification, coding which clarifies bit width such as
        W, H, UW or UH is not used very often in the C language interface.
        Rather INT and UINT are often used.  Under various implementations of
        uITRON 3.0 specification, however, W, H, UW, UH may be used in place
        of INT and UINT in product manuals because the bit width of the
        processor being used is known.

      * For example, INT is equivalent to H, and UINT is to UH in its meaning
        when implementing uITRON 3.0 specification on a 16-bit processor.
        In this case, it is possible to code the following:

            typedef H       INT;    /* when using a 16-bit processor */
            typedef UH      UINT;   /* when using a 16-bit processor */

      * It is necessary for each implementor to clarify the correspondence
        between the above data types and the actual bit width.

****************************************************************************
***    6.5 C Language Interfaces                                         ***
****************************************************************************

 - Task Management Functions

      ER ercd = cre_tsk ( ID tskid, T_CTSK *pk_ctsk );
      ER ercd = del_tsk ( ID tskid );
      ER ercd = sta_tsk ( ID tskid, INT stacd );
           void ext_tsk ( );
           void exd_tsk ( );
      ER ercd = ter_tsk ( ID tskid );
      ER ercd = dis_dsp ( );
      ER ercd = ena_dsp ( );
      ER ercd = chg_pri ( ID tskid, PRI tskpri );
      ER ercd = rot_rdq ( PRI tskpri );
      ER ercd = rel_wai ( ID tskid );
      ER ercd = get_tid ( ID *p_tskid );
      ER ercd = ref_tsk ( T_RTSK *pk_rtsk, ID tskid );

 - Task-Dependent Synchronization Functions

      ER ercd = sus_tsk ( ID tskid );
      ER ercd = rsm_tsk ( ID tskid );
      ER ercd =frsm_tsk ( ID tskid );
      ER ercd = slp_tsk ( );
      ER ercd =tslp_tsk ( TMO tmout );
      ER ercd = wup_tsk ( ID tskid );
      ER ercd = can_wup ( INT *p_wupcnt, ID tskid );

 - Synchronization and Communication Functions

      ER ercd = cre_sem ( ID semid, T_CSEM *pk_csem );
      ER ercd = del_sem ( ID semid );
      ER ercd = sig_sem ( ID semid );
      ER ercd = wai_sem ( ID semid );
      ER ercd =preq_sem ( ID semid );
      ER ercd =twai_sem ( ID semid, TMO tmout );
      ER ercd = ref_sem ( T_RSEM *pk_rsem, ID semid );
      ER ercd = cre_flg ( ID flgid, T_CFLG *pk_cflg );
      ER ercd = del_flg ( ID flgid );
      ER ercd = set_flg ( ID flgid, UINT setptn );
      ER ercd = clr_flg ( ID flgid, UINT clrptn );
      ER ercd = wai_flg ( UINT *p_flgptn, ID flgid, UINT waiptn, UINT wfmode );
      ER ercd = pol_flg ( UINT *p_flgptn, ID flgid, UINT waiptn, UINT wfmode );
      ER ercd =twai_flg ( UINT *p_flgptn, ID flgid, UINT waiptn, UINT wfmode,
                          TMO tmout );
      ER ercd = ref_flg ( T_RFLG *pk_rflg, ID flgid );
      ER ercd = cre_mbx ( ID mbxid, T_CMBX* pk_cmbx );
      ER ercd = del_mbx ( ID mbxid );
      ER ercd = snd_msg ( ID mbxid, T_MSG *pk_msg );
      ER ercd = rcv_msg ( T_MSG **ppk_msg, ID mbxid );
      ER ercd =prcv_msg ( T_MSG **ppk_msg, ID mbxid );
      ER ercd =trcv_msg ( T_MSG **ppk_msg, ID mbxid, TMO tmout );
      ER ercd = ref_mbx ( T_RMBX *pk_rmbx, ID mbxid );

 - Extended Synchronization and Communication Functions

      ER ercd = cre_mbf ( ID mbfid, T_CMBF *pk_cmbf );
      ER ercd = del_mbf ( ID mbfid );
      ER ercd = snd_mbf ( ID mbfid, VP msg, INT msgsz );
      ER ercd =psnd_mbf ( ID mbfid, VP msg, INT msgsz );
      ER ercd =tsnd_mbf ( ID mbfid, VP msg, INT msgsz, TMO tmout );
      ER ercd = rcv_mbf ( VP msg, INT *p_msgsz, ID mbfid );
      ER ercd =prcv_mbf ( VP msg, INT *p_msgsz, ID mbfid );
      ER ercd =trcv_mbf ( VP msg, INT *p_msgsz, ID mbfid, TMO tmout );
      ER ercd = ref_mbf ( T_RMBF *pk_rmbf, ID mbfid );
      ER ercd = cre_por ( ID porid, T_CPOR *pk_cpor );
      ER ercd = del_por ( ID porid );
      ER ercd = cal_por ( VP msg, INT *p_rmsgsz, ID porid, UINT calptn, INT
                          cmsgsz );
      ER ercd =pcal_por ( VP msg, INT *p_rmsgsz, ID porid, UINT calptn, INT
                          cmsgsz );
      ER ercd =tcal_por ( VP msg, INT *p_rmsgsz, ID porid, UINT calptn, INT
                          cmsgsz, TMO tmout );
      ER ercd = acp_por ( RNO *p_rdvno, VP msg, INT *p_cmsgsz, ID porid, UINT
                          acpptn );
      ER ercd =pacp_por ( RNO *p_rdvno, VP msg, INT *p_cmsgsz, ID porid, UINT
                          acpptn );
      ER ercd =tacp_por ( RNO *p_rdvno, VP msg, INT *p_cmsgsz, ID porid, UINT
                          acpptn, TMO tmout );
      ER ercd = fwd_por ( ID porid, UINT calptn, RNO rdvno, VP msg, INT cmsgsz
                          );
      ER ercd = rpl_rdv ( RNO rdvno, VP msg, INT rmsgsz );
      ER ercd = ref_por ( T_RPOR *pk_rpor, ID porid );

 - Interrupt Management Functions

      ER ercd = def_int ( UINT dintno, T_DINT *pk_dint );
           void ret_int ( );
           void ret_wup ( ID tskid );
      ER ercd = loc_cpu ( );
      ER ercd = unl_cpu ( );
      ER ercd = dis_int ( UINT eintno );
      ER ercd = ena_int ( UINT eintno );
      ER ercd = chg_iXX ( UINT iXXXX );
      ER ercd = ref_iXX ( UINT *p_iXXXX );

 - Memorypool Management Functions

      ER ercd = cre_mpl ( ID mplid, T_CMPL *pk_cmpl );
      ER ercd = del_mpl ( ID mplid );
      ER ercd = get_blk ( VP *p_blk, ID mplid, INT blksz );
      ER ercd =pget_blk ( VP *p_blk, ID mplid, INT blksz );
      ER ercd =tget_blk ( VP *p_blk, ID mplid, INT blksz, TMO tmout );
      ER ercd = rel_blk ( ID mplid, VP blk );
      ER ercd = ref_mpl ( T_RMPL *pk_rmpl, ID mplid );
      ER ercd = cre_mpf ( ID mpfid, T_CMPF *pk_cmpf );
      ER ercd = del_mpf ( ID mpfid );
      ER ercd = get_blf ( VP *p_blf, ID mpfid );
      ER ercd =pget_blf ( VP *p_blf, ID mpfid );
      ER ercd =tget_blf ( VP *p_blf, ID mpfid, TMO tmout );
      ER ercd = rel_blf ( ID mpfid, VP blf );
      ER ercd = ref_mpf ( T_RMPF *pk_rmpf, ID mpfid );

 - Time Management Functions

      ER ercd = set_tim ( SYSTIME *pk_tim );
      ER ercd = get_tim ( SYSTIME *pk_tim );
      ER ercd = dly_tsk ( DLYTIME dlytim );
      ER ercd = def_cyc ( HNO cycno, T_DCYC *pk_dcyc );
      ER ercd = act_cyc ( HNO cycno, UINT cycact );
      ER ercd = ref_cyc ( T_RCYC *pk_rcyc, HNO cycno );
      ER ercd = def_alm ( HNO almno, T_DALM *pk_dalm );
      ER ercd = ref_alm ( T_RALM *pk_ralm, HNO almno );
           void ret_tmr ( );

 - System Management Functions

      ER ercd = get_ver ( T_VER *pk_ver );
      ER ercd = ref_sys ( T_RSYS *pk_rsys );
      ER ercd = ref_cfg ( T_RCFG *pk_rcfg );
      ER ercd = def_svc ( FN s_fncd, T_DSVC *pk_dsvc );
      ER ercd = def_exc ( UINT exckind, T_DEXC *pk_dexc );

 - Network Support Functions

     ER ercd = nrea_dat ( INT *p_reasz, VP dstadr, NODE srcnode, VP srcadr,
                          INT datsz );
     ER ercd = nwri_dat ( INT *p_wrisz, NODE dstnode, VP dstadr, VP srcadr,
                          INT datsz );
     ER ercd = nget_nod ( NODE *p_node );
     ER ercd = nget_ver ( T_VER *pk_ver, NODE node );

****************************************************************************
***    6.6 Common Constants and Data Structure Packet Formats            ***
****************************************************************************

/* --- overall ----------------------- */

        NADR   (-1)   /* invalid address or pointer value */
        TRUE     1    /* true */
        FALSE    0    /* false */

   ATR tskatr, intatr, cycatr, almatr, svcatr, excatr:
        TA_ASM    H'0...00   /* program written in assembly language */
        TA_HLNG   H'0...01   /* program written in high-level language */
          * TA_ASM indicates that the task or handler is directly started
            at the assembly language level.  The TA_ASM attribute has the
            opposite meaning of TA_HLNG.

   TMO tmout:
        TMO_POL      0    /* polling */
        TMO_FEVR   (-1)   /* wait forever */

/* --- function codes ----------------------- */

        TFN_CRE_TSK   (-17) H'ffef   /* create task */
        TFN_STA_TSK   (-23) H'ffe9   /* start task */
                ...
        TFN_DEF_INT   (-65) H'ffbf   /* define interrupt handler */
                ...

          * Use a mnemonic of the form TFN_XXX_YYY for the function code to
            invoke a system call of the form xxx_yyy.  Use a mnemonic of the
            form TFN_ZXXX_YYY for the function code to invoke a system call of
            the form zxxx_yyy.  The mnemonics used for the function code of a
            typical system call follows this convention.

/* --- for task management functions ----------------------- */

    /* cre_tsk */
        typedef struct t_ctsk {
                VP    exinf;     /* extended information */
                ATR   tskatr;    /* task attributes */
                FP    task;      /* task start address */
                PRI   itskpri;   /* initial task priority */
                INT   stksz;     /* stack size */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_CTSK;

    tskatr:
        TA_ASM    H'0...00     /* program written in assembly language */
        TA_HLNG   H'0...01     /* program written in high-level language */
        TA_COP0   H'0...8000   /* uses coprocessor having ID = 0 */
        TA_COP1   H'0...4000   /* uses coprocessor having ID = 1 */
        TA_COP2   H'0...2000   /* uses coprocessor having ID = 2 */
        TA_COP3   H'0...1000   /* uses coprocessor having ID = 3 */
        TA_COP4   H'0...0800   /* uses coprocessor having ID = 4 */
        TA_COP5   H'0...0400   /* uses coprocessor having ID = 5 */
        TA_COP6   H'0...0200   /* uses coprocessor having ID = 6 */
        TA_COP7   H'0...0100   /* uses coprocessor having ID = 7 */

    tskid:
        TSK_SELF   0   /* task specifies itself */
        FALSE      0   /* indicates a task-independent portion (return
                          parameters only) */

    tskpri:
        TPRI_INI   0   /* specifies the initial priority on task startup
                          (chg_pri) */
        TPRI_RUN   0   /* specifies the highest priority during execution
                          (rot_rdq) */

    /* ref_tsk */
        typedef struct t_rtsk {
                VP     exinf;     /* extended information */
                PRI    tskpri;    /* current priority */
                UINT   tskstat;   /* task state */
            /* the following are represent extended features of support
               [level X] (implementation-dependent) */
                UINT   tskwait;   /* cause of wait */
                ID     wid;       /* ID of object being waited for */
                INT    wupcnt;    /* wakeup request count */
                INT    suscnt;    /* SUSPEND request count */
                ATR    tskatr;    /* task attributes */
                FP     task;      /* task start address */
                PRI    itskpri;   /* initial task priority */
                INT    stksz;     /* stack size */
                        ...
        } T_RTSK;

    tskstat:
        TTS_RUN   H'0...01   /* RUN */
        TTS_RDY   H'0...02   /* READY */
        TTS_WAI   H'0...04   /* WAIT */
        TTS_SUS   H'0...08   /* SUSPEND */
        TTS_WAS   H'0...0C   /* WAIT-SUSPEND */
        TTS_DMT   H'0...10   /* DORMANT */

    tskwait:
        TTW_SLP   H'0...0001   /* wait due to slp_tsk or tslp_tsk */
        TTW_DLY   H'0...0002   /* wait due to dly_tsk */
        TTW_NOD   H'0...0008   /* connection function response wait */
        TTW_FLG   H'0...0010   /* wait due to wai_flg or twai_flg */
        TTW_SEM   H'0...0020   /* wait due to wai_sem or twai_sem */
        TTW_MBX   H'0...0040   /* wait due to rcv_msg or trcv_msg */
        TTW_SMBF  H'0...0080   /* wait due to snd_mbf or tsnd_mbf */
        TTW_MBF   H'0...0100   /* wait due to rcv_mbf or trcv_mbf */
        TTW_CAL   H'0...0200   /* wait for rendezvous call */
        TTW_ACP   H'0...0400   /* wait for rendezvous accept */
        TTW_RDV   H'0...0800   /* wait for rendezvous completion */
        TTW_MPL   H'0...1000   /* wait due to get_blk or tget_blk */
        TTW_MPF   H'0...2000   /* wait due to get_blf or tget_blf */

          * Since the task states given by tskstat and tskwait are expressed
            by bit correspondences, they are convenient when looking for OR
            conditions (such as whether a task is in WAIT or READY state).

/* --- for semaphore functions ----------------------- */

    /* cre_sem */
        typedef struct t_csem {
                VP    exinf;    /* extended information */
                ATR   sematr;   /* semaphore attributes */
            /* Following is the extended function for [level X].
                INT   isemcnt;   /* initial semaphore count */
                INT   maxsem;    /* maximum semaphore count */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_CSEM;

    sematr:
        TA_TFIFO   H'0...00   /* waiting tasks are handled by FIFO */
        TA_TPRI    H'0...01   /* waiting tasks are handled by priority */

    /* ref_sem */
        typedef struct t_rsem {
                VP      exinf;    /* extended information */
                BOOL_ID wtsk;     /* indicates whether or not there is a
                                     waiting task */
                INT     semcnt;   /* current semaphore count */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RSEM;

/* --- for eventflag functions ----------------------- */

    /* cre_flg */
        typedef struct t_cflg {
                VP     exinf;     /* extended information */
                ATR    flgatr;    /* eventflag attribute */
                UNIT   iflgptn;   /* initial eventflag */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_CFLG;

    flgatr:
        TA_WSGL   H'0...00   /* multiple tasks are not allowed to wait (Wait
                                Single Task) */
        TA_WMUL   H'0...08   /* multiple tasks are allowed to wait (Wait
                                Multiple Task) */

    wfmode:
        TWF_ANDW   H'0...00   /* AND wait */
        TWF_ORW    H'0...02   /* OR wait */
        TWF_CLR    H'0...01   /* clear specification */

    /* ref_flg */
        typedef struct t_rflg {
                VP        exinf;      /* extended information */
                BOOL_ID   wtsk;       /* indicates whether or not there is a
                                         waiting task */
                UINT      flgptn;     /* eventflag bit pattern */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RFLG;

/* --- for mailbox functions ----------------------- */

   /* cre_mbx */
        typedef struct t_cmbx {
                VP    exinf;    /* extended information */
                ATR   mbxatr;   /* mailbox attributes */
            /* Following is implementation-dependent function */
                INT   bufcnt;   /* ring buffer size */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_CMBX;

    mbxatr:
        TA_TFIFO   H'0...00   /* waiting tasks are handled by FIFO */
        TA_TPRI    H'0...01   /* waiting tasks are handled by priority */
        TA_MFIFO   H'0...00   /* messages are handled by FIFO */
        TA_MPRI    H'0...02   /* messages are handled by priority */

        typedef struct t_msg {
            /* a region (header) reserved by the OS may be included first
               depending on the implementation */
                        ...
                VB   msgcont[];
        } T_MSG;

    /* ref_mbx */
        typedef struct t_rmbx {
                VP        exinf;    /* extended information */
                BOOL_ID   wtsk;     /* indicates whether or not there is a
                                       waiting task */
                T_MSG*    pk_msg;   /* message to be sent next */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RMBX;

/* --- for messagebuffer functions ----------------------- */

    /* cre_mbf */
        typedef struct t_cmbf {
                VP    exinf;    /* extended information */
                ATR   mbfatr;   /* messagebuffer attributes */
                INT   bufsz;    /* messagebuffer size */
                INT   maxmsz;   /* maximum size of messages */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_CMBF:

    mbfatr:
        TA_TFIFO   H'0...00   /* tasks waiting to receive messages are handled
                                 by FIFO */
        TA_TPRI    H'0...01   /* tasks waiting to receive messages are handled
                                 by priority */

    mbfid:
        TMBF_OS   (-4)   /* messagebuffer used for OS error log */
        TMBF_DB   (-3)   /* messagebuffer used for debugging */

    /* ref_mbf */
        typedef struct t_rmbf {
                VP        exinf;     /* extended information */
                BOOL_ID   wtsk;      /* indicates whether or not there is a
                                        task waiting to receive a message */
                BOOL_ID   stsk;      /* indicates whether or not there is a
                                        task waiting to send a message */
                INT       msgsz;     /* size of message to be sent next */
                INT       frbufsz;   /* size of free buffer */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RMBF;

/* --- for port or rendezvous functions ----------------------- */

    /* cre_por */
        typeder struct t_cpor {
                VP    exinf;     /* extended information */
                ATR   poratr;    /* port attributes */
                INT   maxcmsz;   /* maximum call message size */
                INT   maxrmsz;   /* maximum reply message size */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_CPOR;

    poratr:
        TA_NULL   0   /* specifies no particular attributes */
          * TA_NULL should be used in place of zeroes to turn off all
            attribute features.

    /* ref_por */
        typedef struct t_rpor {
                VP        exinf;   /* extended information */
                BOOL_ID   wtsk;    /* indicates whether or not there is a task
                                      waiting to call a rendezvous */
                BOOL_ID   atsk;    /* indicates whether or not there is a task
                                      waiting to accept a rendezvous */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RPOR;

/* --- for interrupt management functions ----------------------- */

    /* def_int */
        typedef struct t_dint {
                ATR   intatr;   /* interrupt handler attributes */
                FP    inthdr;   /* interrupt handler address */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_DINT;

/* --- for memorypool management functions ----------------------- */

    /* cre_mpl */
        typedef struct t_cmpl {
                VP    exinf;    /* extended information */
                ATR   mplatr;   /* memorypool attributes */
                INT   mplsz;    /* memorypool size */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_CMPL;

    mplatr:
        TA_TFIFO   H'0...00   /* waiting tasks are handled by FIFO */
        TA_TPRI    H'0...01   /* waiting tasks are handled by priority */

    mplid:
        TMPL_OS   (-4)   /* memorypool used by OS */

    /* ref_mpl */
        typedef struct t_rmpl {
                VP        exinf;    /* extended information */
                BOOL_ID   wtsk;     /* indicates whether or not there are
                                       waiting tasks */
                INT       frsz;     /* total size of free memory */
                INT       maxsz;    /* size of largest contiguous memory */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RMPL:

    /* cre_mpf */
        typedef struct t_cmpf {
                VP    exinf;     /* extended information */
                ATR   mpfatr;    /* memorypool attributes */
                INT   mpfcnt;    /* block count for entire memorypool */
                INT   blfsz;     /* fixed-size memory block size */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_CMPF;

    mpfatr:
        TA_TFIFO   H'0...00   /* waiting tasks are handled by FIFO */
        TA_TPRI    H'0...01   /* waiting tasks are handled by priority */

    /* ref_mpf */
        typedef struct t_rmpf {
                VP        exinf;    /* extended information */
                BOOL_ID   wtsk;     /* indicates whether or not there are
                                       waiting tasks */
                INT       frbcnt;   /* free block count */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RMPF;

/* --- for time management functions ----------------------- */

    /* example for 32-bit CPUs */
        typedef struct t_systime {
                H    utime;   /* upper 16 bits */
                UW   ltime;   /* lower 32 bits */
        } SYSTIME, CYCTIME, ALMTIME;

    /* example for 16-bit CPUs */
        typedef struct t_systime {
                H    utime;   /* upper 16 bits */
                UH   mtime;   /* middle 16 bits */
                UH   ltime;   /* lower 16 bits */
        } SYSTIME, CYCTIME, ALMTIME;

          * Member configuration depends on the bit width of the processor and
            on the implementation.  A total of 48 bits is recommended.

    /* def_cyc */
        typedef struct t_dcyc {
                VP        exinf;    /* extended information */
                ATR       cycatr;   /* cyclic handler attributes */
                FP        cychdr;   /* cyclic handler address */
                UINT      cycact;   /* cyclic handler activation */
                CYCTIME   cyctim;   /* cyclic startup period */
        } T_DCYC;

    cycact:
        TCY_OFF   H'0...00   /* do not invoke cyclic handler */
        TCY_ON    H'0...01   /* invoke cyclic handler */
        TCY_INT   H'0...02   /* initialize cycle count */

    /* ref_cyc */
        typedef struct t_rcyc {
                VP        exinf;    /* extended information */
                CYCTIME   lfttim;   /* time left before next handler startup */
                UINT      cycact;   /* cyclic handler activation */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RCYC;

    /* def_alm */
        typedef struct t_dalm {
                VP        exinf;    /* extended information */
                ATR       almatr;   /* alarm handler attributes */
                FP        almhdr;   /* alarm handler address */
                UINT      tmmode;   /* start time specification mode */
                ALMTIME   almtim;   /* handler startup time */
        } T_DALM;

    tmmode:
        TTM_ABS   H'0...00   /* specified as an absolute time */
        TTM_REL   H'0...01   /* specified as a relative time */

    /* ref_alm */
        typedef struct t_ralm {
                VP        exinf;    /* extended information */
                ALMTIME   lfttim;   /* time left before next handler startup */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RALM;

/* --- for system management functions ----------------------- */

    /* get_ver */
        typedef struct t_ver {
                UH   maker;     /* vendor */
                UH   id;        /* format number */
                UH   spver;     /* specification version */
                UH   prver;     /* product version */
                UH   prno[4];   /* product control information */
                UH   cpu;       /* CPU information */
                UH   var;       /* variation descriptor */
        } T_VER;

    /* ref_sys */
        typedef struct t_rsys {
                INT   sysstat;   /* system state */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_RSYS;

    sysstat:
        TSS_TSK    0   /* normal state in which dispatching is enabled during
                          task portion execution */
        TSS_DDSP   1   /* state after dis_dsp has been executed during task
                          portion execution (dispatch disabled) */
        TSS_LOC    3   /* state after loc_cpu has been executed during task
                          portion execution (interrupt and dispatch disabled)
                          */
        TSS_INDP   4   /* state during execution of task-independent portions
                          (interrupt and timer handlers) */

    /* ref_cfg */
        typedef struct t_rcfg {
            /* details concerning members are implementation dependent */
        } T_RCFG;

    /* def_svc */
        typedef struct t_dsvc {
                ATR   svcatr;   /* extended SVC handler attributes */
                FP    svchdr;   /* extended SVC handler address */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_DSVC;

    /* def_exc */
        typedef struct t_dexc {
                ATR   excatr:   /* exception handler attributes */
                FP    exchdr;   /* exception handler address */
                        ...
            /* additional information may be included depending on the
               implementation */
                        ...
        } T_DEXC;

/* --- for network management functions ----------------------- */

    NODE srcnode, dstnode, node:
        TND_SELF   0      /* specifies the local node */
        TND_OTHR   (-1)   /* specifies default remote node */

/* ------------------------------------------------------ */


[Differences from uITRON 2.0 and ITRON2 Specifications]

The bit patterns of TA_HLNG and TA_COPn have been changed.  The bit patterns
of TTW_MPL, TA_WMUL and TA_WSGL have also been changed.

****************************************************************************
***    6.7 Error Codes                                                   ***
****************************************************************************

 -----------------------------------------------------------------------
 Mnemonic   Value    Description
 -----------------------------------------------------------------------
 E_OK       0        Normal completion
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_SYS      (-5)     System error
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_NOMEM    (-10)    Insufficient memory
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_NOSPT    (-17)    Feature not supported
 E_INOSPT   (-18)    Feature not supported by ITRON/FILE specification
 E_RSFN     (-20)    Reserved function code number
 E_RSATR    (-24)    Reserved attribute
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_PAR      (-33)    Parameter error
 E_ID       (-35)    Invalid ID number
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_NOEXS    (-52)    Object does not exist
 E_OBJ      (-63)    Invalid object state
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_MACV     (-65)    Memory access disabled or memory access violation
 E_OACV     (-66)    Object access violation
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_CTX      (-69)    Context error
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_QOVR     (-73)    Queuing or nesting overflow
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_DLT      (-81)    Object being waited for was deleted
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 E_TMOUT    (-85)    Polling failure or timeout exceeded
 E_RLWAI    (-86)    WAIT state was forcibly released
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 EN_NOND    (-113)   Target node does not exist or cannot be accessed
 EN_OBJNO   (-114)   Specifies an object number which could not be
                     accessed on the target node
 EN_PROTO   (-115)   Protocol not supported on target node
 EN_RSFN    (-116)   System call or function not supported on target node
 EN_COMM    (-117)   No response from target node
 EN_RLWAI   (-118)   Connection function response wait state was forcibly
                     released
 EN_PAR     (-119)   A value outside the range supported by the target
                     node and/or transmission packet format was specified
                     as a parameter
 EN_RPAR    (-120)   A value outside the range supported by the issuing
                     node and/or transmission packet format was returned
                     as a return parameter
 EN_CTXID   (-121)   An object on another node was specified to a system
                     call issued from a task in dispatch disabled state
                     or from a task-independent portion
 EN_EXEC    (-122)   System call could not be executed due to
                     insufficient resources on the target node
 EN_NOSPT   (-123)   Connection function not supported
 -----------------------------------------------------------------------

****************************************************************************
*****                                                                  *****
*****  Chapter 7 Appendices                                            *****
*****                                                                  *****
****************************************************************************

****************************************************************************
***    7.1 Maker Codes and CPU Codes                                     ***
****************************************************************************

This section describes the maker codes and CPU codes returned by the maker and
cpu return parameters of the get_ver system call.  These codes are assigned by
the TRON Association.

***  Maker Codes ***********************************************************

Figure 46 shows the format of maker codes.



    +---------------+---------------+---------------+---------------+
    |                             MAKER                             |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

                Figure 46 Format of maker Returned by get_ver


Specific MAKER codes established as of March, 1993 are as follows.

    MAKER:
        H'0000  No version (test systems, etc.)
        H'0001  University of Tokyo
        H'0009  FUJITSU LIMITED
        H'000a  Hitachi, Ltd.
        H'000b  Matsushita Electric Industrial Co., Ltd.
        H'000c  Mitsubishi Electric Corporation
        H'000d  NEC Corporation
        H'000e  Oki Electric Industry Co., Ltd.
        H'000f  TOSHIBA CORPORATION
          * The above have been assigned in alphabetical order.

        H'0010  ALPS ELECTRIC CO., LTD.
        H'0011  WACOM Co., Ltd.
        H'0012  Personal Media Corporation
        H'0101  OMRON CORPORATION
        H'0102  SEIKOSHA CO., LTD.
        H'0103  SYSTEM ALGO CO., LTD.
        H'0104  Tokyo Computer Service Co., Ltd.
        H'0105  YAMAHA CORPORATION
        H'0106  MORSON JAPAN
        H'0107  TOSHIBA INFORMATION SYSTEMS (JAPAN) CORP.
        H'0108  Miyazaki System Planning Office
        H'0109  Three Ace Computer Corporation

Due to restrictions on the assignment of CPU codes described below, it is
necessary to use maker codes in the range H'0000 through H'00ff for vendors
developing CPUs.


***  CPU Codes *************************************************************

Figure 47 shows the format of cpu code.  Some processors use the format
given in Figure 47(1).  The format given in Figure 47(2) is used for all
other proprietary processors.

The code assignment of the CPU1 region in the format given in Figure 47(1) is
common to ITRON and BTRON specifications.  The same number is used in the CPU
type of the standard object format of BTRON specification operating systems
implemented on a TRON-specification chip.

When using the format given in Figure 47(2) the code used for MAKER1 is
assigned by using the lower 8 bits of MAKER described in the previous
subsection.  The code assignment of CPU2 is left up to each maker.



      +---------------+---------------+---------------+---------------+
  (1) | 0   0   0   0   0   0   0   0 |              CPU1             |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      +---------------+---------------+---------------+---------------+
  (2) |             MAKER1            |              CPU2             |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

                 Figure 47 Format of cpu Returned by get_ver


Specific CPU codes established as of March, 1993 are as follows.

    CPU1:
        B'00000000  (H'00)   CPU unspecified, no CPU information given
        B'00000001  (H'01)   TRONCHIP32 shared
        B'00000010  (H'02)   reserved
        B'00000011  (H'03)   reserved
        B'00000100  (H'04)   reserved
        B'00000101  (H'05)   reserved (<<L1R>> TRON-specification chip)
        B'00000110  (H'06)   reserved (<<L1>> TRON-specification chip)
        B'00000111  (H'07)   reserved (TRON-specification chip supporting the
                             LSID function)
          * CPU vendors are unspecified for codes B'00000000 through
            B'00000111.

        B'00001000  (H'08)  reserved
        B'00001001  (H'09)  GMICRO/100
        B'00001010  (H'0a)  GMICRO/200
        B'00001011  (H'0b)  GMICRO/300
        B'00001100  (H'0c)  reserved
        B'00001101  (H'0d)  TX1
        B'00001110  (H'0e)  TX2
        B'00001111  (H'0f)  reserved

        B'00010000  (H'10)  reserved
        B'00010001  (H'11)  reserved
        B'00010010  (H'12)  reserved
        B'00010011  (H'13)  O32
        B'00010100  (H'14)  reserved
        B'00010101  (H'15)  MN10400
        B'00010110  (H'16)  reserved
        B'00010111  (H'17)  reserved

        B'00011000  (H'18)  GMICRO/400
        B'00011001  (H'19)  GMICRO/500
        B'00011010  (H'1a)  reserved
        B'00011011-B'00111111 (H'1b-H'3f)
                            reserved
          * For GMICRO extended, TX series extended, and TRONCHIP64 chips.

        B'01000000   (H'40)   Motorola 68000
        B'01000001   (H'41)   Motorola 68010
        B'01000010   (H'42)   Motorola 68020
        B'01000011   (H'43)   Motorola 68030
        B'01000100   (H'44)   Motorola 68040
        B'01000000-B'01001111 (H'40-H'4f)
                              Motorola 68000 family
        B'01010000   (H'50)   National Semiconductor NS32032
        B'01010000-B'01011111 (H'50-H'5f)
                              National Semiconductor NS32000 family
        B'01100000   (H'60)   Intel 8086, 8088
        B'01100001   (H'61)   Intel 80186
        B'01100010   (H'62)   Intel 80286
        B'01100011   (H'63)   Intel 80386
        B'01100100   (H'64)   Intel 80486
        B'01100000-B'01101111 (H'60-H'6f)
                              Intel iAPX86 family

        B'01110000-B'01111111 (H'70-H'7f)
                              NEC V Series

        B'10000000-B'11111111 (H'80-H'ff)
                              reserved

****************************************************************************
***    7.2 Specification Maintenance System                              ***
****************************************************************************

***  Assigning Version Numbers *********************************************

The version numbers of ITRON and uITRON specifications take the following
form.

        Ver X.YY.ZZ[.WW]

where "X" represents major version number of the ITRON specification to
distinguish ITRON1, ITRON2 and uITRON 3.0 specifications.  Specific
assignment is as follows.

        "X" = 1  ITRON1 specification
            = 2  ITRON2 or uITRON 2.0 specification
            = 3  uITRON 3.0 specification

"YY" is a number used to distinguish versions according to changes and
additions made to the specification.  After the specification is published,
this number is incremented in order "YY" = 00, 01, 02... according to version
upgrades.  The first digit of "YY" is 'A', 'B' or 'C' for draft standard
versions and test versions within the TRON Association before the
specification have been published.

The "X.YY" part of the specification version numbers is returned by spver
to get_ver system call.  The corresponding hexadecimal value is used when
"YY" includes 'A', 'B' or 'C'.

"ZZ" represents a number used to distinguish versions related to the written
style of a specification.  This number is incremented in order "ZZ" = 00, 01,
02... when there have been changes in specification configuration, reordering
of chapters or corrections of misprints.  When a further distinction of the
written style of specifications is desired, ".WW" may be added optionally
after "ZZ".  WW will be assumed to be zero if ".WW" is omitted.

***  Who to Contact with Questions Regarding Specifications ****************

Contact the following address or telephone number if you have any questions
regarding ITRON or uITRON specifications.

        ITRON Technical Committee
        TRON Association
        Katsuta Building 5F
        3-39 Mita 1-chome, Minato-ku, Tokyo 108
        JAPAN
        Tel. +81-3-3454-3191
        Fax. +81-3-3454-3224

The ITRON Newsletter, published periodically by the ITRON Technical Committee,
gives information regarding additions, corrections, and supplemental
information regarding the latest version of the ITRON specification.  The ITRON
Newsletter is included with organization magazines published for members of the
TRON Association and with "TRONWARE", a bimonthly technical magazine about
the TRON Project published by Personal Media Corporation
(Tel. +81-3-5702-0502).


****************************************************************************
***    7.3 Bibliography of the TRON Project and ITRON Specification      ***
****************************************************************************

The following book is published by the TRON Association and covers the entire
TRON Project including all subprojects.

    "The TRON Project 1993", TRON Association, 1993 (Both Japanese and
    English versions available)

For the latest information, see "TRONWARE", a bimonthly technical magazine
about the TRON Project published by Personal Media Corporation.  For research
results of the TRON Project, see the proceedings of the international TRON
Project Symposium held annually.  The latest available proceedings
publication is given below.  A list of TRON Project-related books is included
to supplement this proceedings publication.

    "Proceedings of the 9th TRON Project Symposium (International)",
    IEEE Computer Society Press, 1992 (ISBN 0-8186-2990-8)

The ITRON Standard Guidebook is edited and published by the ITRON Technical
Committee as a comprehensive text book of ITRON specification OS.  This book
includes a descriptive bibliography page for those who wish to learn more
about ITRON specification.

    "ITRON Standard Guidebook '92 to '93", compiled by Ken Sakamura,
    published by Personal Media Corporation, 1992 (ISBN 4-89362-197-6)

The following specification document makes public the ITRON/FILE specification
used with an ITRON specification kernel.

    "ITRON/FILE Standard Handbook", compiled by Ken Sakamura, published by
    Personal Media Corporation, 1992 (ISBN 4-89362-092-4)

The TRON Association has established a registration system for products
conforming or related to ITRON specification in order to make information
regarding the products widely available.  This system registers ITRON
specification products which have been developed for the purpose of
increasing the popularity of registered products and exchanging information
among registered developers through PR activities of the TRON Association.
Please contact the TRON Association for details concerning the registration
system of products related to ITRON specification.
