sima Command Line Tools Application Development and … · Simulated Integrated Modular vionicsA ( sima R) is an execution environment, pro- ... Section 7 provides a reference to

sima Command Line Tools

Application Development and Con�guration

Guide

GMV ima Research Group

c©2009 � 2010 by GMV, all rights reserved.

version 0.3.0.2

sima command line tools

Contents

1 Introduction 5

1.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.3 Document Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.4 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.5 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Architecture 8

2.1 Overview on arinc 653 . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.2 Mapping of arinc 653 to posix . . . . . . . . . . . . . . . . . . . . . 9

2.3 Hard Real-Time on Linux . . . . . . . . . . . . . . . . . . . . . . . . . 11

3 Installation 12

3.1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.2 Installation Process and Directory Structure . . . . . . . . . . . . . . . 12

3.3 Application of the Real-Time Preemption Patch . . . . . . . . . . . . 16

4 Basic Usage 22

4.1 The pos Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.2 Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4.3 The mos Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

4.4 Health Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

4.5 The simout Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

4.6 Logbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

4.7 Use of posix in apex Applications . . . . . . . . . . . . . . . . . . . . 46

4.8 sima speci�c Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4.9 Ada Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

5 Application Development Walkthrough 50

5.1 Use Case Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

5.2 Use Case Installation and Execution . . . . . . . . . . . . . . . . . . . 51

5.3 Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

5.4 Integration and Simulation . . . . . . . . . . . . . . . . . . . . . . . . 63

6 Internal Processes and Signals 69

7 Con�guration Reference 70

7.1 sima Con�guration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

7.2 arinc 653 Con�guration . . . . . . . . . . . . . . . . . . . . . . . . . 78

8 Service Reference 79

8.1 Service Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

8.1.1 Partition Management . . . . . . . . . . . . . . . . . . . . . . . 79

2 of 92 c©2009 � 2010 by GMV, all rights reserved.


8.1.2 Process Management . . . . . . . . . . . . . . . . . . . . . . . . 80

8.1.3 Time Management . . . . . . . . . . . . . . . . . . . . . . . . . 82

8.1.4 Partition Resources . . . . . . . . . . . . . . . . . . . . . . . . 83

8.1.5 Resources and Time outs . . . . . . . . . . . . . . . . . . . . . 83

8.1.6 Interpartition Communications . . . . . . . . . . . . . . . . . . 84

8.1.7 Health Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . 84

8.1.8 Multiple Module Schedules . . . . . . . . . . . . . . . . . . . . 84

8.1.9 Logbook System . . . . . . . . . . . . . . . . . . . . . . . . . . 84

8.1.10 File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

8.1.11 Service Access Points and Name Services . . . . . . . . . . . . 84

8.2 Service Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

8.2.1 Partition Management . . . . . . . . . . . . . . . . . . . . . . . 84

8.2.2 Process Management . . . . . . . . . . . . . . . . . . . . . . . . 85

8.2.3 Time Management . . . . . . . . . . . . . . . . . . . . . . . . . 86

8.2.4 Intrapartition Communication - Bu�er . . . . . . . . . . . . . . 87

8.2.5 Intrapartition Communication - Blackboard . . . . . . . . . . . 88

8.2.6 Intrapartition Communication - Event . . . . . . . . . . . . . . 89

8.2.7 Intrapartition Communication - Semaphore . . . . . . . . . . . 89

8.2.8 Interpartition Communication - Sampling Port . . . . . . . . . 90

8.2.9 Interpartition Communication - Queuing Port . . . . . . . . . . 91

8.2.10 Health Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

8.2.11 Multiple Module Schedules . . . . . . . . . . . . . . . . . . . . 92

8.2.12 Logbook System . . . . . . . . . . . . . . . . . . . . . . . . . . 92

8.2.13 File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

8.2.14 Sampling Port Extensions . . . . . . . . . . . . . . . . . . . . . 92

8.2.15 Service Access Points . . . . . . . . . . . . . . . . . . . . . . . 92

8.2.16 Name Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 92



List of Tables

1 apex and posix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2 preempt-rt Benchmarks . . . . . . . . . . . . . . . . . . . . . . . . . 11

3 arinc 653 Error Response Actions. . . . . . . . . . . . . . . . . . . . 36

4 arinc 653 Application Error Codes . . . . . . . . . . . . . . . . . . . 36

5 sima System States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

6 sima Error Identi�ers . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

7 Mapping of sima Errors to arinc 653 Application Error Codes . . . . 40

8 sima pos Internal Processes . . . . . . . . . . . . . . . . . . . . . . . . 69

9 sima posix Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

List of Figures

1 arinc 653 Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2 posix Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 sima Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . 13

4 xcon�g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

5 cyclictest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6 sima Tool Chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

7 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

8 Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

9 Debug Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

10 sima Port De�nition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

11 sima Ports toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

12 sima mos De�nition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

13 arinc 653 Partition Scheduling . . . . . . . . . . . . . . . . . . . . . . 33

14 sima Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

15 Error Handling Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . 37

16 System hm Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

17 Module hm Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

18 Partition hm Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

19 simout with three Partitions . . . . . . . . . . . . . . . . . . . . . . . 40

20 Output De�nition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

21 Logbook in SIMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

22 sima logbook toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

23 Control Use Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

24 Control Deployment View . . . . . . . . . . . . . . . . . . . . . . . . . 51

25 Control Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

26 CTL Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

27 sima Con�guration Overview . . . . . . . . . . . . . . . . . . . . . . . 71

28 arinc 653 Processes State Transition . . . . . . . . . . . . . . . . . . 81



1 Introduction

1.1 Purpose

Simulated Integrated Modular Avionics (simaR©) is an execution environment, pro-viding the arinc 653 Application Programming Interface (api) to operating systems(os) that do not support such services. sima is designed to run on all posix-compliantos; it is tested and optimised for the Native posix Thread Library (nptl), availableon os like gnu/Linux, kernel version 2.6 or higher, and for rtems, version 4.6 orhigher. This document focuses on the use of sima on Linux. It describes the com-mand line tools pos, mos, simout and additional development tools, all part of theimadeR© environment.

1.2 Audience

The document was written for system designers, programmers and researchers workingon ima systems and the arinc 653 standard. It is assumed that the reader hasknowledge on ima and arinc 653. Knowledge in the C language, the posix api andon development tools like make and unix shells are at least helpful for understandingthis manual. For Ada programmers, a section on the binding to this language isincluded.

1.3 Document Structure

The document is structured as follows:

• Section 1 contains the introduction you are currently reading.

• Section 2 describes the architecture of arinc 653 compliant systems in general,and its mapping to the Linux os implemented by sima.

• Section 3 discusses system requirements and the installation process.

• Section 4 explains the basic usage of the sima tools pos, mos, makeports,makebooks and simout. It also discusses the binding to the Ada programminglanguage.

• Section 5 demonstrates the main steps of the development of an arinc 653

application using the sima tools. This section discusses development, debugging,testing and simulation techniques by means of real-world examples.

• Section 6 lists internally used apex processes and posix signals and their pur-pose.

• Section 7 provides a reference to the sima speci�c con�guration and those partsof the arinc 653 standard con�guration that are used by the sima tool chain.

• Section 8 provides a reference to the arinc 653 de�ned services that are madeavailable by the sima execution environment.

• Appendix A contains the xml schema for the sima main con�guration.

• Appendix B provides an example of sima main con�guration based on the ex-ample given in arinc 653 part 1.



1.4 Conventions

Formalisms are kept to a minimum. However, the document contains many listings,re�ecting several programming languages and tools, in particular shell commands andscripts, make�les, Python, xml, pseudo code, C and Ada. Most of these listingsshow code in ascii "as is". No formalisms are adopted besides the grammar of thosesystems. Usually, listings are given in non-proportional font.

In listings, expressions enclosed in angle brackets, if not part of the de�nition of thegiven language (as in xml, for instance) are place holders, such as formal parameters,that should be replaced by actual values. The following listing shows an example:

sudo <program name> -s

sudo test -s

Pseudo code presents program logic independent from any given programming lan-guage. It does not show an implementation, but speci�es requirements for the be-haviour of a program, in particular wich output or error statement is generated for agiven input. Pseudo code follows the conventions adopted in the arinc 653 speci�ca-tion.

In the running text, we use a non-proportional font to refer to technical entities likeprograms, binaries and so on, for instance: pos. We use small capitals to representacronyms - like: pos. As you see, the di�erence can be quite subtle. In this case,the �rst expression refers to the library � pos.a � the second refers to the partitionoperating system as a concept.

Ofen uml diagrams are used to present architectures and data structures. Usually,we use class diagrams, component diagrams and deployment diagrams. Note that theuse of class diagrams does not imply an object-oriented design. Class diagrams aremainly used to show data structures (records or structs). Consequently, our classes donot have operations.

We often assume environment variable that are not explicitly introduced before used,namely $SIMA_ROOT. Those environment variables is explained in section 3.



1.5 References

[1] Airlines Electronic Engineering Committee (AEEC). Avionics Applications Soft-ware Standard Interface (ARINC Speci�cation 653 Part 1 � Required Services).ARINC Inc., 2006.

[2] Airlines Electronic Engineering Committee (AEEC). Avionics Applications Soft-ware Standard Interface (ARINC Speci�cation 653 Part 2 � Extended Services).ARINC Inc., 2008.

[3] Airlines Electronic Engineering Committee (AEEC). Avionics Applications Soft-ware Standard Interface (ARINC Speci�cation 653 Part 3 � Conformity Test).ARINC Inc., 2008.

[4] K. M. Obenland. The Use of POSIX in Realtime Systems, Asessing its E�ec-tiveness and Performance. The MITRE Corporation. September, 2000.

[5] U. Drepper, I. Mólnar. The Native POSIX Thread Library for Linux. Feburary,2006. Available at:http://people.redhat.com/drepper/nptl-design.pdf

[6] S. Rostedt. Internals of the RT Patch. In Proceedings of the 2007 Linux Sym-posion. June, 2007. Available at:http://ols.108.redhat.com/2007/Reprints

[7] E. Pascoal, J. Ru�no, T. Schoofs, and J.Windsor. AMOBA - ARINC 653 Sim-ulator for Modular Space Based Applications. DAta Systems In Aerospace.Conference, EUROSPACE, Palma de Mallorca, Spain, May, 2008.

[8] S. Santos, J. Ru�no, T. Schoofs and J. Windsor. A Portable ARINC 653 APEXInterface. In Proc. of the 27th Digital Avionics Systems Conference (DASC) ,St. Paul, MN, USA, October, 2008.

[9] T. Schoofs, S. Santos, C. Tatibana, J. Anjos. An Integrated Modular Avion-ics Development Environment. In Proc. of the 28th Digital Avionics SystemsConference (DASC) , Orlando, FL, USA, October, 2009.


http://people.redhat.com/drepper/nptl-design.pdf

http://ols.108.redhat.com/2007/Reprints


2 Architecture

2.1 Overview on arinc 653

arinc 653 is a standard de�ning an application executive (apex) and its api to be usedin partitioned environments. Partitioning means that applications are separated interms of time and space: In the time domain, this means that applications are executedone after another according to their frequency such that there is no competition forresources during run-time; each application has guaranteed access to resources fora prede�ned amount of time. In the space domain, it means that applications areseparated from each other by memory protection; no application is allowed to accessmemory outside its own address space.

The unit of partitioning is called a partition. A partition contains the executioncode and data that constitute a program. Most partitioning os, like VxWorks 653R©,PikeOSR©, LynxOS-178R© or Integrity-178R©, use a two-layer architecture, such that thepartition additionally contains an application executive, providing the api to the usercode within its partition. This os layer is usually called the Partition Operating Sys-tem (pos). The separation of applications is enforced by a lower layer os component,called Module Operating System (mos). The mos is typically a hypervisor, schedul-ing partitions as guest operating systems, using virtualisation technology. arinc 653speci�es the software interface to be used in Integrated Modular Avionics (ima), thestandard architecture in the avionics industry, based on robust partitioning. In thecontext of ima, the hardware unit on top of which the partitioning environment is ex-ecuted, is called a module. Modules are grouped together into cabinets. The following�gure illustrates the ima approach:

Figure 1: arinc 653 Partitioning

sima follows the two layered architecture of most ima os. The partition operatingsystem is provided as a library (pos.a) that is linked statically to the user applicationcode. This library contains the arinc 653 api. The sima module operating system isimplemented by a program called mos. It contains the partition scheduler, con�guredin arinc 653 compliant xml con�guration tables. The hardware units of ima are notdirectly simulated. An arinc 653 system with all its partitions, logically, presents amodule. With sima it is very well possible to simulate several ima systems on one pc.

The arinc 653 standard consists of four parts:

1. Required Services (Supplement 2)

2. Extended Services (Supplement 1)

3. Conformance Test Speci�cation



4. Minimal Services (Draft)

sima implements Part 1 (Required Services) and most of the extended services of Part2; the compliance to the standard has been proven according to Part 3 by means ofGMV's avt (arinc 653 Conformance Veri�cation Testsuite). The services de�ned byPart 1 and implemented by sima are:

• Partition Management

• Process Management

• Time Management

• Intra-Partition Communication

• Inter-Partition Communication

• Health Monitoring

The services of Part 2 implemented by sima are:

• Multiple Module Schedules

• Logbook System

• File System

• Sampling Port Extensions

• Service Access Points

• Name Services

For more details on the services, see section 8 of this document or the arinc 653 Part1, Supplement 2 and arinc 653 Part 2, Supplement 1.

2.2 Mapping of arinc 653 to posix

The arinc 653 apex de�nes two types of schedulable objects: processes and parti-tions. A partition is a unit of concurrency with its own protected address space; aprocess is a concurrency unit that executes within the address space of a partition.All processes within the same partition, thus, share the same address space.

In posix there are processes and threads. posix processes, like arinc 653 partitions,but unlike arinc 653 processes have their own protected address space; do not getconfused by the fact that the term process is used for di�erent things in arinc 653

and posix! Threads are executed within the address space of a process. All threadswithin the same process, hence, share the same address space.

Table 1 summarises this relation, using +M and -M to indicate objects with and,respectively, without memory protection:

-M +M

apex process partition

posix thread process

Table 1: apex and posix



sima exploits the analogy by mapping arinc 653 partitions to posix processes andarinc 653 processes to posix threads. Each sima application is, hence, linked toits own posix program, containing user code and data, the apex code and data and,�nally, the platform execution environment, i.e. the nptl for Linux.

In sima, partitions can be executed as single programs, scheduled by the Linux kernel,just like any other Linux process. This mode of execution is called standalone mode.In this mode, of course, there is no time partitioning and no arinc 653 health mon-itoring. Time partitioning and health monitoring are provided by the mos. The mos

is an application, i.e. a posix process, that simulates the behaviour of a real moduleoperating system. The following picture illustrates this design:

Figure 2: posix Mapping

The pos implements the apex process scheduler on top of the posix fifo scheduler(sched_fifo). posix features are encapsulated within a core layer; this way mainparts of the apex code do not rely directly on posix, but on scheduling policies im-plemented by the pos itself. The advantage of this approach is enhanced portability �there is even an implementation of the sima pos, running on bare hardware � and thefact that scheduler features that introduce subtle di�erences between di�erent posiximplementations are handled in the core layer and hidden from the apex implemen-tation.

The mos implements the apex partition scheduler. To be able to suspend and resumepartitions, commands are exchanged with the pos layer in the partitions using signalsand shared memory segments. Obviously, this approach does not answer safety andsecurity threats, caused by random errors in the partitioned code. The pos has torespond correctly to the given commands which may not be true in the case wherefaulty or malicious application code corrupted the state of the pos. In fact, the pos

was designed and developed, following safety critical software guidelines; its purposeis to support embedded applications. The mos, however, was not; the mos does onlysimulate the behaviour of an arinc 653 compliant os on top of non-safety awaresystems like standard Linux. Since it is not possible to implement a fully safety awaresystem on top of a non safety-critical os like Linux, you should not expect the simulatorto behave like a safety critical os. Note that this has impact on software failures: yourapplication may crash the simulator or even may crash the system � just like any otherLinux application too.

pos and mos are designed to support real-time applications. They use the real-timeprogramming interfaces of the posix thread library, like fifo scheduling and thread



priorities. Additionally, all memory used during execution is created during initialisa-tion and locked in ram, avoiding paging and the latency penalties caused by swappingpages in and out. However, hard real-time guarantees cannot be met without a fullypreemptive operating system kernel. Standard Linux is not yet a preemptive kernel.

If hard real-time is mandatory in your simulation scenario you may consider to usethe preempt-rt patch by Ingo Mólnar and Thomas Gleixner.

2.3 Hard Real-Time on Linux

The main problem, achieving hard real-time behaviour on Linux, is latency, de�nedas the time between the arrival of an event (like an interrupt) and the execution of itsresponse. As a general purpose os; Linux is designed to enhance the average responsetime, whereas real-time systems aim at enhancing the worst case response time as thisis the fundamental factor of impact on the system predictability.

Linux high latencies are a consequence of a non-preemptive kernel approach; the kernelcontains large protected sections, where the kernel cannot be preempted by a user task.These non-preemptible sequences cause high latencies.

To overcome this situation, Ingo Mólnar, one of the authors of the nptl, and ThomasGleixner reworked the kernel code to reduce non-preemptible sequences to a minimum.This code is available as a patch, called preempt-rt patch (see http://rt.wiki.

kernel.org).

The latency that can be expected with the preempt-rt patch depends on systemcon�guration. Main drivers for latency are hardware interrupts, causing the kernel tobecome active and and to enter the remaining non-preemptible sequences. Sources ofinterrupts are, for instance, the network interface, the graphic card, typically whenrunning an X server, and service interrupts coming from the board. This last kind ofinterrupts is worse with newer intel or amd hardware and, especially, with all kinds ofportable computers. There are scripts available to reduce interrupts on your system,but it is not recommended to apply such scripts if you are not fully aware of whatthey do in detail. Disabling service interrupts, for instance, may seriously harm yourhardware.

On systems with di�erent hardware con�gurations, the following latencies have beenmeasured, after running benchmarks for 24 � 48 hours. All values in the table arein µs; runlevel 5 means a multi-threaded environment with networking enabled andan X server running; runlevel 3 means a multi-threaded environment with networkingenabled, but without a running X server.

Best Case Average Worst Case

Desktop runlevel 5 1 7 54

Desktop runlevel 3 1 7 17

Laptop runlevel 5 1 18 62

Laptop runlevel 3 1 11 48

Table 2: preempt-rt Benchmarks

Industry experience con�rms that deadlines down to 100µs can be guaranteed even onsystems that run graphical user interfaces (gui). Without guis, even shorter deadlinesmay be possible. However, deadlines of 100µs are su�cient for typical avionics usecases and much more than can be expected from conventional simulation environments.


http://rt.wiki.kernel.org



3 Installation

3.1 System Requirements

There are no special memory, processor or disk requirements imposed on the hardware.The sima pos is designed to support embedded applications. This way, its memoryrequirements can be reduced to the minimum that is demanded by the user application.Without taking care of the memory footprint, the application is started with theamount of memory, needed to support the system limits speci�ed by the arinc 653

standard, e.g. 128 processes, 512 ports etc. This is less than a megabyte of memory;however, it should be taken into account that memory is not swapped out when anotherprogram gains access to the processor. This can cause memory overload when a systemwith many partitions is hosted on a computer with limited memory resources.

The pos is multi-core aware, but does not exploit the use of various processors orprocessor cores actively. This is inline with the arinc 653 standard. In consequence,an apex program does not have any performance advantage when executed on morethan one core. However, multi-core architecture can be very helpful for the observationof a system, when the observing tool, like simoutR©, is running on a di�erent processorcore than the ima system itself. There will certainly exist bottlenecks during memoryaccess. But the simulation and the observation tool will at least not compete forthe same processor. In general, we recommend to run always run apex programs onone processor core only. This can be achieved by means of the taskset utility; thefollowing command, for instance, will execute the program test in standalone mode onprocessor 0:

taskset 0x00000001 ./test -s

The sima tools run on 32 and 64bit hardware. Compiled libraries and binaries areavailable in the sima directories. A symbolic link points to the 32bit version by default.The user may change this default simply be redirecting the link to the 64bit version:

cd bin

# redirect the link to the 64 bit version

rm mos

ln -s mos64 mos

The sima tools rely on the nptl. The nptl is the standard thread library on Linux,version 2.6 or higher. For using sima you need as a minimum a gcc compiler withbinutils and a C-library that corresponds to you compiler. An up-to-date C++ libary(version 4.3 or higher) is advisable, but not necessary. Since the gnu C++ librarieschange much more than the C counterparts, sima is provided with statically linkedbinaries including everything related to C++. This a�ects the mos, simout and make-

tools. The pos library does not use C++, so no con�icts with your environment areexpected in this respect.

Linux distributions that have been tested with sima are Debian 4.x and 5.x, Fedora 6� 10, Suse 10 and 11, Ubuntu 8 - 10.

3.2 Installation Process and Directory Structure

The sima tools come with a gzipped tar archive calledsima-MAJOR.MINOR.PATCH.BUILD.tgz

where MAJOR, MINOR, PATCH and BUILD de�ne the version of the sima tools. It is notplanned to deliver distribution-dependent packages like rpm or deb. This may appear



a bit uncomfortable, but please note that we do not want to impose a pre-de�nedstructure for your system. There are a lot of scenarios how you may use sima, thereis no best way. However, we recommend to start with the following approach:

• Extract the tarball to /usr, /usr/local or /opt;

• Add the variable $SIMA_ROOT to your environment (e.g.: /opt/sima);

• Add the sima bin directory to your $PATH variable (e.g. PATH=$PATH:/opt/-

sima/bin);

• Create your applications in a directory outside the sima installation and point inyour make�les to the libraries and objects in the sima directory, using $SIMA_ROOT.

After extracting the archive (using sudo tar -xzf sima-MAJOR.MINOR.PATCH.tgz),the �le settings should be veri�ed and read like: drwxr-xr-x. Otherwise, you shouldapply these settings using chmod.

The resulting structure is as follows:

Figure 3: sima Directory Structure

The subdirectories contain:

• ada: Contains Ada-speci�c samples.

• bin: Contains the binaries for the sima tools, i.e.:

� mos: The Module Operating System

� simout: A visualisation tool using the curses library

� makeports: A code generator for port inter-partition communication stubs

� makebooks: A code generator for port logbook stubs

• lib: The Partition Operating System library. There are two �avours available:

� pos.a: This is the standard pos library.

� pos_log.a: This is an instrumented variant, needed for logging.



• include: The include �les:

� apex_types.h: Basic Types

� apex_time.h: Time Types and Services

� apex_process.h: Process Types and Services

� apex_partition.h: Partition Types and Services

� apex_sampling.h: Sampling Port Types and Services

� apex_queuing.h: Queuing Port Types and Services

� apex_buffer.h: Message Bu�er Types and Services

� apex_blackboard.h: Blackboard Types and Services

� apex_event.h: Event Types and Services

� apex_error.h: Error Types and Services

� a653.h: All together in one �le for convenience

� apex_debug.h: sima-speci�c debug services

� apex_system.h: sima-speci�c services

• usr: Defaults for user de�ned resources:

� main.c: Contains the C main function.

� noports.o: An object that must be linked to an applications that doesnot use ports for external communication.

� nobooks.o: An object that must be linked to an applications that doesnot use the logbook system.

• doc: Contains the user documentation, including this document.

• samples: Contains some sample programs:

� simple: A set of hello world applications to illustrate the use of basicconcepts like process, time and intra- and inter-partition communicationservices. Some of the simple samples are also used for some of the morecomplex samples, namely the a653, com and book sample.

∗ one: Illustrates the use of time services. The program writes thecurrent apex system time to standard output and delays its executionfor 100ms.

∗ base: A basic preemption example to illustrate the use of aperiodicand periodic processes. It also illustrates the use of semaphores andthe LOCK_PREEMPTION-service. The program writes the numbers from0 to 99 to standard output, interrupted by two hash signs (#).

∗ stop_base: Same as base, but stopping the periodic process thatwrites the hash signs every 10 iterations.

∗ susp_base: Same as stop_base, but using SUSPEND instead of STOP.

∗ prio: Illustrates the use of the SET_PRIORITY-service. It switches be-tween two processes by changing their priority. The processes do notdelay their execution; be aware that the program may stall your sys-tem, in particular singlecore systems!

∗ board: Illustrates the use of blackboards. A process publishes textmessages through a blackboard to other processes that print this textto standard output. The text is based on the book of Daniel, 5, 24-29(mene mene tekel).



∗ frost: Illustrates the use of message bu�ers. A set of programs sendtext messages through a message bu�er to another set of processesthat print this text to standard output. The correct execution of thisprogram should result in a poem by Robert Frost (Stopping by woodson a snowy evening).

∗ evt: Illustrates the use of events. A periodic process counts downfrom 9 to 0. On 0 an event is released with �ve processes waiting onit.

∗ philos: A simple implementation of the Dining Philosopers, illustrat-ing the use of semaphores.

∗ client: The client sends messages through a queuing port.

∗ server1: The server1 receives queuing messages and sampling mes-sages.

∗ server2: The server2 receives queuing messages and writes samplingmessages.

� a653: This is an implementation of the example ima system given in part1 of the arinc 653 standard. The directory contains:

∗ con�g: The con�guration tables.

∗ mos: Scripts to start the mos.

∗ partitions

· system: Scripts to start the the System application.

· fm: Scripts to start the Flight Management application.

· fc: Scripts to start the Flight Control application.

· io: Scripts to start the io application.

· ihvm: Scripts to start the ihvm application.

� com: This example illustrate interpartition communication in sima in anapplication using three partitions.



∗ partitions

· client: Scripts to start the client application partition.

· server1: Scripts to start the server1 application partition.

· server2: Scripts to start the server2 application partition.

� book: This example illustrate the use of logbooks in sima in an applicationusing �ve partitions.



∗ partitions

· control: Scripts to start the control application partition and sys-tem partition.

· position: Scripts to start the position application partition andsystem partition.

· writer: Scripts to start the writer application partition.

� control: This example is an extremly simple control application that isdiscussed in more detail in Section 5. The example contains �ve partitions,an external io simulator and an hmi based on Python.



∗ con�g: The con�guration �les

∗ mos: The mos startup script

∗ partitions: The startup scripts and executables for the sample parti-tions

∗ src: The sources

· ctl: The source code for the control logic

· hmi: The Python code for the human machine interface

· plant: The io simulator code

• make�le: an illustrative make�le for the samples.

3.3 Application of the Real-Time Preemption Patch

If possible, you should choose a Linux distribution that already comes with hard real-time support; Some distributors o�er packages containing a kernel with the preempt-rt patch already applied. Ask your distributor if such a distribution is already availableor will be made available soon.

If you want or have to build your own preemptible kernel, you �rst should get someinformation. There are some constraints concerning available hardware, other patches,kernel features, compilers and so on, you should check in advance. Important sourcesof information are:

• http://rt.wiki.kernel.org

This is the main entry point for everything dealing with the preempt-rt patch.You will �nd howtos, tools and links to other sources of information.

• http://www.digitalhermit.com/linux/Kernel-Build-HOWTO.html

If you have no experience with building a kernel, you should check-out this page.It explains, how the kernel is patched, con�gured, compiled and installed.

• http://www.kernel.org

This is the main entry point to everything dealing with the kernel. You �ndhowtos, tools, and links to other sources of information.

• vger.kernel.org

This is the server for the mailing list of kernel.org. Check the mailing listarchives you will �nd on www.kernel.org; inscribe to the kernel mailing list ifyou want to learn more about kernel development and the current state of thepreempt-rt patch.

The process of applying the patch consist of the following steps:

• Select a Kernel

• Get the Sources

• Patch the Kernel

• Con�gure the Kernel

• Build the Kernel

• Install the Kernel

• Post-Installation Tasks



http://www.digitalhermit.com/linux/Kernel-Build-HOWTO.html

http://www.kernel.org

vger.kernel.org

kernel.org

www.kernel.org


Select a Kernel The kernel selection may depend on a lot of factors. Importantfactors are the kernel features you need, e.g. smp or 64bit support (note that onlyIntel/amd-like hardware architectures are currently supported), the environment youmay want or have to use, mainly the compiler and linker version, the distributionyou use and, of course, the availability of patches for your kernel version. If youwant to continue with a distribution you are already using, you should select a kernelthat is close to the version of your currently used kernel. Determine your kernelversion by typing uname -r or uname -a on the command line, �nd a patch (on http:

//www.kernel.org/pub/linux/kernel/projects/rt) that is close to this version andsearch the kernel mailing list archives for bug reports and discussions on this patch.

Get the Sources The patch is available on http://www.kernel.org/pub/linux/

kernel/projects/rt. You �nd the kernel code on ftp://ftp.kernel.org/pub/linux/

kernel/v2.6. Choose patch and kernel carefully: The patch has to correspond to thekernel version!

The kernel version is de�ned by the following scheme:VERSION.PATCHLEVEL.SUBLEVEL.EXTRAVERSION, e.g.: 2.6.24.11.The �rst three numbers, VERSION, PATCHLEVEL and SUBLEVEL de�ne, what is oftencalled a vanilla kernel. A vanilla kernel is a standard baseline for development. TheEXTRAVERSION is intended for use by distribution providers who add their own patchesto the vanilla kernel. On the kernel.org you will �nd a lot of kernel versions with anEXTRAVERSION; those are developments by the Linux community, not by resellers. Ifthere is a corresponding patch, it is ok to use them.

When you look at the sources inhttp://www.kernel.org/pub/linux/kernel/projects/rt

you will see that the patches are versioned in a similar way; you will see patches ofthe form:

patch-2.6.7-rt5

patch-2.6.26.8-rt5

and so on. The �rst three numbers correspond to the kernel version; the fourth maycorrespond to the EXTRAVERSION, like in the second case, or, usually separated by adash, already to the patch version starting with rt. Everything before the dash, beit with or without EXTRAVERSION, must be equal to the version of the kernel you havechosen. The number after the dash identi�es the version of the patch within this kernelversion.

Patch the Kernel The kernel comes as tar archive, compressed by the bzip2 tool.Before you can use it, you have to untar it to a working directory, using: tar -xjf

<kernel-archive>. You should think of a useful directory structure for your kernel(s)and patch(es), like: <path>/linux/kernel/patches. Assume that we are using kernel2.6.26.8; copy the kernel archive to <path>/linux/kernel; after executing tar -xjf

linux-2.6.26.8.tar.bz2, you will see a new directory: <path>/linux/kernel/li-

nux-2.6.26.8. Copy the patch patch-2.6.26.8-rt12.bz2 into the directory <path>-

/linux/kernel/patches and step into the kernel directory (cd <path>/linux/ker-

nel/linux-2.6.26.8). Now, call the following command:

bzcat ../patches/patch-2.6.26.8-rt12.bz2 | patch -p1

This command uncompresses the patch and writes the contents (bzcat) via pipingto the command patch that applies it to the kernel sources. After the successfulapplication of the patch, we are ready to con�gure the kernel.


http://www.kernel.org/pub/linux/kernel/projects/rt




ftp://ftp.kernel.org/pub/linux/kernel/v2.6

ftp://ftp.kernel.org/pub/linux/kernel/v2.6

kernel.org



Con�gure the Kernel If you are not familiar with con�guring and compiling thekernel, please refer tohttp://www.digitalhermit.com/linux/Kernel-Build-HOWTO.html

or another kernel build howto. It is important to follow the steps of the build processcarefully; omitting a detail can cost you hours of trial and error.

If you have already built a running kernel in this directory, backup the .config �le,otherwise it will be lost. Then start one of the con�guration tools; the preferable oneis the X con�guration tool xconfig. If you have no X server, use the menuconfig tool.The tools are started by:

make xconfig

make menuconfig

The �rst command will open an X application, similar to the one that is shown in�gure 4. The menuconfig will open a simpler, curses-based interface.

Figure 4: xcon�g

In the left panel of the tool, you choose the con�guration topics. Go to Processor Typeand Features and select High Resolution Timer Support. Under the same categorysearch for Preemption mode and select Complete Preemption (Real-Time). If thisoption is not available something went wrong with the patch. This option is essentiallywhat is added by the preempt-rt patch.

Now, go to Power Management Options in the left panel. Typically you have to disableAPM and to enable ACPI. But this may change in future version of the patch.

Be aware that there may be additional options you have to enable or disable for yourspeci�c hardware. Check the howtos and mailing list archives. But really essentialfor the preempt-rt patch are the settings we discussed in this section. Try to compileyour kernel! With a bit of luck, no more changes are necessary.


http://www.digitalhermit.com/linux/Kernel-Build-HOWTO.html


Build the Kernel Compile the kernel, using the commands:

make clean

make

This will take a while, so let's have a co�ee or two...

Install the Kernel When the compilation terminated without problems, we areready to install the kernel. First step is to install the kernel modules. You need rootprivileges to do so; if you have an entry in the sudoers �le, simply use sudo, otherwiseyou need the root password and login as root. Here, we assume, you use sudo. Callthe following command:

sudo make modules_install

This command installs your modules in /lib/modules. Have a look at this directory.After installing the modules, there will be a new directory, named very similar to yourpatch version, like:

2.6.26.8-rt5

Next step is to create the boot image. The boot image contains all drivers, thekernel needs to startup and access the �lesystem. Once loaded, it can read otherdata directly from the �lesystems. The command that creates the boot image variesbetween di�erent distributions. On Redhat based systems, the command is:

mkinitrd <img> <kernel version>

sudo mkinitrd /boot/initrd-2.6.26.8-rt5.img 2.6.26.8-rt5

On Debian based systems the command is:

mkinitramfs <img> <kernel version>

sudo mkinitramfs /boot/initrd-2.6.26.8-rt5.img 2.6.26.8-rt5

The boot image is created in the /boot directory; therefore, again root privileges areneeded. The version number must correspond to your kernel version and the directoryname where the modules have been installed.

Of course, one more �le must be copied to /boot: the kernel. You will �nd the kernelin the architecture branch of your installation. For an x86 computer, do:

sudo cp arch/x86/boot/bzImage /boot/bzImage-2.6.26.8-rt5

The last installation step is editing the boot loader con�guration. Modern distributionscome with a boot loader, called grub. You will �nd a directory in /boot called grub.Open the grub con�guration �le called either menu.lst or grub.conf. Go to the endof the �le and add an entry of the form:

title My Real-Time Kernel 2.6.26.8-rt5

root (hd0,0)

kernel /bzImage-2.6.26.8-rt5

initrd /initrd-2.6.8-rt5.img

The title can be chosen randomly; the kernel and initrd attributes must correspondto the �les you installed in the boot directory. The root attribute corresponds to



the harddisk and partition your system boots from. Be aware that grub uses its ownformat to refer to disks and partitions. The partition (hd0,0) is equal to hda1. Please,refer to the grub manual for more details on the con�guration of your boot loader.You will �nd the manual at:

http://www.gnu.org/software/grub/manual/grub.html

Make sure, a timeout is de�ned at the beginning of the grub con�g �le, to force theboot process to pause and give you the opportunity to select the kernel you want toboot with (including a maintenance kernel if anything goes wrong!):

timeout=10

Now, reboot your computer.

Post-Installation Tasks If your computer does not boot, something has gonewrong. First, check that you followed the instructions in the manual and repeat thewhole procedure if necessary. If you still can't boot your machine, check the sourcesgiven above.

If you �nally are able to boot, some tasks are still necessary or, at least, recommended.On newer hardware, drivers are often proprietary; the vendor of the Linux distributionor of the hardware make such drivers available on special terms. You have to downloadthose drivers and probably you have to recompile them for the new kernel. This istypically the case for graphic card drivers. If your computer boots correctly, but can'tstart the X server, the lack of drivers is a probable cause.

When everything works correctly you should start to benchmark your machine to de-termine worst case execution times (wcet). Download the cyclictest from ThomasGleixner at:

http://www.tglx.de/projects/misc/cyclictest/

Untar and compile the cyclictest (simply using make) and call it like this:

sudo ./cyclictest -p 80 -t5 -n

The meaning of the parameters is:

• -t5: The test uses �ve posix realtime threads (note that there is no spacebetween t and 5 );

• -p 80: The threads use priorities 80, 79...76 (note that there is a space betweenp and the priority;

• -n: Thre threads use nanosleep between the calls.

The program creates an output similar to the following:

Figure 5: cyclictest



The value we are interested in, is the Max on the right. As you can see, the longestwaiting interval, between a given event and the execution of the highest priority thread,was 47µs since program start.

You should run this test for at least some hours and you should cause some ballast onyour system, using ping or cache misses or other means. See rt.wiki.kernel.org forsome suggestions.

Finally, the worst value you obtain for Max is the smallest granularity your systemsupports.


rt.wiki.kernel.org


4 Basic Usage

4.1 The pos Tool

sima can run in two di�erent modes:

• Simulation of a multi partition system on top of a module operating system;

• Executing a single partitioned application that may or may not be part of amulti partition system; this mode is called standalone mode.

The most simple way to use the pos library is to build a partition for standaloneexecution. In standalone execution, the program runs as an ordinary posix process,there is no time segregation from other apex applications. Running applications instandalone mode is a good way for verifying the program functional behaviour. It doesnot require con�guration �les and eases application debugging.

To build an apex application you need to compile your code and link it against thepos library. In this chapter, we will stick to programs written in the C language. ForAda code, see section 4.9. We assume, you use gcc as compiler.

The compilation of your code is straight forward. Just call

gcc -I$(SIMA_ROOT)include -c yourcode.c -o yourobject

In the make�le that comes with sima this is done in a generic way using macros:

CC = gcc

INC = $(SIMA_ROOT)include

.c.o: $(CC) $(INC) -c -o $@ $<

Then, you have to link the application:

$(CC) -lpthread -lrt -lm -o yourprogram yourobjectfiles \

$(SIMA_ROOT)lib/pos.a \

$(SIMA_ROOT)usr/noports.o \

$(SIMA_ROOT)usr/nobooks.o \

$(SIMA_ROOT)main.o

Again, macros are a good way to simplify the make�le:

LIB = -lpthread -lrt -lm

POS = $(SIMA_ROOT)lib/pos.a

USROBJ = \



$(SIMA_ROOT)main.o

$(CC) $(LIB) -o yourprogram yourobjectfiles \

$(POS) $(USROBJ)

The use of the pthread and rt libraries is mandatory. Whether you need the mathlibrary, depends on your code. In the listings above, dynamic linking is suggested.The libraries are loaded, when they are �rst used in the program. This may impactthe worst case execution time of some calls. For the pthread and rt library, this is notcritical as they are already used and loaded when the execution environment starts.For the math library, it may be a good idea to link it statically to your application.



The noports-object is a dummy for applications that do not use external commu-nication via ports (see section 4.2) and the nobooks-object is a similar dummy forapplications that do not use the logbook system (see section 4.6). The main-objectcontains the C-main entry point into the pos library. It is kept outside the libraryto enable the user to de�ne her own main function. For this case, you have to callthe function apx_main(int argc, char **argv) somewhere in your code as entrypoint to the pos library. The semantics of the arguments of apx_main is equal to thestandard C main function.

To make the listing above more concrete, let us assume, we are working with one ofthe sample programs coming with sima. To build the frost-program do:

# first compile

gcc -I$(SIMA_ROOT)include -c frost.c -o frost.o

# now link

$(CC) -lpthread -lrt -o frost frost.o \

$(SIMA_ROOT)lib/pos.a \



$(SIMA_ROOT)main.o

Figure 6 illustrates sima basic tool chain. Steps one and two provide the applicationexecutable.

Figure 6: sima Tool Chain

After linking the application, you are able to execute it. Since pos uses the posixreal-time interface, you have to call the program as root. The recommended way todo so, is to add an entry for the sima users in the sudoers �le. This enables you tocall the binary as root, just typing your own unix password.

Now, let us execute the application; we will start using the -h option:

sudo ./frost -h

This command will list all command line parameters:



Figure 7: Usage

For each parameter two forms are possible:

1. short form: -h

2. long form: --help

The short form consists of one hyphen and one character; the long form consists of twohyphens and a word. The character of the short form is equal to the �rst character ofthe long form corresponding to the same parameter.

Some parameters take an argument value that is given as =Value. Some more expla-nations follow below:

• connect: In standalone mode, the program does not connect ports to a channel.If communication with the outside world is required in standalone mode theprogram must be invoqued with the connect option:

sudo frost --standalone --connect

sudo frost -s -c

• help: Writes the usage to standard output.

• Version: Writes version information to standard output. The version informa-tion looks like this:

This is SIMA Partition Operating System (POS) -

version 0.1.2.16

(C) GMV, 2008-2010



• grain: This option de�nes the granularity; the granularity is the smallest valueany time expression within an apex program can use. The granularity is givenin nanoseconds, like:

sudo frost --standalone --grain=100000

sudo frost -s -g=100000

These calls de�ne a granularity of 100µs. The smallest possible deadline, time-out or wait interval is de�ned with this option as 100µs. Time steps betweentwo grains, 150µs, for instance, are cut down to the next lower granularity step,thus 100µs for the example. The granularity depends on the system. It does noharm to use a lower granularity than your system can support. The bigger thedi�erence between the granularity, your system supports, and the granularity,you set to your application, the higher is the risk to miss a deadline. If you ac-tually use deadlines that are lower than the granularity, your system supports,you will, certainly, miss these deadlines. A standard Linux kernel has a granu-larity between 1 and 10ms. A kernel with the preempt-rt patch can supportmuch lower granularity. The actual value depends on the result of your latencybenchmarks. 100µs is a fairly good guess for patched kernels.The default value for this parameter is 100µs. We recommended to start withthis value on patched and non-patched kernels and to �netune the parameteronly when you run into trouble with deadlines.A word of caution: When your application uses very short preemption timesthat are close to your granularity (like, e.g. 100µs), it may block or, on sin-glecore machines, even stall the system � even with a preemptible kernel. Thereason is that one or two granularity steps may be too short for your machineto execute a conext switch within the the apex, such that the system immedi-ately starts to reschedule and, e�ectively, is never preempted. If you need towork with extremely short preemption times you should benchmark the apexon your system, using, for instance, two processes with di�erent priorities andthe timed_wait service.

• log: De�nes the log level for the instrumented variant of the library. Five loglevels are de�ned:

� 0: Nothing is logged

� 1: Warnings are logged

� 2: All entries to and exits from apex-calls are logged

� 3: Additionally to log level 2, parameters are logged

� 4: Additionally to log level 3, objects like messages and blackboards arelogged

The logging output is written to a �le, using a log server that may be hostedon the same or a remote computer. The log �le is human readable, but mainlyintended to be used by the analyser applications, part of the imadeR©. See theimade manual for more details on logging.

• mos: De�nes the shared memory key to be used to connect to the mos. Theparameter is not used directly by the user (see sections 4.3 and 7.1).

• period: De�nes the partition period in standalone mode. The partition periodis used by the period_wait service to synchronise the process period and thepartition period, and by the start service to start periodic processes in NORMAL

mode (see section 8 for details). The parameter is given in nanoseconds. Thedefault value is 500ms (500000000ns).



• standalone: With this option given, the application will not try to connect tothe mos, but run as an ordinary posix application. As discussed earlier thisoption is intended for quick debugging, since there is no con�guration involved.

The obvious drawback is that there is no time partitioning and no health mon-itoring. When you run more than one apex application in standalone modeat the same time these applications will interfere with each other. If an erroroccurs, the application will terminate, indicating the hm event that caused theinterruption.

If your application uses aperiodic processes, your program will appear to runfaster than connected to the mos: It has 100% of available CPU resources foritself.

• time: De�nes the starting point of the system. The parameter is not useddirectly by the user; its purpose is to synchronise all partitions connected to themos to the same system time, measured in nanoseconds since system start (seesections 4.3 and 7.1).

• verbose: Without this parameter, the library is quite. Only errors are written tostandard output. In normal execution, you will not see any output, besides yourown printf or fprintf. With verbose given, internal activities are announcedon standard output.

Having discussed all this, we are prepared to execute one of the sample programs.(Don't forget to use the --standalone or -s option!)

When an application starts, the apex executes the partition entry point, de�ned inthe user code. The partition entry point is provided as a memory address or symbolicname in the con�guration (see below, section 7.2). However, the sima pos does notuse this con�guration data. There is a simple reason for this: The con�guration �le isintended for use with a real arinc 653 OS; the user should not be forced to changeher con�guration for testing with the sima tool chain. Therefore, the pos library callsa pre-de�ned function in the user code. This function is declared as follows:

int entry_point()

On success the entry_point should return the arinc 653 de�ned return value NO_ERROR.On error, some value not equal to NO_ERROR should be returned; the pos will ter-minate execution writing an error message to standard output that includes your errorcode.

It is a good idea to separate the entry_point from the application code in a singleC-�le. The entry_point should simply call your partition intialisation routine. Thisway, no traces of the use of sima are left in your application.

Have a look at the entry_point in the frost-example. You will see a lot of apex stu�like creating and starting processes, creating semaphores and message bu�ers. Seesection 8 for more details on this. For the moment, look at the printf you will �ndin the code. Some timing information is written to the standard output. When theprogram starts, and you see somthing like:

Shared Memory Key should be > 1000: 0

Terminating

you forgot the -s option :-) Otherwise, you will see something similar to the following:



Figure 8: Entry Point

The �rst line tells you that the entry_point was started 1.2ms after system start.The next line, starting with Procs, is issued after process creation. Eight processeshave been created in 100µs. The next line, beginning with First, gives the timeafter starting the �rst process. It took again 100µs. The amount of time for processinitialisation depends on your system and the size of the stack. In the frost programthe stack is 10KB; look for the line stating

atts.STACK_SIZE = 10240;

The default value, selected when the stack size is set to 0, is 100KB. The stack sizethat is appropriate for your processes, depends on the code. The stack size depends onthe amount of memory used for function parameters, function scope variables and theheight of the call tree. For simple debugging of your code, guessing a value somewherebetween e.g. 10 � 100KB, is ok. Later, during hardware integration or preparingcerti�cation evidence, stack sizing is an important task.

The next line in the output, beginning with Started, is written when all processeshave been started. Because there remain seven processes to be started after issueingthe First line, this takes 700µs. Afterwards, a semaphore and a message bu�er arecreated. This takes less than 100µs. Since the default granularity of 100µs is usedthe next line still gives the system time as 2.1ms after system start. The call ofSET_PARTITION_MODE which signals the end of the initialisation phase (see section 8for details) is still within the 100µs limit, so the entry_point terminates 2.1ms aftersystem start and took 900µs.

After the initialisation, the program will write some line breaks to standard output.Then it starts to write a famous poem by Robert Frost (1874 � 1963). If everythinggoes right, the following poem should be written repeatedly to your terminal:

Whose woods these are I think I knowHis house is in the village, though;

He will not see me stopping hereTo watch his woods �ll up with snow.

My little horse must think it queerTo stop without a farmhouse near

Between the woods and frozen lakeThe darkest evening of the year.

He gives his harness bells a shakeTo ask if there is some mistake

The only other sound's the sweepOf easy wind and downy �ake.

The woods are lovely, dark and deepBut I have promises to keep

And miles to go before I sleep,And miles to go before I sleep.



As you will notice, the entry_point is the longest part of the program, it is about halfof the lines of code. With some knowledge of the C language and the apex servicesyou will be able to understand what the program is doing in detail. Have a look atthe code and try to �gure out what it is doing!

To end the program send it the INT signal, either by typing <ctrl>-c, if you run it inthe foreground of your terminal, or by kill -INT <pid>.

If you want to know the internal state of the runtime during execution you may sendthe TRAP signal to the process. This will cause the program to write some debuginformation to standard output:

kill -TRAP <pid>

Figure 9: Debug Information

Two kind of information is given here: The state of the apex process scheduler andthe state of the apex time manager. The process scheduler has currently

• DORMANT: No process is in DORMANT state. All processes have been started.

• WAITING: All user processes, ONE through EIGHT, are waiting. Most of theseprocesses are waiting for a semaphore or the message bu�er. Only EIGHT, as wewill see later, is waiting for a time event. There is one internal process waiting,_apx_upd_period. This process is responsible for updating the partition periodin standalone mode and is most of the time waiting. Please note that namesof internal processes always start with _apx_. If you have processes named likethis, please refer to the list of internal processes (section 6), to avoid a symbolclash.

• READY: Currently, no process is READY.

• RUNNING: Currently, no user process, but an internal process, _apx_idle, isrunning. This process is executed whenever there is no user process in READY

state.



The lines between === Start === and === End === contain information on the state ofthe time manager. The state is de�ned by a list of events. The �rst �eld (0x80657b8) isa pointer to an event that was created during initialisation of the runtime environment.(Note that memory is never allocated during run-time.) The second �eld de�nes thepoint in time of this time event, given in nanoseconds since system start. Within thecurly braces, a list of processes is shown that are waiting for this event or have adeadline registered at this point in time. The user process EIGHT is waiting � indicatedby (W) � for a timeout or a wait interval (TIMED_WAIT, as we know from the code). Ifa process had a deadline registered at this point in time, (D) would be shown.

This debug information can also be explicitly queried by calling apx_sched_show andapx_show_time_line de�ned in the apex_debug header �le. The primitives are calledlike this:

apx_sched_show(DORMANT); // Shows processes in DORMANT state

apx_sched_show(WAITING); // Shows processes in WAITING state

apx_sched_show(READY); // Shows processes in READY state

apx_sched_show(RUNNING); // Shows the process in RUNNING state

apx_show_time_line(); // Shows the time manager state

4.2 Ports

arinc 653 applications use ports to communicate with the outside world. Ports arememory areas within the partition address space where messages are written to orread from by application code. If ports are connected to a channel, the messages ina source port are copied to the memory area of the destination port. This transportmechanism is invisible to the application. It is also transparent to the applicationwhere the other port is located: In a partition on the same module or on anothercomputer.

Channels are de�ned in the arinc 653 con�guration as a relation between a source portto one or more destination ports (see section 7.2 for details). The arinc 653 standardleaves it open whether messages are sent to one destination or all destinations. simasends a message to all destination ports that are con�gured. This way, it is possible toemulate a simple unicast environment with 1:1 relation between ports and a multicastenvironment with 1:n relation.

The arinc 653 con�guration de�nes the logical relation between ports. The mappingto lower level entities implementing ports is out of the scope of the standard. simamaps arinc 653 ports to UDP ports on Linux. The additional information needed bythis mapping is given in the sima main con�guration �le (see section 7.1). A portthat is de�ned in the arinc 653 con�guration has an equivalent in the sima maincon�guration. The general format of a port de�nition in the sima main con�guration,given in uml notation, is as follows:

Figure 10: sima Port De�nition

The Name must correspond to a port name in the arinc 653 con�guration �le. Cur-rently, only one Type is de�ned: UDP. The IP address is given in the dotted decimal



notation, for instance: 127.0.0.1. The Port is the UDP port number you want to usefor this arinc 653 port.

The port, as it is shown above, is, actually, an abstract class with two subclasses:

• Sampling_Port: Corresponds to arinc 653 Sampling_Ports.

• Queuing_Port: Corresponds to arinc 653 Queuing_Ports.

The following listing shows a con�guration fragment presenting examples for bothkinds of ports:

<Sampling_PortName="SAMP_ONE"Type="UDP"IP=" 12 7 . 0 . 0 . 1 "Port="12353"/>

<Queuing_PortName="QUEUE_ONE"Type="UDP"IP=" 12 7 . 0 . 0 . 1 "Port="12351"/>

In the sima con�guration, ports are speci�ed in terms of ip address and port numberwhich is used to connect partitions via udp sockets. The channel between partitions indi�erent modules is, according to arinc 653, speci�ed through pseudo partitions. Thelisting below illustrates the connection between partitions located in di�erent modules.

<Pa r t i t i on P a r t i t i o n I d e n t i f i e r="1"PartitionName="Cont r o l l e r ">

<Queuing_PortName="ACTUATOR_Q"Type="UDP"IP=" 12 7 . 0 . 0 . 1 "Port="0000"/>

</ Par t i t i on><Pseudo_Partit ion Name="ACTUATOR">

<Queuing_PortName="ACTUATOR"Type="UDP"IP=" 12 7 . 0 . 0 . 1 "Port="12383"/>

</Pseudo_Partit ion>

The listing shows the port mapping de�nition in the sima con�guration �le. It de�nes aqueuing port ACTUATOR_Q in a standard partition called Controller and a queuingport ACTUATOR in a pseudo partition called ACTUATOR. It is not visible in thesima con�guration �le whether ACTUATOR_Q is a source or a destination port.This is de�ned in the arinc 653 con�guration. However, it makes sense to assume thatthe ACTUATOR_Q is a source port that sends to an external resource representedby the pseudo partition. Note that the port in ACTUATOR_Q is not valid (it is 0); infact, in the sima simulator, outgoing ports do not represent a resource actually usedon your system. Internally, sima uses the ip and port de�ntion of the destination,the pseudo port in this example, to create a socket and send messages through it.Consequently, destination port con�guration is essential: it de�nes the listening toa socket.



The general rule for port mapping is, hence, that a port mapping is needed

• For all ports, de�ned as destination in the arinc 653 con�guration;

• For external resources (ports in pseudo partitions) that represent a destinationport.

For the sake of clarity, we recommend that you introduce a port mapping node inthe sima con�guration for all ports used in the arinc 653 con�guration. For moredetails on port con�guration, please refer to the con�guration of the com and control

example as well as to section 7.2 in this document and, of course, to the arinc 653

standard documents.

The con�guration is not read directly by the pos. Instead, a C-stub must be generatedfrom the con�guration using the makeports tool. The makeports tool is called asfollows:

makeports <sima_config> <partition> > <c-file>

makeports config/sima.xml System > systemports.c

In a make�le, a dependency from an application, using ports, to the con�guration, theports are described in, should be de�ned. Note that the dependency holds for bothcon�guration �les, the sima main con�guration and the arinc 653 con�guration:

systemports.c: config/sima.xml config/a653.xml

makeports config/sima.xml > systemports.c

systemports.o: systemports.c

...

system: ... systemports.o ...

...

Figure 11 shows the build chain for port con�gurations schematically:

Figure 11: sima Ports toolchain

The channel between ports is implemented by an internal process, called _apx_udp_listen.The process is automatically started when the application is connected to the mos orwith the --connect option given in standalone mode.

In standalone mode, this process runs with a priority lower than user process prior-ities. This implies that messages are only sent and received when no user processis ready. It implies also that the transportation mechanism interferes with the userprocess activity. These restrictions are acceptable for debugging, but certainly notfor the simulation of an ima system. Therefore, more options are available when theapplication is connected to the mos. For more details, see section 4.3.



4.3 The mos Tool

The purpose of the mos program is to schedule and to health monitor partitionedapplications. The mos works in three phases:

1. The con�guration �les are read and the corresponding entities, like partitionsand health monitoring tables are created in memory.

2. The mos goes into real-time mode and starts the partitioned applications.

3. The mos enters the scheduling phase. From now on, the mos will suspend andresume partitions, according to the module schedule, and wait for health moni-toring events.

The con�guration �le to be read is given as parameter. The most common way to callthe mos is:

sudo mos <sima-config>

sudo mos sima.xml

There are some more options available, following the same schema as the pos library:

• help: Prints the usage message and exits.

• Version: Prints version information and exits:

sudo mos --Version

sudo mos -V

This is SIMA Module Operating System -

version 0.1.1.8

(c) GMV, 2008-2010

• verbose: Usually the mos runs almost quiet; it only indicates when a healthmonitoring event occurs. With verbose given, it will write every executionwindow switch to standard output.

• check: checks the given con�guration and exits.

Unlike the pos tool, information controlling the behaviour of the program is not givenas command line parameter, but rather by con�guration. The entry point for the mosinto the sima main con�guration is the root node mos:

Figure 12: sima mos De�nition



system de�nes the name of the ima module. arinc653_config is the path to thearinc 653 xml con�guration �le. Startup is the path to an executable �le, a binaryor a script, that starts the mos itself. This information is used by the simout tool.partitions gives the number of partitions in the module. This parameter is used tocheck the con�guration. If this number and the actual number of partitions in thecon�guration do not match, a warning is written to standard output. granularity

de�nes the granulariy of the system. All partitions will be started with this value.

The mos node contains a set of partition nodes representing the partitions, themos will schedule. A partition is identi�ed by the PartitionIdentifier and thePartitionName. The values must be identical to the corresponding partition in thearinc 653 con�guration �le. SharedMemory de�nes the shared memory key that isused to communicate with the given partition. Startup is a path to an executable, theuser application binary or a user de�ned script that will start the partition application.The last attribute, visible is used by the simout tool only (see section 4.5).

The partition scheduling is de�ned in the arinc 653 con�guration �le in three hier-archy levels: the Module_Schedule contains one Partition_Schedule per partition;each Partition_Schedule contains a set of Window_Schedules. A Window_Schedule

de�nes the starting point and the duration of one execution window. This way onepartition may have n execution windows assigned to it.

All Window_Schedules together de�ne the Module_Schedule or major execution framethat is repeated during module run-time. If there is a gap between the end of oneexecution window and the beginning of the next, the mos automatically �lls it up withan execution window without a partition assgned to it.

Partitions gain access to the processor, when the time, de�ned relatively to the be-ginning of the major time frame in WindowStartSeconds, arrives. When the timede�ned in WindowDurationSeconds expires the partition is suspended. If an �rst exe-cution window of a partition becomes active for the �rst time after a cold_start orwarm_start, the entry_point of the corresponding partition is executed. Otherwisethe execution is continued where it has been suspended before. Figure 13 illustratesthe main concepts of time partitioning in arinc 653.

Figure 13: arinc 653 Partition Scheduling

For the arinc 653 approach, it is important to understand, how partition and processscheduling work together. The schedules are de�ned by two di�erent roles in the imaprocess. The partition scheduling is de�ned by the system integrator who is responsiblefor the integration of the module and the whole avionic system; the process schedulingis de�ned by the function supplier who is responsible for the development and integra-tion of the software application. The function supplier receives two requirements that



de�ne the partition scheduling from the system integrator: the application frequencyand the time resources available for the application. The application frequency de�nesthe frequency of periodic processes: The period of all periodic processes in the appli-cation must be integer multiples of the partition period. For example, if the frequencyof the application is 5Hz, the partition period is 200ms. Possible process periods are,for instance: 200ms, 400ms, 600ms and so on. Note that if a process does not obeythis requirement, its processing time will sooner or later fall into a time period wherethe partition is not active. It will, hence, miss its deadline.

The worst case execution time of all real-time processes that are executed together inone period should �t into the time resource available for the application within thisperiod. Let us assume, our application with 200ms frequency has 100ms guaranteedper period. Let us further assume there are four processes, two, p1 and p2, executingwith 400ms, two, p3 and p4 with 600ms frequency. Since the p1 and p2 period is twotimes the partition period, the time guaranteed for both process together is 200ms. Theworst case execution time for each shall be ≤ 100ms or more precisely ≤ 100ms− osoverhead for partition context switching. Processes p3 and p4 have a much longerperiod than p1 and p2 ; it covers three partition periods. They, hence, together shallhave a worst case execution time of less than 300ms or ≤ 150ms each. Note that withthis de�nition there will be partition periods where all four processes will be executed.This means that the worst case execution time shall be much lower than the valueswe de�ned for the processes under the assumption that only two are executed at thesame time. This is not trivial and e�ort must be spent to carefully design the timingbehaviour of a real-time application. But basically, this is well-known rate-monotonicscheduling. The function supplier does not see the partitioning of the system but onlythe system that is de�ned by the time partition available for his application. He evendoes not know in how many Window_Schedules his partition is divided; in the exampleabove it may be one Window_Schedule with 100ms duration per major time frame orseveral Window_Schedules with shorter durations. Note that in the latter case, moreoverhead for partition schedule has to be taken into account. But this is part of thesystem integrator's task.

In the sima con�guration, Window_Schedules are split into smaller units, called slices.Each execution window may have up to three slices: the start slice, the main slice andthe end slice. The main slice is always present; it represents the time guaranteed forexecution of the application code itself. The start slice and the end slice are reservedfor message transportation. Only one process is allowed to execute during start andend slices: _apx_udp_listen. When an execution window has a start slice de�ned,the mos will explicitly set this process from the WAITING to the RUNNING state. Whenthe duration of the start slice expires, apx_udp_listen is set back to WAITING and theapplication is resumed. When the duration of the main slice expires, the application issuspended, and if the execution window has an end slice de�ned, the _apx_udp_listenprocess will be set to RUNNING. When no slices are de�ned for a window, the durationof the main slice is equal to the duration of the Window_Schedule.

The slices of Window_Schedules are con�gured by means of the Transport node, partof Partition in sima main con�guration:



Figure 14: sima Transport

In the Transport node Start and End de�ne the start and end slices. The Transport-Slice datatype is de�ned as {period|selected|all}. If Start or End are set to period,a start slice or an end slice respectively, will be present in all Window_Schedules ofthis partition de�ned with PartitionPeriodStart set to true. If selected is de�nedonly those execution windows that are given explicitly as Window_Schedule within theTransport node will have a start or end slice by default. If all is de�ned all executionwindows of this partition will have a start or end slice. The duration of start and endslices are de�ned in StartDurationSeconds and EndDurationSeconds respectively.

The Window_Schedule nodes control the application of slices to execution windowsfor settings of all and selected in the Start and End attributes of Transport. TheWindowIdentifier must correspond to a Window_Schedule of the given partition inthe arinc 653 con�guration. If selected was de�ned in Transport only the presentWindow_Schedules will have slices. The Start and End attributes in the Window-

_Schedule de�ne whether this execution window will have a start or an end slice orboth. If all was de�ned in Transport all execution windows of the current parti-tion will have the de�ned slices per default; Window_Schedule is used in this case tooverwrite the default, de�ned by Transport for single execution windows.

In the case of all the values of StartDurationSeconds and EndDurationSeconds

applied to an execution window will come from Transport per default. If a Window-

_Schedule overwrites this default, the values from Window_Schedule will be applied.This means, a Window_Schedule must de�ne these values, even if they are equal to thedefault. In the case of select, the values will always come from the Window_Schedule.The values in Transport are ignored. For the period setting, Window_Schedules arecompletely ignored.

As an alternative to start and end slices, continuous may be selected. This settingcauses _apx_udp_listen to be executed together with the application code in the mainslice. This setting may be useful when there are execution windows, known to havelow user activity. But it is not recommended as a general setting for all executionwindows. The listen process contains protected sequences that cannot be preemptedby other processes. The continuous setting introduces the risk of missing deadlinesof user processes.

For the continuous setting, the period value is forbidden. continuous can only be de-�ned as selected or all execution windows of the given partition. With continuous,the current priority of the _apx_udp_listen process will be set to Priority. ThePriority value is not limited to arinc 653 priorities, but has a range of [0,∞[. Thisway, it is possible to run the listener process only when no user process is ready(Priority = 0) or, in the contrary, to execute user processes only, when the listeneris not ready (Priority > 63).



4.4 Health Monitoring

The other responsibility of the mos program, besides partition scheduling, is healthmonitoring (hm). Errors ocurring in partitioned applications are reported to the mos.The mos looks-up the error in the con�guration and applies the corresponding action.The action may be handled on one of three levels: process, partition or module.The actions on partition and module level are directly speci�ed in the con�guration.The following table shows which actions are possible on these levels:

Action Level Comment

ignore module and partition No error handling

shutdown module The module is shut down

reset module The module is restarted

idle partition The partition is shut down

warm_start partition The partition is restarted

cold_start partition The partition is restarted

Table 3: arinc 653 Error Response Actions.

Errors on process level are delegated to the user de�ned error handler process (eh).When the mos invokes the eh, the latter is started and the control returned to thepos of the a�ected partition. Since the eh runs as the highest priority process withinthe partition, it will preempt any other process and run immediately. Now, the errorhandling is in the responsibility of the user code. To enable the eh to identify theerror that has occurred, the arinc 653 speci�cation de�nes a set of standard errorcodes. Table 4 lists the error identi�ers de�ned on process level:

Symbolic Name Error Code

deadline_missed 0

application_error 1

numeric_error 2

illegal_request 3

stack_overflow 4

memory_violation 5

hardware_fault 6

power_fail 7

Table 4: arinc 653 Application Error Codes

There are four sources of errors:

• Internal errors of the pos

• Deadline misses detected by the pos

• Signals from the Linux kernel

• raise_application_error issued by application code

The last error source is an exception to the common error handling. All errors, de-tected by the pos are passed to the mos and handled there, according to the con-�guration. raise_application_error, however, allows the application to invokethe eh directly, without passing the error code through the mos. According to arinc653, there is only one error that can be raised by raise_application_error: theapplication_error.

The general error handling scenario is illustrated by �gure 15:



Figure 15: Error Handling Scenario

Most errors cannot be detected by the pos itself; running on a Linux platform, theLinux kernel is responsible for detecting segmentation faults, numeric errors or stackover�ows. The kernel sends a signal, like sigsegv, sigfpe or sigstkflt, to the faultyprocess. The pos catches this signal and reports the incident to the mos.

The arinc 653 con�guration de�nes error response actions in terms of system statesand error identi�ers. An error occurring in one system state may be treated in adi�erent way than occurring in another � it may even be handled on another level.Figure 16 shows the structure of the arinc 653 system hm table; this table de�nesthe level, an error is handled on, where ErrorLevel is either process, partition ormodule:

Figure 16: System hm Table

On module and partition level, the actions taken when an error occurs, is de�ned bythe con�guration. There must be one Module_HM_Table in the system:



Figure 17: Module hm Table

Module and partition hm tables contain a Callback attribute. This callback refers touser de�ned code that is executed, before the con�guration de�ned action is taken.Note that there is currently no mechanism to de�ne such a callback for the sima tools.Individual solutions may be found in cooperation with GMV.

Finally, the actions taken on partition level are de�ned in the Partition_HM_Table.There must be one such table per partition:

Figure 18: Partition hm Table

These tables are usually de�ned in the arinc 653 con�guration. However, the hminformation depends on the os and won't be the same for the sima execution envi-ronment and the real target os. Therefore, it is possible to place any of these tablesin the sima main con�guration instead of the arinc 653 con�guration �le. This way,the original arinc 653 �le is not a�ected by sima-speci�c con�guration data.

System states and error identi�ers are not de�ned by the arinc 653 standard. Eachimplementation must de�ne its own system states and error identi�ers. System levelsin sima are:



System State Description

1 mos is starting

2 mos is executing

3 Reserved

4 pos system code is executing

5 Application code is executing

6 raise_applicaton_error in eh

7 Reserved

8 Reserved

9 mos hm is executing

Table 5: sima System States

Table 6 presents the error codes known to the sima tools:

Error Description Raised by Means pos code

1 Reserved N/A N/A N/A

2 Module Con�g N/A N/A N/A

3 Partition Con�g N/A N/A N/A

4 Module Init N/A N/A N/A

5 Segmentation Fault os kernel sigsegv 1022

6 Timing Error pos N/A 1023

7 Illegal Instruction os kernel sigill 1026

8 Numeric Error os kernel sigfpe 1024

9 Stack Over�ow os kernel sigstkflt 1027

raise

10 Application Error eh application 1028error

11 Bad Opcode os kernel sigsys 1021

12 Power Failure os kernel sigpwr 1029

Table 6: sima Error Identi�ers

The pos error codes are only visible to the user in standalone mode. Since in standalonemode, the pos has nothing to raise the error to, the application is stopped and an errormessage is written to standard output which contains the pos error code, e.g.:

Raise Partition Error 1022

=> Partition in standalone mode can't raise partition error handler.

Note that con�guration and initialisation errors (errors 2-3 in Table 6) are not handledby the hm. The mos will terminate during initialisation and write an error messageto standard output. Remember that the mos does not constitute a safety criticalsystem. It is an ordinay Linux application that simulates the behaviour of a realmodule operating system.

Error 1 is reserved for internal use and should not be used in the con�guration.

Errors that are handled on process level, are passed to the eh according to themapping shown in table 7:



Symbolic Name Error Code Error Description

deadline_missed 0 6 Timing Error

application_error 1 10 Appliclation Error

numeric_error 2 8 Numeric Error

illegal_request 3 11 Bad Opcodeillegal_request 3 7 Illegal Instruction

stack_overflow 4 9 Stack Over�ow

memory_violation 5 5 Segmentation Fault

hardware_fault 6 N/A Not available

power_fail 7 12 Power Failure

Table 7: Mapping of sima Errors to arinc 653 Application Error Codes

4.5 The simout Tool

The simout program shows the output of the mos and up to six partitions in a graphicalenvironment based on the curses library. simout invokes the mos automatically, usingthe value in the Startup attribute of the mos node as path to the mos startup script.Like mos, simout is called with the sima main con�guration as parameter:

sudo simout <sima-config>

sudo simout sima.xml

When the mos and the partitions have been started, an output as the following, showingsimout with three partitions, is presented:

Figure 19: simout with three Partitions

There are two more options available, following the same schema as the pos and mos

programs:

• help: Prints the usage messages and exits.

• Version: Prints version information and exits:

sudo simout --Version

sudo simout -V



This is SIMA simout - version 0.1.2.3

(c) GMV, 2008-2010

The program is terminated by typing q. Do not use <ctrl>-c to terminate simout.This may leave the system in an unknown state; it may be necessary to do somecleanup manually.

By typing the value of the PartitionIdentifier (like: 2), displayed at the top ofthe partition window, the corresponding output is frozen. Typing the number again,continues the output.

The simout tool uses named pipes (fifos) to read the output of the other programs.To enable the simout tool to receive this data, the standard output and standard erroroutput of these programs must be redirected to the named pipes, simout will read.The easiest way, to do so, is to de�ne scripts to wrap the call to the mos and thepartitioned applications:

# ===========================

# This is mos.sh

# The starter script for mos

# ===========================

mos sima.xml > fifo_mos 2>&1 &

# ===========================

# This is system.sh

# The starter script

# For the System application

# ===========================

system $1 $2 $3 > fifo_system 2>&1 &

The parameters passed to a partition, the system application in the example above,are generated by the mos. These parameters are:

• $1: The granularity

• $2: The shared memory key for this partition

• $3: The system start time

You should not pass values to these parameters but just pass on parameters 1 � 3 ofthe script.

Note that mos and applications must be started in the background, using & (like in thescripts) or nohup. This way, the shell scripts calling the applications are immediatelyterminated.

The named pipes, fifo_mos and fifo_system, must be created before executing thescripts, using mkfifo.

Scripts can also be used to execute applications in di�erent environments. On multi-core systems, a processor a�nity for an application may be de�ned, using taskset; adebugging tool, like valgrind, may be used for some sessions; or the output may bepreprocessed before it is sent to the �fo:



# ===========================

# This is system.sh


# For the System application

# We use valgrind to find

# A segmentation fault

# ===========================

valgrind system $1 $2 $3 > fifo_system 2>&1 &

# ==================================

# This is fc.sh


# For the Flight Control Application

# We will run it on a dedicated set

# Of cores to avoid interference

# With Linux background daemons

# ==================================

taskset 0x00000003 fc $1 $2 $3 > fifo_fc 2>&1 &

# ======================================

# This is fm.sh


# For the Flight Management Application

# We use the verbose parameter and

# A filter to find out where

# The scheduling goes wrong

# ======================================

fm $1 $2 $3 --verbose | filter.sh > fifo_fm 2>&1 &

The path to the scripts must be assigned to the attributes Startup in the mos andpartition nodes of the sima main con�guration:

<mos system="Example"a653_config=" . / c on f i g /a653 . xml"Startup="/bin / sh . / samples /mos/mos . sh"p a r t i t i o n s="3"g r anu l a r i t y="100000">. . .

<Pa r t i t i on P a r t i t i o n I d e n t i f i e r="1"PartitionName="System"SharedMemory="50010"Startup="/bin / sh . / samples / p a r t i t i o n s /base / system . sh"v i s i b l e=" true ">. . .

Finally, simout has to be informed where to read the output of the mos and thepartitions from. For this purpose, an element , called Output is de�ned in the simamain con�guration:



Figure 20: Output De�nition

The type attribute de�nes the output type; there is, currently, only one possible value:fifo. The path attribute de�nes the path to the named pipe:

<Outputtype=" f i f o "path=" . / samples /mos/ fi fo_mos "/>

Output nodes must be de�ned within the mos node and the partition nodes.

For easy debugging, the output displayed on the screen, is written to �les named likethe �fo with .txt added. The �les are written in the directory where the corresponding�fo is located.

Because simout is limited to display the output of six partitions, three per row withat most two rows, it must be de�ned which partitions should be displayed during thecurrent session. This is done by the visible attribute of the partition node. Onlythose partitions with the visible attribute, set to true, are displayed.

simout is a convenient tool for visual control over the execution of partitioned appli-cations and for output-based debugging. There are, however, some drawbacks. First,simout itself needs processing time and system bus resources. This may be mitigatedby assigning a di�erent set of processor cores to to the ima system and the simout

tool. Also, simout runs with a lower priority than mos and the apex applications. Butstill, the simout tool needs some bandwidth on the system bus.

Second, writing to standard output in general is an easy means for debugging, butchanges the execution characteristics of the program. In particular, the �ushing ofthe output device is an expensive operation. The fact that fifos are used, causesadditional coding overhead: fifos must be �ushed explicitly in the user code. Theprogrammer may decide whether she wants to �ush each printed line or if she prefersto �ush only once per period.

In conclusion, simout is useful for debugging an application running in an ima envi-ronment. For more sophisticated simulation of an ima system, logging mechanisms,like the arinc 653 logbook, that are also used on the target system, are preferable.

4.6 Logbooks

arinc 653 logbooks are implemented by sima through system partition, shared mem-ory and ordinary �les. A system partition is used to engrave messages in the logbook,it reads from the IN_PROGRESS bu�er and engraves in the NVM �le. Its purposeis to provide arinc 653 logbook two step writing behaviour � the time demandedfor engraving messages belong to the system partition and not to the logbook ownerpartition.

A shared memory segment is used to realize logbook IN_PROGRESS bu�er, it isvisible to the partition that owns the logbook and system partition. The applicationpartition writes messages to the shared memory and accesses the NVM �le for readingoperations. Figure 21 illustrates the logbook elements within sima implementation.

Within a partition schedule window, messages can be written to the intermediary



bu�er until this bu�er is full. In a second step, the messages are engraved to theNVM by the system partition.

Whenever a logbook is speci�ed within the module, a system partition must also existin the same module. The time spent for accessing the NVM for writing operations istaken from the system partition schedule windows. Notice that one system partitioncan be used (and is usually used) to engrave messages of all the logbooks in the module.However, it is the system integrators responsibility to specify appropriate schedulewindows for this partition. The position of the system partition schedule windowsin the major time frame and the amount of time attributed for it determines whenthe messages are actually engraved. Large logbooks (in terms of IN_PROGRESSbu�er capacity) require longer system partition schedule windows than small ones.Messages written to the IN_PROGRESS bu�er are only expected to change statusto ENGRAVED after the execution of such system partition.

Like ports, sima logbooks require information that does not belong to the arinc 653con�guration. The name for the logbook NVM and a key for the shared memory mustbe provided in the sima con�guration. This information (together with the arinc 653con�guration information) is used by the POS to allocate and initialize the resourcesbefore the logbook is used. As illustrated in the listing below, a DeviceType node isalso speci�ed. Currently, only one type is de�ned; �file�. The logbook name in theLogbookName �eld must be the same given in the arinc 653 con�guration.

Figure 21: Logbook in SIMA

<Logbook LogbookName="ManagementData"NVMName="P2LB1"DeviceType=" f i l e "LogbookKey="60097">

</Logbook>

sima provides a tool for creating logbooks system partition, the �les required for thelogbook NVM and stubs that provide the pos, information from the con�guration�les (both arinc 653 and sima main con�guration). For generating logbook stubsmakebooks is used as exempli�ed below:

sima provides a tool for creating: (i) logbooks system partition, (ii) the �les requiredfor the logbook NVM and (iii) stubs that provides the pos , information from thecon�guration �les (both arinc 653 and sima main con�guration). For generatinglogbook stubs makebooks is used as exempli�ed below:

makebooks <sima config> <partition name> <stub source file name>

makebooks config/sima.xml "Flight Controls" logbook_stub.c

In this example makebooks tool input is a sima con�guration �le config/sima.xml

and the name of the partition that owns the logbook (Flight Controls). As output,



makebooks generates the stub for the application partition and the �les required bythe logbook NVM. The generated stub source code is named according to the nameprovided in the line invoking the tool.

The generated stub (logbook_stub.c) must be linked to both partitions; the parti-tion that owns the logbook and to the system partition that engraves its messages. Itcontains functions de�nitions to be invoked by the POS that will return informationrequired for the POS to initialize logbooks � information retrieved from the con�gu-ration �le.

Figure 22 shows makebooks in the context of the sima tool chain:

Figure 22: sima logbook toolchain

The value speci�ed in NVMName node in sima con�guration will be used to name two�les: theNVM �le that stores the messages and the �le that stores the index of the lastengraved message. The �les generated from the example given are named "P2LB1"and "P2LB1-new". The �rst �le is created with messages size �eld initialized withzeros and empty slots for messages. The second one, stores the index of the lastengraved message and the number of messages that have been engraved. It is alsoinitialised with zeros. This static format for the �les allows the recovery of engravedmessages in a previous simulation session.

Before generating the NVM �les the makebooks tool will search for the �les in thecurrent directory (location from which it was invoked). When the �les are not found,a directory named "SIMA-TMP" is created and the NVM �les are generated init. Before running the application, those �les must be placed in the location theapplication is invoked.

When used with the parameter �system, the makebooks tool generates the system par-tition that engraves the logbooks messages. Notice that the parameter <partition

name> was given as empty, therefore the generated system partition will engrave mes-sages from all the logbooks declared in the sima.xml and arinc 653 con�guration.It is possible to generate system partitions to engrave messages from one partitiononly by giving this partition name as parameter. It can be used for the partition (andthe system partition) execution in standalone mode or for distributing the engraveprocesses of di�erent logbooks through di�erent system partitions within the module.

makebooks --system <sima config> <partition name>

<system partition source file name>

makebooks --system config/sima.xml "" system_partition.c



4.7 Use of posix in apex Applications

posix calls can be used within a sima apex application. You can �nd some simpleexamples in the sample applications where printf and exit are used, for instance.

You should be aware that posix calls are not handled by sima, but directly by theLinux kernel and the correspondig posix library. This means that an arinc 653

process that is preempted due to a posix call, sleep for instance, but also a printf,waiting for a resource, may preempt the caller, remains RUNNING in the apex schedulerand will block access to the processor for other READY processes with equal or lowerpriority. Mixing posix and apex is, thus, a means to ease application debugging, faultinjection or the integration of some simulation means. But it is certainly not an optionfor the �nal target code.

You should be careful with pthread calls. It is possible to create posix threads inan apex application, but the e�ects on scheduling are di�cult to predict. A lot ofsituations may result where a running pthread will prevent the currenlty RUNNING

apex process to execute. Additionally, pthreads are not scheduled by the mos; thismeans a pthread will continue to execute when the execution window of its partitionends. Thus, pthreads break the sima time partitioning!

Moreover, you should be aware of the fact that sima, internally, uses threads andsignals to emulate arinc 653 processes. To avoid that your pthreads cause deadlockswith the internally used threads, you should protect all pthread calls in your code.There is a sima speci�c system service apx_posix_protect (see section 4.8) that shouldbe used before and after sequences, using pthread calls, e.g.:

apx_posix_protect(APX_POSIX_ENTER);

rc = pthread_mutex_lock(&mutex);

if (rc != OK) {

do_some_error_handling();

}

apx_posix_protect(APX_POSIX_EXIT);

do_something();

apx_posix_protect(APX_POSIX_ENTER);

rc = pthread_mutex_unlock(&mutex);

if (rc != OK) {

do_some_error_handling();

}

apx_posix_protect(APX_POSIX_EXIT);

An important restriction for the use of posix is the use of signals. You may send signalsthat are not used by sima (see section 6). However, signal calls must be protectedas shown above. Also, you must never de�ne a signal handler on an apex process.Doing so, you would overwrite the standard signal handlers that are used internallyby sima and that de�ne the behaviour of the apex. Again, be aware that pthreadsare not scheduled by the apex process and partition schedulers. Their behaviour isexclusively de�ned by Linux and as such will never comply to the behaviour speci�edby arinc 653.



4.8 sima speci�c Services

You already know the debug calls de�ned in apex_debug:

• apx_sched_show;

• apx_show_time_line;

Please refer to section 4.1 for more details.

In apex_system.h more sima speci�c services are de�ned:

• apx_shutdown_module

• apx_posix_protect;

Using these services, you shall be aware that your code is not portable to other arinc653 os. The services are intended to be used for simulation-related code and, usually,within a pluggable component as, for instance, a system paritition.

The apx_shutdown_module service can be used to stop or reboot a module from apartition. Such a service should, of course, only be issued by a partition with specialprivileges. However, currenlty no mechanisms to ensure this is de�ned. Any partitionmay call this service. The service is de�ned as follows:

procedure apx_shutdown_module

(MODE : in APX_SHUTDOWN_MODE_TYPE;

RETURN_CODE : out RETURN_CODE_TYPE) is

error

when (current partition is not allowed to issue this command) =>

RETURN_CODE := INVALID_CONFIG; -- Currently not implemented!

when (MODE does not identify a valid shutdown mode) =>

RETURN_CODE := INVALID_PARAMETER;

normal

if (MODE is APX_SHUTDOWN_HALT) then

stop module;

else if (MODE is APX_SHUTDOWN_RESET) then

reboot module;

end if;

end apx_shutdown;



The apx_posix_protect service shall be used to protect pthread and posix signal

calls in an apex program. It is de�ned as follows:

procedure apx_posix_protect

(MODE: in APX_PROTECTION_MODE_TYPE) is

error

when (MODE does not identify a valid protection mode) =>

RETURN_CODE := INVALID_PARAMETER;

when (preemption is disabled or

process is error handler process) =>

RETURN_CODE := INVALID_MODE;

normal

if (MODE is APX_POSIX_ENTER) then

disable scheduling;

disable POSIX signals;

else if (MODE is APX_POSIX_EXIT) then

enable scheduling;

enable POSIX signals;

end if;

end apx_posix_protect;

4.9 Ada Binding

It is possible to use Ada with sima. sima does not provide an Ada kernel, but bindsAda code with the pos library, using the gnat C-Ada interface and the arinc 653

speci�ed Ada interface (apex.ads).

To link C and Ada you �rst have to initialise the Ada environment. This is donein the already known entry_point. sima provides a standard entry_point for Adaprograms that is de�ned as follows:

#include <a653.h>

extern void adainit();

extern void adafinal();

int entry_point() {

RETURN_CODE_TYPE rc;

adainit();

rc = ada_entry_point();

adafinal();

return (int)rc;

}

The ada_entry_point is the Ada pendent to the entry_point for C programs. Here,the arinc 653 intialisation routine should be called.

To compile your Ada code �les do:

# create the Ada interface mycode.ali

gcc -c -gnatc mycode.ads

# create the object file mycode.o

gcc -c mycode.adb

Now you can bind your Ada objects:



gnatbind -n mycode.ali

Finally link the application:

gnatlink ada_link.o mycode.ali

-o myapp

-lpthread -lrt pos.a

noports.o nobooks.o main.o

Note that Ada programs use the same external interface as C programs. Consequently,you call an Ada program like any other sima program as well:

sudo ./myapp -s

The �rst example in the ada directory, for instance, is called like this:

sudo ./ada_test.exe -s

It should produce the following output:

Ada code: ada_entry_point

Ada code: CREATE_PROCESS process1_Ada

NO_ERROR

Ada code: pid1...

3

Ada code: CREATE_PROCESS process2_Ada

NO_ERROR

Ada code: pid2...

4

Ada code: START

NO_ERROR

Ada code: SET_PARTITION_MODE

NO_ERROR

Ada code: EXIT ada_entry_point

Ada partition1 process1: hello world












5 Application Development Walkthrough

5.1 Use Case Description

This section will discuss how sima can be used in ima software development. For thispurpose, the control application will be used, you �nd among the other examples inthe sample directory. The control application is di�erent from the other example asit does not only implement an ima module, but a whole subsystem as it can be foundon real aircrafts. The control system is modelled after a typical control application,consisting of a plant (sensor and actuator), a controller and an hmi showing the currentvalue of the controlled entity.

The value that is controlled by the application is nothing particular. It is a simpleinteger value. You may think of something like engine temperature, cabin pressure orground speed. In reality, the subsystem to control such a value is, of course, muchmore complex than the simple logic of the application presented here. However, thebasic structure is similar to systems found on-board.

The system is autonomous in the sense that no intervention by an external actor isnecessary � nor possible. In fact, the only use case for an external actor is to observethe value. This is depicted in Figure 23.

Figure 23: Control Use Case

The three components of the system are hosted on di�erent on-board computers. Theplant is a subsystem consisting of sensor, actuator and a Remote Control Unit (rcu),connected to these devices. An rcu is not an ima module, but a much simpler comput-ing resource that is mainly con�guration de�ned, but with the capability of runninga simple, typically single-threaded application. The plant, used in the example, is, ofcourse, just a simulation of such a device. It implements a logic to change the con-trolled value in the same way the environment would do. The most important factorin�uencing the value is the state of the actuator. The actuator may be in one of threestates:

• increasing (inc)

• decreasing (dec)

• none (none)

The actuator starts processing in the none state.

The controlled value changes every 30 milliseconds according to the actuator's state:

• If the actuator has never been in inc or dec since system start, the value isincreased by 1;



• If the actuator is in none state the value is either decreased by 1 if the previousstate of the actuator was dec or increased by 1 if the previous state of theactuator was inc;

• If the actuator is in inc state the value is increased by 2.

• If the actuator is in dec state the value is decreased by 2.

The plant is implemented using the apex interface. Since it is not an ima applicationit could have been implemented using any other api such as posix or even a simplerscripting language like Python. The apex was mainly chosen, because it providesstrong means for controlling real-time characteristics.

The control application, called ctl, is an ima application that is hosted on a module.The simple logic of our control application could have been completely implementedinto the plant. However, the purpose of the use case is the discussion of ima devel-opment using sima. Therefore, the system follows a typical implementation wherecomplex data processing is done on an ima module.

The purpose of the ctl is to keep the controlled value within a given range by changingthe state of the actuator and to update the representation of the value in the hmi. Toachieve this, the ctl communicates with the plant and the panel. From the plant, itreceives the current sensor value and forwards it to the panel whenever it has changed;if necessary, it changes the state of the actuator by sending an actuator command tothe plant.

The panel is hosted on a cockpit display computer. A real hmi would use the arinc661 interface. In the example application, the hmi is represented by a simple Pythonscript using the TK platform.

The system is shown in Figure 24.

Figure 24: Control Deployment View

This diagram abstracts from a lot of details that have to be taken into account inreality: The module should be part of a cabinet, redundant units for all componentsare left out, the network is simpli�ed etc. However, for the purpose of this section,the level of detail is su�cient.

5.2 Use Case Installation and Execution

The demonstrator application is built like the other complex examples as well: justtype make control to generate all the objects necessary for execution. Execution is,however, a bit di�erent.

Three components must be started, only one of which is part of an IMA module. Thebest way to execute the components depends on the system (hardware, os) you are



using and on the degree of realism you want to achieve. Of course, you can run allcomponents on the same computer. But be aware that the three components, runningon the same host, will steal time from each other. This may lead to deadline misses,in particular on older hardware and on non-patched Linux kernels.

There is another limitation for the panel application; the panel is implemented inPython, using the TK platform. The underlying TK platform must be compiled withthe thread-safe option. This is true for Debian-based Linux distributions (like, forexample, Ubuntu) and for the Windows-based Python package; but it is not true forRedhat-based distributions (such as Fedora). You can test whether your TK plat-form is thread-safe or not by means of the checkthreads.py script you will �nd insamples/control/src/hmi.

If you your TK platform is not thread-safe you can either

• compile TK from the source code; this will require some e�ort (and the procedureis not described within this document);

• or simply run the panel on another computer, like a Windows machine.

If you decide to host the applications on di�erent machines you have to adapt thecon�guration �les to your actual environment. There are three con�gurations youshould change:

• simaplant.xml: This is the sima con�guration for the plant component.

Here you have to adapt the udpmapping of the outgoing sampling port CONTROL-_SAMPLE to the ip address of the computer the ctl application is running on.Note that this change has to be applied to the pseudo partition.

You also have to change the udp mapping of the queuing port ACTUATOR_Q. Theip address must correspond to the interface (eth0, eth1,...) that is connect tothe machine, the ctl is running on. In other words: this is the ip address of themachine hosting the plant as it is seen by the ctl. Note that this change hasto be applied to the queuing port de�nition, not to the pseudo partition. Thefollowing listing shows the nodes that have to be changed:

<Pa r t i t i on P a r t i t i o n I d e n t i f i e r="1"PartitionName="Plant ">

<Queuing_PortName="ACTUATOR_Q"Type="UDP"IP=" 12 7 . 0 . 0 . 1 " <!−− This va lue

has to be changed −−>Port="12383"/>

</ Par t i t i on><Pseudo_Partit ion Name="CONTROL_SAMPLE">

<Sampling_PortName="CONTROL_SAMPLE"Type="UDP"IP=" 12 7 . 0 . 0 . 1 " <!−− This va lue

has to bechanged −−>

Port="12382"/></Pseudo_Partit ion>



• simactlint.xml: This is the sima con�guration for the CTL component usingthe simout-tool.

Here, two di�erent channels have to be adapted: The communication with theplant and the communication with the hmi. Note that all changes are appliedto partition 1 ("Control") or pseudo partitions related to it.

First, you have to set the ip address of the listening sampling port SENSOR_-

SMP to the interface (eth0, eth1,...) that is connected with the computer, theplant is running on. In other words: this is the ip address of the computer asit is seen by the plant; it is the same ip address you have already used for theCONTROL_SAMPLE pseudo partition above. You also have to adapt the pseudopartition port ACTUATOR. The ip address must correspond to the computer, theplant is running on and that you already have used above for the ACTUATOR_Q.

The second channel to change is the hmi. You have to adapt udp mapping ofthe pseudo partition PANEL to the ip of the computer, the pannel application isrunning on. The following listing shows the nodes that have to be changed:

<Pa r t i t i on P a r t i t i o n I d e n t i f i e r="1"PartitionName="Control ">

<Sampling_PortName="SENSOR_SMP"Type="UDP"IP=" 12 7 . 0 . 0 . 1 " <!−− This va lue


Port="12382"/></ Par t i t i on><Pseudo_Partit ion Name="ACTUATOR">

<Queuing_PortName="ACTUATOR"Type="UDP"IP=" 12 7 . 0 . 0 . 1 " <!−− This va lue


Port="12383"/></Pseudo_Partit ion><Pseudo_Partit ion Name="PANEL">

<Queuing_PortName="PANEL"Type="UDP"IP=" 12 7 . 0 . 0 . 1 " <!−− This va lue


Port="12384"/></Pseudo_Partit ion>

• simactlintmos.xml: This is the sima con�guration for the CTL componentusing the mos-tool from the command line, without using simout. You onlyhave to change this �le if you actually want to run your application withoutsimout. The changes are identical to the changes in the simactlint.xml.

Do not forget to rebuild the use case by running make control!

Now you are able to start the components. We will �rst show how to manually runcomponent by component:



1. Start the panel:

cd samples/control/src/hmi

python demopanel.py <ip-address-of-network-interface> <port>

For example:

python demopanel.py 192.168.100.1 12384

Note that the port 12384 is used in the ctl con�guration.

2. Start the plant in standalone mode with connected ports:

sudo samples/control/src/plant/plant -s -c -p=30000000

Note that the period is set to 30 milliseconds. This may be too demanding foryour machine. In this case, you should select a higher value in the entry_pointof plant.c.

3. Start the ima system:

sudo bin/simout samples/control/config/simactlint.xml

There is a script in the bin directory that starts the ima system and the plant togetheron one machine. The script is named startdemo.sh. It is called like:

sudo bin/startdemo.sh <number-of-processor-cores>

On a single core machine you should type:

sudo bin/startdemo.sh 1

On a dual or quad core machine you may use:

sudo bin/startdemo.sh 2

When the script is called with a number of cores greater than 1 it will execute theima system and the plant application on di�erent processor cores. Otherwise theyare started without any processor a�nity.

The script will �rst start the plant application in the background and then the imasystem by means of simout. When you terminate the ima system by typing q theplant will be stopped and the screen will be reset.

You should not interrupt the script by using <ctrl>-c or <ctrl>-d : The script willterminate and leave the system in an unknown state and you will have to do somecleanup manually.



5.3 Design

We will now start a kind of role play. Let us assume we are working for a company thatis currently developing the control application. The requirements have been de�ned byour customer and a �rst iteration of requirements analysis has already been performed.From this �rst analysis, a high-level design has been derived that is shown in Figure25:

Figure 25: Control Components

Now, before going too deep into the detailed design, we want to better understandthe customer's requirements. To achieve this, we will build a set of very simple proto-types. This will help us to take the correct design decisions later; we also expect theprototypes to ease our discussions with the customer. We want to present somethingthat already looks quite real, long before we start to mess around with hardware in-tegration, worst case execution time and schedulability analysis. In other words, wewant to focus on the functional requirements and progressively approximate the �naltarget, including real-time and rams requirements step by step. (Of course, someconsiderations about timing and possible architectures, must be made and are presentin the early design, already by using arinc simulation.) Note that prototyping in thissense is often considered an important step in system engineering. It will be veryvaluable later, during acceptance testing.

Three teams are formed to study di�erent aspects of the requirements:

• Team 1: Develops a model to simulate the environment and the e�ects of theactuator. The team is also responsible for the development of a communicationstub that will be connected to the control application by means of arinc 653

ports.



• Team 2: Has three objectives:

� Objective 1: to develop a proper state representation that will be the coreof the ctl application.

� Objective 2: to connect the state representation with the plant such thatvalues from the model can be used for testing.

� Objective 3: to connect the state representation with the plant such thatactuator commands can be sent.

By achieving the three goals the team will be able to validate the high-leveldesign against the functional requirements. It is not yet an objective to imposethe timing requirements on the application. This will be done at a later stage.

• Team 3: Will analyse the timing requirements and de�ne the arinc 653 con-�guration to integrate the ctl on an ima module.

We will now look at the work of team 2. The �rst result is a speci�cation for the controllogic. This speci�cation is captured in the function ctl_state_check() in state.c

(see: samples/control/src/ctl). It is also given here in a formal way, where

v is the state of the controlled value;

max is the upper bound value;

min is the lower bound value;

avg is the average of MAX and MIN ;

a is the state of the actuator;

inc is the actuator state increasing ;

dec is the actuator state decreasing ;

nrm is the actuator state normal ;

nop is no operation;

⇐ is an assignment.

IF (a = INC) and (v ≥ AV G) THEN a⇐ DECELSE IF (a = DEC) and (v ≤ AV G) THEN a⇐ INCELSE IF (a = NRM) THENIF (v < MIN) THEN a⇐ INCELSE IF (v > MAX) THEN a⇐ DECELSE NOPELSE NOP

Now the question arises how the logic can be tested. A good option is using a functionallanguage like Haskell. However, the team has also other objectives, namely to providethe means to integrate the control logic with the plant later. For this reason, theteam decides to implement the logic in C, using the sima simulator in standalonemode. The �rst step will be the integration with a simple test driver (test.c insamples/control/src/ctl). Two considerations drive the further design:



1. The integration of the test driver shall be as simple as possible;

2. Later a periodic process will be needed to update the state of the controlledvalue. The frequency of this process is part of the requirements. The controllogic itself, however, was speci�ed without any relation to time.

Taking both considerations into account, the team decides to decouple the periodicprocess, to be developed later, and the control logic. This can be seen as a component-oriented approach: the control logic provides a well-de�ned interface to be connectedto any other component, using this interface. As interface, the team selects an intra-partition communication means, an arinc 653 message bu�er. This message bu�erwill be written by external components, namely the test driver and the periodic processreading sensor samples, and will be read by the state component.

A new function is added to state.c, the ctl_state_listen(). This function reads acommand from a message bu�er. A command is de�ned by

• An identi�er that may be used in logging and debugging;

• The type of the command;

� MIN changes the MIN value;

� MAX changes the MAX value;

� UPD changes the state of the controll variable.

Note that the MIN and MAX commands are not foreseen in the requirementsas we have discussed them before. For the tests the team is setting up, thepossibility to change the range values is, however, very interesting to study thebehaviour of the control logic with di�erent ranges.

• The command data (the value to set, for instance);

The �rst program, hence, conists of the test driver test.c and the control logicstate.c. To complete its implementation, the intialisation routines (ctl_state_-init() in state.c and test_init() in test.c) must be de�ned. The routine ctl_-

state_init()

• creates the message bu�er, using the arinc 653 service CREATE_BUFFER;

• creates the process that implements the component, using the arinc 653 serviceCREATE_PROCESS;

• starts this process, using the arinc 653 service START;

The routine test_init()

• creates the process that implements the test component, using the arinc 653

service CREATE_PROCESS;

• starts this process, using the arinc 653 service START;

The initialisation routines have to be called from the sima entry_point. You will �ndan entry.c in the samples/control/src/ctl directory. Note that this entry pointis for the ctl application in its �nal version. It does not call the test initialisationroutine. To de�ne an entry point for a test application, test_entry.c, is left as anexercise to the user.

The test application is now compiled and linked:



gcc -I./src -I$(SIMA_ROOT)/include -g -c state.c -o state.o

gcc -I./src -I$(SIMA_ROOT)/include -g -c test.c -o test.o

gcc -I./src -I$(SIMA_ROOT)/include -g -c test_entry.c -o test_entry.o

gcc -lpthread -lrt -o tst_state \

$(SIMA_ROOT)/usr/noports.o \

$(SIMA_ROOT)/usr/nobooks.o \

$(SIMA_ROOT)/usr/main.o \

state.o test.o test_entry.o

To ease the build procedure, the team sets-up the following make�le:

CC = gcc

AR = ar

CFLAGS = -g -Wall

INC = -I./src -I./include -I./

LIB = -lpthread -lrt

ctlsrc = samples/control/src/ctl

TSTOBJ = \

$(ctlsrc)/state.o \

$(ctlsrc)/test.o \

$(ctlsrc)/test_entry.o \

USROBJ = \

$(SIMA_ROOT)/usr/noports.o \


$(SIMA_ROOT)/usr/make.o

.SUFFIXES: .o .c

.c.o:

$(CC) $(CFLAGS) $(INC) -c -o $@ $<

bin/tst_state: $(TSTOBJ)

$(CC) $(LIB) -o bin/tst_state \

$(TSTOBJ) \

$(POS) $(USROBJ)

test: bin/tst_state

all: test

Now, the experiments with the test application can begin. The team starts by simplyediting the test procedure, using di�erent values to send to the control logic and re-compiling the test program. Then they execute the program by:

sudo bin/tst_state -s

After some tests with the application, the team starts to de�ne a set of unit tests onthe control logic. The idea is that this unit tests can later be reused for the real targetapplication that will be developed on the base of the prototype code.

The team's next objective is the integration of the control logic with the simulationsthat are developed in parallel by team 1. The frequency de�ned for the control ap-plication is 5Hz. So the team de�nes a periodic process with a period of 200ms.This process performs is de�ned within the sns component (see ctl_sns_sample insamples/control/src/ctl/sns.c) and performs the following tasks:



• Reading a sampling port by means of the arinc 653 service READ_SAMPLING_-

MESSAGE;

• Updating the state of the controlled variable in the control logic by means ofctl_state_update() de�ned in samples/control/src/ctl/state.c;

• Wating for the next release point by means of the arinc 653 service WAIT_PERIODIC;

The initialisation routine is de�ned as ctl_sns_init().

• creates the sampling port, using the arinc 653 service CREATE_SAMPLING_PORT;

• creates the process that implements the sampling component, using the arinc653 service CREATE_PROCESS;

• starts this process, using the arinc 653 service START.

Note that the intialisation routines of the components of the control application arecalled by the meta intialisation routine ctl_init() which is de�ned in init.c. Thelast call of ctl_init() is SET_PARTITION_MODE. By setting the partition mode tonormal the initialisation phase ends. The scheduler is activated and the aperiodicprocesses are started. Periodic processes will remain in waiting unitl the next releasepoint of the partition.

The sns component di�ers in two important aspects from the ctl component:

• It is a periodic;

• With the sampling port, it provides an inter-partition interface.

These di�erences have consequences on the compilation and the execution. We haveto link the port mapping and channel con�guration into the application and later, onexecution, we have to respect the frequency, be it in an ima environment, be it instandalone execution.

Concerning the ports con�guration, we have to add the makeports tool to the buildchain. As described in section 4.2, the makeports tool takes two arguments: Thesima main con�guration �le and the partition, we want to generate port data for.So, the �rst step is to de�ne a con�guration. Building a complete ima con�gura-tion which may be time-consuming and error-prone task is not an objective for team2. Therefore, they decide only to de�ne what is essential for their task. You �ndthe reduced con�guration in samples/control/config/simactl.xml and samples/-

control/config/ctl653.xml. You see that only partition 1 ("Control") and its portsand channels are de�ned. There are no hm, partition scheduling or simout relatedcon�guration data.

From this torso con�guration, the necessary port con�guration can be created bycalling makeports:

makeports \

samples/control/config/simactl.xml \

Control \

> samples/control/src/ctl/ports.c

The make�le is also changed:



CC = gcc

AR = ar

CFLAGS = -g -Wall

INC = -I./src -I./include -I./

LIB = -lpthread -lrt

ctlsrc = samples/control/src/ctl

ctlcfg = samples/control/config

CTLOBJ= \

$(ctlsrc)/state.o \

$(ctlsrc)/sns.o \

$(ctlsrc)/ports.o \

$(ctlsrc)/entry.o \

USROBJ = \


$(SIMA_ROOT)/usr/make.o

.SUFFIXES: .o .c

.c.o:

$(CC) $(CFLAGS) $(INC) -c -o $@ $<

$(ctlsrc)/ports.c: $(ctlcfg)/simactl.xml $(ctlcfg)/ctl653.xml

makeports \

$(ctlcfg)/simactl \

Control \

> $(ctlsrc)/ports.c

bin/ctl: $(TSTOBJ)

$(CC) $(LIB) -o bin/ctl_state \

$(CTLOBJ) \

$(POS) $(USROBJ)

test: bin/tst_state

all: test

Note that in some situations, the makeports tool can behave a bit nasty. When anerror occurs on makeports the resulting �le (ports.c) is probably empty, but exists.In the next make run, you will get an error when the compiler tries to process ports.c.You have to manually remove the �le. Good practice is to de�ne a dummy dependencythat removes ports.c (using -f for the case that it does not exist) at the beginningof the compilation.

Now, we can execute the new ctl application that already contains the periodic sns

component. In standalone mode, we are running the component without any ima

context, just as an ordinary posix process. However, we are running a periodic processthat must be synchronised with the partition period. Therefore, it is good practice tocall an application that contains periodic processes with the �period parameter thatde�nes the partition period. In our case, since the application frequency is 5Hz, wecall the application with a period of 200 milliseconds:

sudo bin/ctl -s -c -p=200000000

But there is a surprise: The program terminates with an HM message:




=> Partition in standalone mode can't raise

partition error handler.

The team looks-up error 1022 in this manual (see section 8.1.7): A segmentation fault.This is a case for valgrind. So, the program is executed ones again:

sudo valgrind samples/control/src/ctl -s -c -p=100000000

The �rst try is disappointing since valgrind causes ctl to lose a deadline:

Can't read sampling port 'SENSOR_SMP': 1

Message invalid

Process CTL_SNS missed its deadline:

at.........: 00000719400000

release was: 00000604800000

deadtime...: 00000704800000

wcet.......: 00000100000000

period.....: 00000200000000


=> Partition in standalone mode can't

raise partition error handler.

It is decided to temporally relax the deadlines to SOFT to execute ctl with thememory debugger. This works �ne and now valgrind gives useful output:

==7659== Thread 5:

==7659== Invalid write of size 1

==7659== at 0x4007B8F: memcpy (mc_replace_strmem.c:402)

==7659== by 0x80494E5: ctl_state_report (state.c:87)

==7659== by 0x80495F0: ctl_state_check (state.c:117)

==7659== by 0x80496C8: ctl_state_listen (state.c:147)

==7659== by 0x49494D: clone (in /lib/libc-2.10.1.so)

==7659== Address 0xfff0900c is not stack'd, malloc'd or

(recently) free'd

Obviously, someone used a wrong memory address. With the help of the debugger,the code line is quickly found and corrected. Now, the experiments can continue.

The �nal step, to reach the three objectives is the integration of the actuator. Theconnection to the integrator is implemented on a queuing port that sends actuatorcommands to plant. Please refer to act.c. Additionally, the team implements asimple Python gui and integrates with the ctl component. The connection is againimplemented using a queuing port that sends an update whenever the state of thecontrolled value changes. Please refer to pnl.c for details.

At the end of its task, team 2 reached the three objectives. The report about theiractivity recommends the following design for the ctl component:



Figure 26: CTL Design

With the help of the prototype the team is able to convince the other teams thatthe proposed design ful�ls the functional requirements. The next task will be todemonstrate that it also ful�ls its timing and rams requirements.

This was the objective of team 3. Team 3 developed a proposal for the arinc 653 con-�guration, including a partition schedule, communication paths and an error handlingstrategy.

Concerning error handling, the ctl should handle errors locally whenever possible.Otherwise, the error is propagated to the partition hm which sets the partition towarm_start to restart the application in a clean state.

An example of an error that can be handled locally is a full message bu�er. In thiscase, the error handler consumes all the messages in the bu�er and terminates. Thisis implemented in ctl_err_clean_buf (in err.c.

An example of an error that cannot be handled locally is a full queuing port. In thiscase, the error handler veri�es that the queuing port is full and informs the systembefore it sets the partition to warm_start. (Actually, it does not inform the system,but the user, by printing a message on standard output.) This is implemented inctl_err_check_queue.

Deadline misses are directly propagated to the partition hm that, in its turn, sets thepartition to warm_start.

Finally, if the error handler runs into an error, for example, if it can't call the partitionhm, it autonmously, sets the partition to warm_start. (If even this fails, the posixcall exit is called which is, of course, a mere simulation means and not intended to beused on the �nal target.)



During requirements analysis review with representatives from the customer, our teampresents the prototype that has been developed so far. The team presents the expectedbehaviour for di�erent states of the actuator, shows the output, using the Pythonhmi, demonstrates the compliance to the real-time requirement of 5Hz and discussesthe error handling strategy. Even some proposals are made, how to implement therequirements, e.g. the communication channels and the component-oriented approach.The customer is very pleased with the results and the milestone is reached. Ourcompany can continue with the design activities, based on the results that have alreadybeen achieved using the sima simulator.

5.4 Integration and Simulation

We will now end our role play. But before we leave this walktrhough, some more hintson integration of a full ima simulation will be given in this section. The remarks arerelated to the con�guration simactlint.xml and ctl653int.xml.

We assume that three di�erent computers are used for the simulator:

• 192.168.1.1 hosts the plant;

• 192.168.1.2 hosts the ima system;

• 192.168.1.3 hosts the panel.

To achieve this, again, the ip addresses and udp ports in the sima con�gurations haveto be adapted:

• simaplant.xml

� In Partition Plant :

<!−− This i s a DESTINATION APEX por tl i s t e n i n g to i t s UDP por t −−>

<Queuing_PortName="ACTUATOR_Q"Type="UDP"IP=" 192 . 1 6 8 . 1 . 1 "Port="12383"/>

� In Pseudo Partition control_sample:

<Pseudo_Partit ion Name="CONTROL_SAMPLE"><!−− This i s a SOURCE APEX por t

i t has to know where to sendi t s messages to −−>

<Sampling_PortName="CONTROL_SAMPLE"Type="UDP"IP=" 192 . 1 6 8 . 1 . 2 "Port="12382"/>


• simactlint:xml:

� In Partition Control :



<!−− This i s a DESTINATION APEX por tl i s t e n i n g to i t s UDP por t −−>

<Sampling_PortName="SENSOR_SMP"Type="UDP"IP=" 192 . 1 6 8 . 1 . 2 "Port="12382"/>

� In Pseudo_Partition actuator:

<Pseudo_Partit ion Name="ACTUATOR"><!−− This i s a SOURCE APEX por t


<Queuing_PortName="ACTUATOR"Type="UDP"IP=" 192 . 1 6 8 . 1 . 1 "Port="12383"/>


� In Pseudo_Partition panel:

<Pseudo_Partit ion Name="PANEL"><!−− This i s SOURCE APEX por t


<Queuing_PortName="PANEL"Type="UDP"IP=" 192 . 1 6 8 . 1 . 3 "Port="12384"/>


To get the port and channel con�guration right, in particular on systems using morethan one computer, is probably the most error-prone and as such most frustratingpiece of work. You should always envision:

• What is a port used for: listening or sending?

• Ports that are listened to should always be de�ned with the ip address of theinterface the sender is connected to; this de�nition is applied to the local portde�nition, within the paratition node. Remember that the pseudo partition isa mere representation of an external entity, it does not correspond to any realresource on your machine.

• Ports that are sent to should be de�ned with the ip address of the receiver inthe pseudo partition; a destination port is just a representation of a remotetarget; so there is nothing that corresponds directly to the port de�ned withinthe partition. It is nothing more than a representation of the arinc 653 portin the con�guration �le.

The next di�cult task in system con�guration is the partition schedule. It is crucialthat the execution windows re�ect the frequency of the applications. If we have anapplication that runs at 5Hz:



• The corresponding Partition_Schedule must be de�ned with

� PeriodSeconds set to "0.2";

� PeriodDuration set to the sum of all durations of the execution windowsbelonging to one partition period;

• In the correspondig Window_Schedules there must be one, every 200 millisec-onds, with PartitionPeriodStart set to "true".

Have a look at the following example:

<Part i t ion_Schedule P a r t i t i o n I d e n t i f i e r="1"PartitionName="Control "PeriodSeconds=" 0 .2 "PeriodDurationSeconds=" 0 .1 ">

<!−− t h i s window s t a r t s a t the beg inn ingo f the major frame and s t a r t s , hence ,a per iod .I t runs f o r 100ms

−−><Window_Schedule WindowIdent i f i er="101"

WindowStartSeconds=" 0 .0 "WindowDurationSeconds=" 0 .1 "Pa r t i t i onPe r i odS ta r t=" true "/>

<!−− t h i s window s t a r t s 200msa f t e r the f i r s t one .I t , hence , s t a r t s a per iod .I t runs f o r 50ms .



<!−− t h i s window s t a r t s 300msa f t e r the f i r s t one .I t , hence , does not s t a r t a period , butcont inues the per iod o f the prev ious window .I t runs f o r 50ms .


WindowStartSeconds=" 0 .3 "WindowDurationSeconds=" 0 .05 "Pa r t i t i onPe r i odS ta r t=" f a l s e "/>



<!−− t h i s window s t a r t s 400msa f t e r the f i r s t one .I t , hence , again s t a r t s a per iod .I t runs f o r 100ms .



</Part i t ion_Schedule>

Now have a look at the Transport slices in the sima con�guration. In simactlint.xml

the transport for the Control application is de�ned rather simple:

<Transport Sta r t=" a l l "End=" a l l "StartDurat ionSeconds=" 0 .01 "EndDurationSeconds=" 0 .01 "/>

This means that all execution windows actually have start and end slices assignedto it. This makes sense, because in the application (and di�erent from our scheduleexample above) each execution window de�nes a complete period. There is, in otherwords, only one execution window per period. Since, in each period, the applicationprocesses external data, receiving this data before the processing is essential. Afterthe processing, the data shall be sent to the actuator and the hmi. Therefore, allexecution windows also have end slices.

Let us have a look at a transport de�nition that may be useful for the above schedulingexample. We want to de�ne a transport where execution windows that start a periodhave a start slice and those that end a period have an end slice. This is achieveby the selected setting in the Transport node:

<Transport Sta r t=" s e l e c t e d "End=" s e l e c t e d "StartDurat ionSeconds=" 0 .01 "EndDurationSeconds=" 0 .01 ">

<!−− This one s t a r t s and ends a period ,so we want i t to havea s t a r t and an end s l i c e


Star t=" true "End=" true "StartDurat ionSeconds=" 0 .01 "EndDurationSeconds=" 0 .01 "/>



<!−− This one s t a r t s a period ,but i t does not end i t ;we want i t to havea s t a r t s l i c e on ly


Star t=" true "End=" f a l s e "StartDurat ionSeconds=" 0 .01 "/>

<!−− This one does not s t a r t a period ,but i t does end one ;we want i t to havean end s l i c e on ly


Star t=" f a l s e "End=" true "EndDurationSeconds=" 0 .01 "/>

<!−− This one , again , s t a r t s and ends a period ,so we want i t to havea s t a r t and an end s l i c e


Star t=" true "End=" true "StartDurat ionSeconds=" 0 .01 "EndDurationSeconds=" 0 .01 "/>

</Transport>

Finally, we will examine the hm de�nitions. As already described in sections 8.1.7, thehm is de�ned in three di�erent kinds of tables:

• System_HM_Table This table de�nes on which level an error is handled:

� On module level;

� On partition level;

� On process level;

• Module_HM_Table This table de�nes the actions associated with errors handledon module level;

• Partition_HM_Table This table de�nes the actions associated with errors han-dled on partition level. Note that there is one table per partition.

Have a look at the System_State_Entry for SystemState = "5" in the System_HM_-

Table. These are errors that occur during user process execution and, hence, the mostinteresting. One of the errors, de�ned here, is the one with Error_Identifier = "6"which is deadline_miss. This error is de�ned to be handled on partition level.

So, let us go to the Partition_HM_Table for our control application which is partition"1". Again we look at System_State_Entry "5" and the error "6" with the description"time duration exceeded". The associated action is warm_start. This means, shoulda deadline miss occur during user process execution in this partition, we will restartthe partition in warm_start mode.



This can be easily veri�ed. Open sns.c in samples/control/src/ctl. At the begin-ning of the main loop of the ctl_sns_sample function, a fault is injected:

if (miss) {

sleep(1);

}

As you can see, when the global variable miss is true, the process will sleep for onesecond, using the posix system call sleep. This will cause a deadline miss excep-tion. In the initialisation routine ctl_sns_init, the partition mode is checked againstwarm_start. If the partition is in warm_start, the global variable miss is set tofalse.

Consequently, on startup, the Control partition runs into an error and restarts inwarm_start mode. It is quite fast, but try if you get it!



6 Internal Processes and Signals

The following table gives an overview on internal processes running in an apex appli-cation.

Process Name standalone connected with mos Priority

_apx_idle x x x -1

_apx_udp_listen - x x 0

_apx_upd_period x x - 100

Table 8: sima pos Internal Processes

The next table shows which posix signals are used by the pos library and the mos

tool. Signals sent by the Linux kernel and handled for hm purposes are not listed inthis table.

Signal pos mos Context

ALRM x x time management and scheduling

USR1 x x mos command

USR2 x x pos reports hm event

USR2 x - internal thread control

TRAP x - debugging

INT x x program termination

Table 9: sima posix Signals



7 Con�guration Reference

7.1 sima Con�guration

The following xml class diagram presents an overview on the sima main con�gura-tion. The sima con�guration includes some entities that are directly linked to enti-ties in the arinc 653 con�guration: Partition, Pseudo_Partition, Queuing_Port,Sampling_Port and Window_Schedule. These entities are not identical to the cor-responding types in the arinc 653 con�guration, but related to them. Identi�ers,PartitionIdentifier, WindowIdentifier or Name of ports and pseudo_partitionsmust be equal to the identi�er of the corresponding element in the arinc 653 con-�guration. The hm con�guration tables are equal to the their counterparts in arinc653; they may be included in the sima con�guration in order to avoid polluting thetarget con�guration with sima con�guration data. For detailed information on thesetables, please refer to section 4.4, the description of the arinc 653 con�guration insection 7.2 or the arinc 653 standard speci�cation itself. Other entities, mos, Outputand Transport, are completely separated from the arinc 653 world.

Please note that Pseudo_Partition is an aggregate of mos; like Partition, it alsoaggregates Queuing_Port and Sampling_Port. For clarity, these relations have beenleft out in the diagram.



Figure 27: sima Con�guration Overview

mos

• system

De�nes the module name.

Type Required Limits Default

string Yes 30 Char N/A

• a653_config

Path to the arinc 653 con�guration �le.



• Startup

Path to the mos startup script or executable.





• partitions

The number of partitions in this module.


integer Yes [1, 32] N/A

• granularity

System granularity in nanoseconds.


integer Yes [1, 1000000000] 100000

• Child Nodes

� System_HM_Table

sima error mapping to arinc 653 hm tables.


System_HM_Table Yes 1 N/A

� Output

Output de�nition for simout.


Output No 0..1 N/A

� Partition

De�nes the partitions in the system.


Partition Yes 1..n N/A

� PseudoPartition

External communication peers.


Pseudo Partition No 0..n N/A

System_HM_Table

Partition

• PartitionIdentifier

arinc 653 PartitionIdenti�er.


integer Yes N/A N/A

• PartitionName

arinc 653 PartitionName.



• SharedMemory

Shared Memory key used to communicate with the mos.





• Startup

Path to the startup script or executable of the application running in this par-tition.



• visible

De�nes whether this partition belongs to the six partitions displayed by simout.


Boolean Yes N/A N/A

• Child Nodes:

� Output

Output de�nition for this partition.


Output No 0..1 N/A

� Queuing_Port

UDP mapping for arinc 653 Queuing_Ports


Port No 0..n N/A

� Sampling_Port

UDP mapping for arinc 653 Sampling_Ports.


Port No 0..n N/A

� Transport

Default slice de�nition for arinc 653 Window_Schedules.


Transport Yes 0..1 N/A

� Logbook

Shared Memory key used to communicate with the logbook system parti-tion.Type Required Limits Default

Logbook No 0..n N/A

Pseudo_Partition

• Name

The resource name in the arinc 653 con�guration.



• Child Nodes:

� Queuing_Port

UDP mapping for arinc 653 Queuing_Ports




Port No 0..n N/A

� Sampling_Port

UDP mapping for arinc 653 Sampling_Ports


Port No 0..n N/A

Output

• type

The type of the output medium. There is currently only one valid value: �fo


OutputType Yes N/A �fo

• path

Path to the output medium



Queuing_Port and Sampling_Port

• Name

The name of the port. The name must equal the name of the correspondingport in the arinc 653 con�guration.



• Type

The type of the port mapping. There is currently only one valid value: UDP.


PortType Yes N/A UDP

• IP

The IP address given in the dotted decimal notation (127.0.0.1).


string Yes xxx.xxx.xxx.xxx N/A

• Port

The UDP port this arinc 653 port maps to.





Transport

• Start

De�nes the start slice as either

� period

The Window_Schedule de�ned as PartitionPeriodStart in the arinc 653con�guration will have a start slice.

� selected

The execution windows present in the child nodes Window_Schedule willhave start slices.

� all

All execution windows of this partition will have a start slice by default.This can be overruled by child nodes Window_Schedule

If the attribute is left out no Window_Schedule will have a start slice.


TransportSlice No N/A None

• End

De�nes the end slice as either

� period

The Window_Schedule de�ned as PartitionPeriodStart in the arinc 653con�guration will have an end slice.

� selected

The execution windows present in the child nodes Window_Schedule willhave end slices.

� all

All execution windows of this partition will have an end slice by defaultThis can be overruled by child nodes Window_Schedule.

If the attribute is left out no Window_Schedule will have an end slice.



• Continuous

De�nes the continuous transport mechanism in the main slice as

� selected

The execution windows present in the child nodes Window_Schedule willhave continuous transportation.

� all

All execution windows of this partition will have continuous transportationby default. This can be overruled by child nodes Window_Schedule

If the attribute is left out no Window_Schedule will have a continuous trans-portation.





• StartDurationSeconds

De�nes the duration of the start slice.

If Start has the value selected, this value is ignored; the values in the Win-

dow_Schedule are used instead.

If Start has the value all, all execution windows will have start slices with thisduration by default. It will be overruled by the value in the present child nodesWindow_Schedule.

If Start has the value period, all Window_Schedulemarked as PartitionPeriodStartin the arinc 653 con�guration will have a start slice with this duration.

If Start is not given this attribute is ignored.


float No N/A N/A

• EndDurationSeconds

De�nes the duration of the end slice.

If End has the value selected, this value is ignored; the values in the Window_Schedulesare used instead.

If End has the value all all execution windows will have end slices with thisduration by default. It will be overruled by the value in the present child nodesWindow_Schedule.

If End has the value period Window_Schedulesmarked as PartitionPeriodStartin the arinc 653 con�guration will have an end slice with this duration.

If End is not given this attribute is ignored.


float No N/A N/A

• Priority

De�nes the priority of the transport process for continuous transportation in allor all selected Window_Schedules.


integer No [0,∞] N/A

• Child Nodes:

� Window_Schedule

The execution windows, the start and end slice and the continuous trans-port are de�ned for.


Window_Schedule No 0..n N/A

Window_Schedule

• WindowIdentifier

De�nes the Window_Schedule in the arinc 653 con�guration, this Window_Sche-dule corresponds to.




integer Yes N/A N/A

• Start

De�nes if the execution window will have a start slice.


boolean No N/A false

• End

De�nes if the execution window will have an end slice.



• Continuous

De�nes if the execution window will have continuous transport.



• StartDurationSeconds

De�nes the duration of the start slice of this execution window. If Start is true,this attribute always overrules the corresponding setting in Transport.


float No N/A N/A

• EndDurationSeconds

De�nes the duration of the end slice of this execution window. If End is true,this attribute always overrules the corresponding setting in Transport.


float No N/A N/A

OutputType Currently, only one value is supported:

• fifo

TransportSlice One of the values:

• period

• selected

• all

PortType Currently, only one value is supported:

• UDP

Logbook

• LogbookName The name of the logbook. It must be the same name of the corre-sponding port in the arinc 653 con�guration.





• NVMName

The logbook corresponding �le name.



• DeviceType

The type of non-volatile memory used. Currently only one type is valid; �le.

• LogbookKey

Shared Memory key used to communicate with the Logbook system partition.



• Startup

7.2 arinc 653 Con�guration

sima uses only a subset of the arinc 653 con�guration. It is not necessary to de�nethose parts of the con�guration that are actually not used. Note that no con�gurationis needed at all for a program in standalone mode without connected ports. Withconnected ports, only the partition and port related nodes are needed.

The relevant parts of the arinc 653 con�guration are:

• ARINC_653_Module

� System_HM_Table Can be left out in the arinc 653 con�guration �le and,instead, added to the sima con�guration �le. Only required with mos.

� Module_HM_Table Can be left out in the arinc 653 con�guration �le and,instead, added to the sima con�guration �le. Only required with mos.

� Partition

∗ Queuing_Port

∗ Sampling_Port

� Module_Schedule Only required with mos.

∗ Partition_Schedule

· Window_Schedule� Partition_HM_Table Can be left out in the arinc 653 con�guration �le

and, instead, added to the sima con�guration �le. Only required with mos.

� Connection_Table

Please refer to the arinc 653 speci�cation for details on the arinc 653 con�guration.



8 Service Reference

8.1 Service Overview

The following sections provide a short reference to the services de�ned by arinc 653and implemented by the sima toolchain. The services are grouped into major cate-gories; these categories:

• Partition Management

• Process Management

• Time Management

• Inter-Partition Communication

• Intra-Partition Communication

• Health Monitor

• Multi Modules Schedule

• Logbook System

• Sampling Port Extensions

• Service Access Points

• Name Services

8.1.1 Partition Management

Partition Initialization Partitions are initialized withWARM_START or COLD-_START. With sima, both initialization modes are the same, there is no persistentdata kept when a partition is re-initialized. Initialization mode corresponds to theexecution of partition entry points. Therefore, by the end of a partition entry point,the partition operating mode should be modi�ed from WARM_START or COLD-_START to NORMAL via SET_PARTITION_MODE service.

Partition Attributes

• IDENTIFIER: Uniquely identi�es a partition.

• PERIOD: De�nes time interval within which the partition must execute. It isde�ned at con�guration �le and used by the partition scheduler and periodicprocesses.

• DURATION: De�nes the execution time of a partition within its period; theamount of time this partition will have the processor control.

• LOCK_LEVEL: De�nes if preemtption is enabled among the partition pro-cesses. This attribute can be modi�ed by the processes within the partition.LOCK_PREEMPTION and UNLOCK_PREEMPTION services are used tomodify this value. When the partition lock level is higher than zero, process re-schedule is disabled within the partition. This condition can only be reversed bythe invocation of UNLOCK_PREEMPTION by the same process that lockedit. These services are described in detail later in this section.



• OPERATING_MODE: Can assume any of the following values:

� WARM_START or COLD_START: is partition initialization mode;

� IDLE: partitions on this mode are not running any process, even withinits execution window;

� NORMAL: for partition runtime mode after initialization, partition pro-cesses are running.

• START_CONDITION: Speci�es the reason for the partition start. It can as-sume any of the values:

� NORMAL_START: indicates a partition normal start;

� PARTITION_RESTART: indicates that the partition has been re-started;

� HM_MODULE_RESTART: indicates the intervention from the systemHealth Monitor to re-start the partition;

� HM_PARTITION_RESTART: indicates the intervention from the parti-tion Health Monitor to re-start the partition;

These attributes comprises the partition status; PARTITION_STATUS_TYPE isan arinc 653 de�ned data structure returned by the service GET_PARTITION-_STATUS. The operating modes of a partition are modi�ed via SET_PARTITION-_MODE service.

• PARTITION_HM_TABLE: De�nes actions to be taken by the Health Monitorwhen an error is raised. These de�nitions must be described through the XMLcon�guration �le loaded at application initialization.

• Partition Communication Requirements: Also speci�ed through the XML con-�guration �le, it determines the connections between di�erent partitions usingspeci�c types of ports.

The transition of a partition state from NORMAL to one of the initialization modes(WARM_START or COLD_START), causes the partition resources to be reset: allthe resources and processes are removed from the partition tables. If this partitionsu�ers a new transition to NORMAL, then the context of this resources and processesare reinitialized.

8.1.2 Process Management

Processes attributes

• NAME: unique string (within a partition) identifying the process

• ENTRY_POINT: address o� the process routine

• STACK_SIZE: size of the stack allocated for the process

• BASE_PRIORITY: the process initial priority

• PERIOD: used by periodic processes only, determines the time interval withinwhich the process is executed. If this �eld is �lled with value INFINITE_TIME-_VALUE it identi�es an aperiodic process



• TIME_CAPACITY: de�nes the time interval within which the process startsand �nish its execution. It is the de�nition of a deadline for the process. Thevalue provided within this �eld is used to schedule a time event at pos TimeManager. On the other hand, processes can be initialized with no deadline byspecifying INFINITE_TIME_VALUE for this �eld. The REPLENISH servicecan postpone the process deadline, increasing its time capacity by telling theTime Manager that the process gained more time for completing execution.But unless REPLENISH is invoked in all of this process executions, the processdeadline is de�ned by TIME_CAPACITY

These attributes comprises the PROCESS_ATTRIBUTE_TYPE, an arinc 653 de-�ned data structure. This structure is input parameter for the service CREATE-_PROCESS and is returned by the service GET_PROCESS_STATUS. The inputattributes for CREATE_PROCESS service are used to allocate the resources requiredby the process and cannot be changed after the process creation.

• CURRENT_PRIORITY: when a process priority is modi�ed, this attributeassumes the new value. Processes can modify its own priority or others priorityvia SET_PRIORITY operation.

• DEADLINE_TIME: specify if the process has a hard or soft deadline. Whenhard deadlines are missed, sima Health Monitor takes remedial actions. Whensoft deadlines are missed, messages are printed to the user but no other actionis taken.

• PROCESS_STATE: can assume any of the values:

� DORMANT: process is not eligible for gaining processor control. It ishas not been started yet (by START service), or has been stopped (viaSTOP/STOP_SELF service).

� READY: process is eligible to run, it will be selected to gain processorcontrol according to its priority.

� RUNNING: only one process can assume this state; the process currentlyrunning which is also the �rts process of the READY queue state.

� WAITING: process is not eligible to gain the processor control because itis waiting for some resource or event or because it must wait for some timeinterval.

Processes state transition Processes state transition are illustrated by Figure28.



Figure 28: arinc 653 Processes State Transition

• DORMANT: All processes are created at the DORMANT state and return toDORMANT when are deactivated. Processes in DORMANT may be moved to:

� READY: When the aperiodic process su�ers a START operation at parti-tion NORMAL mode.

� WAITING: When it is a periodic process being started at NORMAL mode.

� DORMANT: When processes are started at initialization mode.

• WAITING: Processes on WAITING are kept ineligible to run for one or morereasons, they may su�er transitions to:

� READY: When the time interval the process was waiting on elapses (pro-cess is returning from TIMED_WAIT, SUSPEND_SELF, PERIODIC-_WAIT, any of the timed resources service); when the suspended processis resumed; when the process was blocked on a resource that became avail-able; or when an aperiodic process was started at initialization mode andthe partition su�ers a transition to NORMAL.

� DORMANT: When the process is stopped (STOP, STOP_SELF).

• READY: Processes in READY state are eligible to run, they are not in control ofthe processor because some other process has higher priority or the preemptionin the partition is disabled. From this state, a process can su�er a transition to:

� RUNNING: When it is the highest priority process from the READY queueand gains the processor control.

� WAITING: When it blocks on an attempt to acquire a resource; when itcalls a time related service (TIMED_WAIT, SUSEND_SELF, PERIODIC-_WAIT); when it is suspended by another process (SUSPEND);

� DORMANT: When another process stopped it (STOP).

• RUNNING: There is only one process running at a time. The running processmay su�er a transition to:

� READY: When it is preempted by a higher priority process or voluntarilyreleases the processor by asking for re-schedule.

� WAITING: When it requests any service related to time or resourcesthat may be unavailable (by calling TIMED_WAIT, SUSPEND_SELF,PERIODIC_WAIT or any of the resources related service).

� DORMANT: When the process invokes STOP service.

8.1.3 Time Management

The Time Manager maintains references of all processes within the partition (there isone instance of Time Manager within each partition). Whenever the process requiresa time related service; a time_out or a deadline, the Time Manager inserts an entryat its schedule connecting/referencing the process to the point in time in which thisprocess requested the service. Di�erent actions are taken by the Time Manager if theevent scheduled is a time_out or a deadline.

In summary, when a time_out elapses, the Time Manager moves the process fromthe WAITING queue to the READY queue (if all conditions for this transition aresatis�ed). And when a deadline is missed, the Time Manager raises an error to be



handled by the process error handler (when this exists) or to the partition error handler(when there is no process error handler).

All partitions use the same clock; time perception is the same for all the partitions.Time events can be elapsed while a partition is not within its execution window. Theseoccurrences are treated only when the partition gains the processor again.

8.1.4 Partition Resources

Partition resources or intrapartition communication means can be any of these: black-boards, bu�ers, events or semaphores.

Blackboards are simple mechanisms used to publish a message. A message is writtenby one process only at a time but can be read by various processes. The blackboardmaintains only one message available, writing to a blackboard implies in loosing theprevious message. It also does not maintain information about the source of themessage or controls which process can read it. Reading from an empty blackboardmay cause a process to block.

Bu�ers are also used by processes to exchange messages. As opposite to blackboards,bu�ers allow various messages to be stored at a time. The messages are maintained bythe bu�er until they are read, reading a message from the bu�er also means removingit. Processes may block on attempts to write to a full bu�er or to read from an emptyone.

Semaphores are used for controlling the access of processes to shared resources. Thesemaphore centralizes the information about the availability of the processes shared re-sources and controls the concurrency for them. The maximum number of a semaphoreindicates the maximum number of resources available. Whenever a process success-fully acquires a semaphore, it decrements this semaphore counter. When it has �n-ished using the resource (that this semaphore controls), it must signal the semaphore.This will cause the semaphore counter to be incremented again, restoring the resourcecounter, indicating to other processes that there are resources available. Whenever aprocess fails to acquire the semaphore, it may wait for the availability of the resourceor procede execution without it.

Events are also mechanisms for synchronizing processes. An event can assume one oftwo states: up or down. A process can condition its execution to one event state: aWAIT_EVENT service invocation will cause the process to block if the event state isdown. Or will allow the process to continue execution when the event state is up.

8.1.5 Resources and Time outs

Most of arinc 653 resources usage is similliar. Processes can require the resourceusage de�ning speci�c parameters and parameters related to the possibility of beingblocked on attempts to use a resource not available at that moment. When a time outparameter is used it can assume any of this values and behaviour:

• zero: speci�es that the process is not willing to wait for the resource when it isnot available. If the resource is not available, the service request will return anNOT_AVAILABLE return code.

• INFINITE_TIME_VALUE: speci�es that the process will wait until the re-source becomes available.

• any value (higher than zero) within the expected time_out range: speci�es thatthe process will wait at most for this TIME_OUT amount of time. After this, if



the resource is still not available, the process will just give up trying to acquireit, a TIMED_OUT code will be returned.

8.1.6 Interpartition Communications

Both types of ports speci�ed by arinc 653 are supported by sima: sampling ports andqueuing ports. The queuing ports allow the transmission of messages of variable sizes.The sampling ports assume a di�erent kind of data to be transmitted. It supportsmessages of one speci�c size and that have a validity attached to it.

Communication between processes within di�erent partitions is accomplished throughchannels. sima implements channels, using udp ports. From the processes point ofview, messages are written to and read from a message port. The processes sendingand receiving the message do not directly interact.

8.1.7 Health Monitoring

The Health Monitor manages the activation of the process error handler or the par-tition error handler. Process error handlers are optional and created by user code,partition error handlers are mandatory and built-in. The behaviour of the partitionerror handler is described by the de�nition of actions to be taken in the con�guration�le provided to the simulator at initialization.

The process error handler routine must be provided by the user code just like any otherprocess. The creation of the error handler process, however, uses a di�erent service:CREATE_ERROR_HANDLER. The error handler process is stored together withthe other processes within the partition. But it does not use an identi�er visible toother processes. The process error handler is activated by the Health Monitor wheneverthe application raises an error via RAISE_APPLICATION_ERROR service.

The Health Monitor may also activate the process error handler upon an error detec-tion, like a hard deadline miss. Because this process is not mandatory, the HealthMonitor activates the Partition Error Handler when a process error handler is notprovided by the application code.

TBD:

De�ne System States and Error Identi�ers

8.1.8 Multiple Module Schedules

8.1.9 Logbook System

8.1.10 File System

8.1.11 Service Access Points and Name Services

8.2 Service Description

8.2.1 Partition Management

GET_PARTITION_MODE The GET_PARTITION_MODE service returnsa data structure containining the six �rst partition attributes listed above.

SET_PARTITION_MODE The GET_PARTITION_MODE service sets theoperating mode of the currently running partition to one of the OPERATING_MODEs



listed above. The transition of partition OPERATING_MODE is illustrated by thediagram below:

8.2.2 Process Management

GET_PROCESS_STATUS The GET_PROCESS_STATUS service returnsthe process PROCESS_STATUS_TYPE data structure. It requires only the PROCESS-_ID as input parameter and will fail to complete if this identi�er is not valid withinthe partition.

CREATE_PROCESS The CREATE_PROCESS service creates the processwithin the partition at initialization modes (partition COLD_START or WARM-_START modes). The process is created once using the PROCESS_ATTRIBUTE-_TYPE data structure information. These attributes cannot be changed during thelife time of a process. Once the process is successfuly created, this service returns anidenti�er for the process (unique within its partition). This service will fail to com-plete if there is no memory enougth for the process creation or if a process with thesame name has already been created. Values for the process time capacity, stack size,period and base priority must also be within a pre-de�ned range.

When a process is created, it is put in the process scheduler DORMANT state queue.

SET_PRIORITY The SET_PRIORITY service modi�es the process CURRENT-_PRIORITY attribute value. This service fails if the process identi�er provided isinvalid or if the priority parameter is out of range. When a priority is modi�ed for aprocess in a waiting queue (ordered by priority), the position of the process will changewhen another process is added to the queue (That means that if no other process isadded to this queue, the process remain in the same position).

SUSPEND_SELF The SUSPEND_SELF service moves the calling process tothe process scheduler WAITING state queue and mark the process as SELF_SUSPENDED.This service uses a TIME_OUT parameter that can be set to INFINITE_TIME-_VALUE or any other value within a range (of possible time interval). When a validvalue is provided, the process will remain in the WAITING queue until it is removedby a RESUME service or the TIME_OUT interval expires. In the last case, the timemanager is responsible for moving the process to the READY state. A suspendedprocess may also be stopped (via STOP service), which will cause the process to bemoved from the WAITING to the DORMANT state.

SUSPEND The SUSPEND service also moves a process to the process schedulerWAITING state queue. However, it is used to suspend another process (the processwhose identi�er is given as input). The suspended process is moved to the WAIT-ING state and marked as SUSPENDED. As this operation uses no time related inputparameter, the process is suspended untill a RESUME operation is issued for it. Pro-cesses that are waiting for resources (within a resource waiting queue) can also besuspended. In this case, as it is already at the process scheduler WAITING queue, itwill only be marked as SUSPENDED.

STOP_SELF The STOP_SELF service moves the calling process to the processscheduler DORMANT state queue. This service also cause the process to release allthe resources it was currently using (semaphores or events) and leave other resourceswaiting queues if that is the case. The way sima implements this behaviour is throughreferences to these resources kept the the process itself.



STOP The STOP service is used to stop another process. It will move the processreferenced by the process identi�er input parameter to the DORMANT state and causeall the resources used by this process to be released.

Processes that are stopped, by STOP_SELF or STOP are put in DORMANT stateand can only become eligible to run again via a START/DELAYED_START opera-tion.

START The START service cause a created process be moved from the DOR-MANT state to the READY or WAITING state. If this process is created as a periodicprocess or if it has a deadline (or both of them), a reference for this process will alsobe registered by the time manager. The Time Manager is responsible for signaling theprocess deadline miss occurrence.

DELAYED_START The DELAYED_START service is similar to START ser-vice. But it uses a DELAY parameter as input, specifying a time interval in which thestarted process remains at the WAITING state until it can actually start.

LOCK_PREEMPTION The LOCK_PREEMPTION service allow a processto disabled process re-scheduling within its partition. This operation will set thecurrent partition LOCK_LEVEL attribute and no other process will be able to gainthe processor control. The running process will then only loose the processor if theerror handler process interfere with it or when it enables the re-scheduling again viaUNLOCK_PREEMPTION service.

UNLOCK_PREEMPTION The UNLOCK_PREEMPTION service allow aprocess to enabled process re-scheduling within its partition. The only processes thatcan successfuly invoke this service is the process that has previously locked the parti-tion preemption or the error handler process.

GET_MY_ID and GET_PROCESS_ID Both these services return a pro-cess identi�er. While GET_PROCESS_ID requires a process name as an input para-menter, GET_MY_ID returns the calling process identi�er within the partition.

8.2.3 Time Management

TIMED_WAIT The TIMED_WAIT service allows the calling process to bemoved to the process scheduler WAITING queue for a given time interval; time_out(this is provided as the service input paramenter). By the end of this time_out inter-val, the process is moved to READY queue (unless it has been suspended).

PERIODIC_WAIT The PERIODIC_WAIT service is used only by periodicprocesses. Its invocation causes the process to remain in WAITING state until itsnext activation time. This service uses the process attributes to calculate the correcttime to make the process sleeps, no input parameter is required.

GET_TIME The GET_TIME service returns the current time. Time is uniquefor all partitions, although a deadline miss may not be raised exactly when it reallyoccurs, the partition is always aware of the time spent while it was not in control ofthe processor.



REPLENISH The REPLENISH service is for exclusive use of processes with apre-de�ned deadline time. The deadline of a process is speci�ed by the time intervalvalue de�ned at the process creation via the attribute TIME_CAPACITY. The RE-PLENISH service can postpone this deadline by adding a BUDGET (time interval)input parameter to the process time capacity. The BUDGET amount of time cannotcause the process time capacity to exceed its period. When this service is invoked theBUDGET time interval is added to the current time and the resulting time point isde�ned as a new deadline for the process.

8.2.4 Intrapartition Communication - Bu�er

CREATE_BUFFER The CREATE_BUFFER service enable the creation ofa bu�er within the partition. The input parameter for this service are: the bu�ername, that must be unique within the partition; the bu�er capacity: that concernsthe size of the messages that can be written to the bu�er and the maximum number ofmessages the bu�er can store; and the queuing discipline, the order in which processesare blocked by the bu�er operations are ordered. The newly created bu�er identi�eris returned if this resource was successfuly created and a return code is also an outputparameter for the service.

SEND_BUFFER The SEND_BUFFER service allows a process to send a mes-sage to another process. The destination of the message is not provided as input forthe service, the process sending the message only need to access the bu�er itself. Mes-sages are put in the bu�er and removed from it according to �rst-in-�rst-out policy.These messages can have variable size but are limited to the maximum size of messagede�ned at bu�er creation (CREATE_BUFFER).

This service can be used as a blocking invocation. Input parameters include a TIME_OUTvalue indicating how long the process is willing to wait in case the bu�er is not avail-able (bu�er is full). The TIME_OUT can be set to zero, indicating the process willnot block if the bu�er is full (the process will only receive a NOT_AVAILABLE returncode). When this value is set to the INFINITE_TIME_VALUE (-1), the process iskept waiting until a place in the bu�er becomes free for the message to be placed in it.Or it can be set to any time out interval, in this case, the process will remain blockedby the resource until a place for its message becomes available in the bu�er or untilits time out expires, whichever occurs �rst.

RECEIVE_BUFFER The RECEIVE_BUFFER service allows a process to re-ceive a message from the bu�er referenced in the service input paramenter BUFFER_ID.The message sender is not known by the receiving process. The message received isthe �rst message pointed by the bu�er to be removed.

This service can be used as a blocking invocation. Input parameters include a TIME_OUTvalue indicating how long the process is willing to wait in case the message is not avail-able (bu�er is empty). The TIME_OUT can be set to zero, indicating the process willnot block if the bu�er is empty (the process will only receive a NOT_AVAILABLEreturn code). When this value is set to the INFINITE_TIME_VALUE (-1), the pro-cess is kept in WAITING state until a message becomes available for it to receive. Orit can be set to any time out interval, in this case, the process will remain blocked bythe resource until a message is available or until its time out expires, whichever occurs�rst.

GET_BUFFER_ID The GET_BUFFER_ID service provides a bu�er identi-�er within the partition given its name.



GET_BUFFER_STATUS The GET_BUFFER_ID service provides a buffercurrent status given its identi�er. The bu�er status contains information like: bu�ercapacity, number of messages currently stored in the bu�er, the maximum size of themessages that can be stored by the bu�er and the number of processes that are waitingto use this resource.

8.2.5 Intrapartition Communication - Blackboard

CREATE_BLACKBOARD The CREATE_BLACKBOARD service enablethe creation of a blackboard within the partition. The input parameter for this serviceare: the blackboard name, that must be unique within the partition; the blackboardcapacity: concerns the size of the message that can be written to the blackboard; anda queuing discipline, the order in which processes are blocked by the blackboard onattempts to read from an empty blackboard. The newly created blackboard identi�eris returned if this resource was successfuly created and a return code is also an outputparameter for the service.

READ_BLACKBOARD The READ_BLACKBOARD service allows a pro-cess to read a message displayed in the blackboard referenced in the service inputparamenter BLACKBOARD_ID. This service copies the message from the blackboardto the process memory space, it does not remove the message.

This service can be used as a blocking invocation. Input parameters include a TIME_OUTvalue indicating how long the process is willing to wait in case a message is not availablein the blackboard. The TIME_OUT can be set to zero, indicating the process will notblock if the blackboard is empty (the process will only receive a NOT_AVAILABLEreturn code). When this value is set to the INFINITE_TIME_VALUE (-1), the pro-cess is kept in WAITING state until a message becomes available for it to read. Or itcan be set to any time out interval, in this case, the process will remain blocked by theblackboard until a message is available or until its time out expires, whichever occurs�rst.

DISPLAY_BLACKBOARD The DISPLAY_BLACKBOARD service allowsa process to display a message in the blackboard. This service will cause a previouslydisplayed message to be overwritten. The blackboard can only store one message ata time so whenever a new message is displayed, the older message is lost. Therefore,this service do not block any process. At the execution of this service, if there wasany process blocked on attempts to read from the empty blackboard, the processes arereleased (they read the displayed message).

CLEAR_BLACKBOARD The CLEAR_BLACKBOARD service allows a pro-cess to erase whatever message is currently displayed at the blackboard. Attempts toerase an already empty blackboard has no e�ect, this is also a non-blocking service.

GET_BLACKBOARD_ID The GET_BLACKBOARD_ID service providesa blackboard identi�er within the partition given its name.

GET_BLACKBOARD_STATUS The GET_BLACKBOARD_STATUS ser-vice provides a blackboard current status given its identi�er. The blackboard statusindicates if the blackboard is empty or not, how many processes are blocked on it andthe size of the message it is currently displaying.



8.2.6 Intrapartition Communication - Event

CREATE_EVENT The CREATE_EVENT service enable the creation of anevent within the partition given its name, that must be unique within the partition.The newly created blackboard identi�er is returned if this event was successfuly createdand a return code is also an output parameter for the service.

SET_EVENT The SET_EVENT service allows a process to signal the ocurrenceof the event (set the event state to UP). If there were processes waiting for the occur-rence of this event, these processes (all the waiting processes) are released (at once)and can continue execution. If the state of the event was already UP, the serviceinvocation has no e�ect, a code indicating such condition is returned.

RESET_EVENT The RESET_EVENT service allows a process to change theevent state to DOWN. If the event state was already down, the service has no e�ect.

WAIT_EVENT The WAIT_EVENT service cause a process to be blocked onan event that is at DOWN state. If the event state is UP, the service has no e�ect.

GET_EVENT_ID The GET_EVENT_ID service provides an event identi�erwithin the partition given its name.

GET_EVENT_STATUS The GET_EVENT_STATUS service provides anevent current status given its identi�er. The event status indicates the state of theevent (UP or DOWN) and how many processes are blocked on it.

8.2.7 Intrapartition Communication - Semaphore

CREATE_SEMAPHORE The CREATE_SEMAPHORE service enable thecreation of a semaphore within the partition. The input parameter for this serviceare: the semaphore name, that must be unique within the partition; the semaphorecurrent value (semaphore is always initialized with its maximum value); the semaphoremaximum value and a queuing discipline, the order in which processes are blocked bythe semaphore. The newly created semaphore identi�er is returned if this resourcewas successfuly created. A return code is also an output parameter for the service.

WAIT_SEMAPHORE The WAIT_SEMAPHORE service allows a process toacquire a semaphore, or acquire a resource the semaphore is controlling access to.Upon this service invocation, the semaphore counter is decremented in case it has notreached zero already and the process proceeds execution.

The semaphore counter can never assume negative values, the counter represents thenumber of available resources. When zero is already reached, processes block whenattempting to acquire the semaphore. This service may or may not be used as ablocking service. Input parameters include a TIME_OUT value indicating how longthe process is willing to wait in case the semaphore is not available (counter value iszero). The TIME_OUT can be set to zero, indicating the process will not block if thesemaphore counter is zero (the process will only receive a NOT_AVAILABLE returncode). When this value is set to the INFINITE_TIME_VALUE (-1), the process willwait untill the semaphore counter is incremented. The TIME_OUT can also assumeany time interval value, in this case, the process will remain blocked by the semaphoreuntil another process increments its value or until its time out expires, whicheveroccurs �rst.



SIGNAL_SEMAPHORE The SIGNAL_SEMAPHORE service allows a pro-cess to release a semaphore. The invocation of this service cause the semaphore counterto be incremented. It will also release processes that were blocked on it.

This service cannot block a process, if a process only acquired one semaphore, it canonly release the semaphore once.

GET_SEMAPHORE_ID The GET_SEMAPHORE_ID service provides asemaphore identi�er within the partition given its name.

GET_SEMAPHORE_STATUS The GET_SEMAPHORE_STATUS serviceprovides the semaphore current status given its identi�er. The semaphore status indi-cates: the semaphore maximum value, current value and the number of processes thatare currently blocked on this semaphore.

8.2.8 Interpartition Communication - Sampling Port

CREATE_SAMPLING_PORT The CREATE_SAMPLING_PORT serviceallows the creation of a sampling port within a partition. The input parameters forthis services are: the port name, the maximum number of messages supported by theport, the maximum size of the messages transmited through the port, the queuing dis-cipline for processes blocked by the port, and the port direction. Upon the successfulcreation of the sampling port, the service returns an identi�er for it.

Wether the port is a source of messages or a destination of messages is prede�ned bythe application con�guration �les.

READ_SAMPLING_MESSAGE The READ_SAMPLING_MESSAGE ser-vice allows a process to read a message from a sampling port. Messages read are im-mediately removed from the port channel and cannot be accessed by another process.

This service can be used as a blocking invocation. Input parameters include a TIME_OUTvalue indicating how long the process is willing to wait in case there is no mes-sage available in the channel to be read. The TIME_OUT can be set to zero,indicating the process will not block if the channel is empty(the process will onlyreceive a NOT_AVAILABLE return code). When this value is set to the INFI-NITE_TIME_VALUE (-1), the process is kept in WAITING state until a messagebecomes available for it. Or it can be set to any time out interval, in this case, theprocess will remain blocked by the port until a message is available or until its timeout expires, whichever occurs �rst.

The READ_SAMPLING_MESSAGE service returns an validity output that indicateswhether the age of the message is consistent with the required refresh rate attributeof the port (de�ned at the port creation).

WRITE_SAMPLING_MESSAGE TheWRITE_SAMPLING_MESSAGEservice request is used to write a message in the speci�ed sampling port. Only onemessage can be sent at a time, so the writing of a message overwrites the previous one.

This service can be used as a blocking invocation. Input parameters include a TIME_OUTvalue indicating how long the process is willing to wait in case there is no space avail-able in the channel to write the message. The TIME_OUT can be set to zero,indicating the process will not block if the channel is full (the process will onlyreceive a NOT_AVAILABLE return code). When this value is set to the INFI-NITE_TIME_VALUE (-1), the process is kept in WAITING state until a place forthe message becomes available. Or it can be set to any time out interval, in this case,



the process will remain blocked by the port until a space for the message is availableor until its time out expires, whichever occurs �rst.

GET_SAMPLING_PORT_ID The GET_SAMPLING_PORT_ID serviceprovides a sampling port identi�er within the partition given its name.

GET_SAMPLING_PORT_STATUS The GET_SAMPLING_PORT_STA-TUS service provides the sampling por current status given its identi�er. The samplingstatus indicates:

8.2.9 Interpartition Communication - Queuing Port

CREATE_QUEUING_PORT The CREATE_QUEUING_PORT service al-lows the creation of a queuing port within a partition. The input parameters for thisservices are: the port name, the size of the messages transmited through the port,the queuing discipline for processes blocked by the port, the port refresh time; whichindicates the maximum age of a message and the port direction. Upon the successfulcreation of the queuing port, the service returns an identi�er for it.

Wether the port is a source of messages or a destination of messages is prede�ned bythe application con�guration �les.

RECEIVE_QUEUING_MESSAGE The RECEIVE_QUEUING_MESSA-GE service is used to receive a message from the queuing port speci�ed by its identi�er.Messages read are immediately removed from the port channel and cannot be accessedby another process.

This service can be used as a blocking invocation. Input parameters include a TIME_OUTvalue indicating how long the process is willing to wait in case there is messageavailable in the channel to be received. The TIME_OUT can be set to zero, in-dicating the process will not block if the channel is empty (the process will onlyreceive a NOT_AVAILABLE return code). When this value is set to the INFI-NITE_TIME_VALUE (-1), the process is kept in WAITING state until a place forthe message becomes available for it. Or it can be set to any time out interval, in thiscase, the process will remain blocked by the port until a message is available or untilits time out expires, whichever occurs �rst.

SEND_QUEUING_MESSAGE The SEND_QUEUING_MESSAGE servicerequest is used to send a message in the queuing port speci�ed by its identi�er.

This service can be used as a blocking invocation. Input parameters include a TIME_OUTvalue indicating how long the process is willing to wait in case there is no spaceavailable in the channel to send the message. The TIME_OUT can be set to zero,indicating the process will not block if the channel is full (the process will onlyreceive a NOT_AVAILABLE return code). When this value is set to the INFI-NITE_TIME_VALUE (-1), the process is kept in WAITING state until a place forthe message becomes available for it. Or it can be set to any time out interval, inthis case, the process will remain blocked by the port until a space for the message isavailable or until its time out expires, whichever occurs �rst.

GET_QUEUING_PORT_ID The GET_QUEUING_PORT_STATUS ser-vice provides the queuing port identi�er within a partition given its name.



GET_QUEUING_PORT_STATUS The GET_QUEUING_PORT_STA-TUS service provides the queuing port current status given its identi�er. The queuingport status indicates: the number of messages currently within the message channel,the maximum number of message that can be within the port channel, the size ofthe messages that can be transmitted through the channel, the port direction and thenumber of processes blocked on this port.

8.2.10 Health Monitor

REPORT_APPLICATION_MESSAGE The REPORT_APPLICATION-_MESSAGE service allows application processes to report an error. The message,provided as input for this service, can be logged or printed. Because this service donot use an error code, there is no prede�ned actions for a process error handler orpartition error handler to take. It is used, for instance, by soft deadline processes tolog a deadline miss or application speci�c errors.

CREATE_ERROR_HANDLER The CREATE_ERROR_HANDLER ser-vice enable the creation of a process error handler for the partition given this processentry point. The process error handler code is user code as well as processes. However,the process error handler is not activated together with all the processes within thepartition. It will only execute when activated by the Health Monitor.

RAISE_APPLICATION_ERROR The RAISE_APPLICATION_ERRORservice is used by the application to register the occurrence of an error and activatethe Health Monitor respective actions. The error information is registered in an errorstatus format (arinc 653 speci�ed data structure). This service causes the activa-tion of the partition process error handler, when it was created or the activation or apartiiton error handler otherwise.

GET_ERROR_STATUS The GET_ERROR_STATUS service is used by theprocess error handler to acquire information about an error registered by the appli-cation through RAISE_APPLICATION_ERROR service. The error status containsthe error code, the message error, the message length, the process (in error) identi�erand the address of the failure occurrence.

8.2.11 Multiple Module Schedules

8.2.12 Logbook System

8.2.13 File System

8.2.14 Sampling Port Extensions

8.2.15 Service Access Points

8.2.16 Name Services


Documents

sima Command Line Tools Application Development and … · Simulated Integrated Modular vionicsA ( sima R) is an execution environment, pro- ... Section 7 provides a reference to