Users Guide

PXROS-HR

Version 1.1

HighTec EDV-Systeme GmbH Phone: +49 681-9 26 13-16

Feldmannstrae 98 Email: [email protected]
D-66119 Saarbrcken http://www.hightec-rt.com
Contents

I Overview 4
1 Introduction 5
1.1 What is PXROS-HR? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 Why an operating system? . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 What is a realtime operating system . . . . . . . . . . . . . . . . . . . . . 5
1.4 Special features of PXROS-HR . . . . . . . . . . . . . . . . . . . . . . . . 6

2 Special characteristics of PXROS-HR 8

3 PXROS-HR Architecture 10
3.1 Overview - Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2 Functional units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2.1 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2.2 Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.3.1 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3.2 MemoryClass object . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3.3 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.3.4 Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.3.5 Objectpools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.3.6 Interrupt objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.3.7 Objects for realising timer functionality . . . . . . . . . . . . . . . . 17
3.4 Inter-process communication . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.4.1 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.4.2 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.5 Safety characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.5.1 Hardware memory protection . . . . . . . . . . . . . . . . . . . . . 20
3.5.2 Memory protection and encapsulation . . . . . . . . . . . . . . . . . 20
3.5.3 Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.5.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4 Services of the system 24

4.1 Services of the core systems . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.1.1 PxSysInfo services . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.1.2 Nameserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.1.3 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.1.4 PXROS-HR Service Task . . . . . . . . . . . . . . . . . . . . . . . . 25
4.1.5 System monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.2 Additional services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.2.1 TCP/IP stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.2.2 PXfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Users Guide V1.1 Contents

4.2.3 PXview Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

II Usersguide 26
5 Summary 27

6 Layout of a programming interface 28

7 Programming the core system 29

7.1 Basic concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.2 The first simple application . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.2.1 Initialising PXROS-HR . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.2.2 Startup-initialisation . . . . . . . . . . . . . . . . . . . . . . . . . . 33
7.2.3 Layout and initialisation of a Task . . . . . . . . . . . . . . . . . . 34
7.2.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.3 Utilising system services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.3.1 Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.3.2 Blocking and non-blocking system services . . . . . . . . . . . . . . 39
7.3.3 System calls in Tasks and Handlers . . . . . . . . . . . . . . . . . . 40
7.4 Object management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
7.4.1 Object pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
7.4.2 Requesting PXROS-Objekten . . . . . . . . . . . . . . . . . . . . . 40
7.5 Memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
7.6 Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.6.1 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.6.2 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.7 Interrupt and Trap Handler . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.7.1 Global Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.7.2 Local Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
7.7.3 Context Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.7.4 Trap handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.8 Timer functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.8.1 Basic timer functionality . . . . . . . . . . . . . . . . . . . . . . . . 55
7.8.2 Delay Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.8.3 Timeout objects and periodical timers . . . . . . . . . . . . . . . . 56
7.9 Access to peripherals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.9.1 Access in Usermode1 . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.9.2 Access via system calls . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.10 The abort mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

8 Further information 60
8.1 PxSysInfo services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
8.2 The Nameserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
8.3 Reloading Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
8.4 PXROS-HR Service Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
8.5 Event logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

HighTec EDV-Systeme GmbH 2

Users Guide V1.1 Contents

8.5.1 The internal trace mechanism . . . . . . . . . . . . . . . . . . . . . 64

8.5.2 PxView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

III Appendix 65
A Example code 66
A.1 For starters: a simple application . . . . . . . . . . . . . . . . . . . . . . . 66
A.2 Data exchange between Handler and Task . . . . . . . . . . . . . . . . . . 70
A.3 Messagepools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
A.3.1 Creating a Messagepool . . . . . . . . . . . . . . . . . . . . . . . . 72
A.3.2 Deleting a Messagepool . . . . . . . . . . . . . . . . . . . . . . . . . 73

HighTec EDV-Systeme GmbH 3

 Part I

Overview
1 Introduction
The following document describes the features and application of the operating system
PXROS-HR. It is subdivided into two parts:
The first part provides a general outline and describes the philosophy, special character-
istics and architecture of PXROS-HR.
The second part explains in depth the practical application and programming of the
system; examples show how a PXROS-HR application is constructed.

1.1 What is PXROS-HR?

PXROS-HR (Portable eXtendible Realtime Operating System - High Reliability) is a
realtime operating system for embedded systems. PXROS-HR is portable and extendible
with a main emphasis on runtime safety.
Portability is restricted to processor architectures providing memory protection mecha-
nisms via a Memory Protection Unit (MPU), which makes it possible to protect memory
areas of arbitrarily small size.

1.2 Why an operating system?

An operating system is an instrument for managing the resources of a system. It helps
reduce the complexity of application development and avoids the necessity of performing
standard tasks, such as memory management, over and over again, thus reducing error
probability and speeding up the development process.
Another advantage of an operating system is the easy portability of an application: the op-
erating system skips hardware specific characteristics and provides standardised interfaces
for each platform.
The basic task of an operating system is to manage the hardware resources and provide
them to the application software. In essence, this means memory and process management.
Furthermore, an operating system can provide interfaces to other services, e.g. file system
or network services.

1.3 What is a realtime operating system

A realtime operating system is not only expected to perform a calculation process cor-
rectly, but also to provide the result of said calculation in due time, meaning within a
defined period of time.
Hard realtime means it is absolutely necessary to keep all time limits. If only one of
the defined time limits is exceeded, this will cause a unusable result (see Figure 1.1 on
page 6).
Users Guide V1.1 1.4 Special features of PXROS-HR

Figure 1.1: Hard realtime

Soft realtime means a time limit may be exceeded in individual cases without causing
unusable results.
A realtime operating system is characterised by the fact that it guarantees realtime con-
ditions on operating system level. This usually means providing mechanisms that allow
the application software to react to (external) events in time.
Examples:
The process of recording, processing and transferring audio data has to be performed
within certain time limits. If these limits are exceeded from time to time, minor distur-
bances (pops) within the audio stream will be the result, which have no negative effects.
This is an example for a soft realtime requirement.
The process of reading and analysing a measured signal, e.g. in a motor control, and the
reaction to this signal has to be performed within a certain time period. If this is not the
case, disruptions might occur or the motor might break down. This is an example for a
hard realtime requirement.

1.4 Special features of PXROS-HR

PXROS-HR is a multi-tasking operating system with hard realtime characteristics. There
are several processes, called Tasks, which run in a quasi-parallel way. Apart from these,
there are Handlers which are of higher priority, which react to hardware or software
interrupts.
Since all the program components, i.e. Tasks and Handlers, share the same CPU, the avail-
able processing time has to be shared (= scheduling). This task is fulfilled by PXROS-HR.
Priorities are assigned to the individual parts of the program, activating or deactivating
these parts whenever certain events (e.g. receiving a message) occur.
In comparison to other realtime operating systems, PXROS-HR has some special features,
such as:
Hardware-assisted memory protection by a Memory Protection Unit (MPU)
Permission concept for Tasks
Object-based architecture

HighTec EDV-Systeme GmbH 6

Users Guide V1.1 1.4 Special features of PXROS-HR

No interrupt locks within the kernel

Encapsulated Tasks, assisted by hardware memory protection
Possibilty of reloading and debugging Tasks during runtime
Message-based data interchange between Tasks
These special features are due to the fact that PXROS-HR attaches great importance to
safety. Runtime errors during development can be avoided by clear semantics and structur-
ing of the application software. Errors, particularly erroneous memory access operations,
can be detected during runtime and be prevented from having wide-ranging effects.

Note:
Hardware memory protection prevents error propagation throughout
the system. Hardware memory protection (MPU) is handled by the
operating system.

HighTec EDV-Systeme GmbH 7

2 Special characteristics of PXROS-HR
It has already been mentioned that PXPROS-HR has some special characteristics distsin-
guishing it from other operating systems. These features will be described below.
Hardware-based memory protection: PXROS-HR uses the memory protection mecha-
nisms of the hardware to seal off the memory areas of the individual tasks from each
other. This means, each Task has a certain amount of memory allocated and if it
tries to reach out of this area, this access violation is detected by the MPU, and a
trap is triggered.
Permission concepts for Tasks: PXROS-HR arranges to grant or deny certain rights to
the Tasks. These include, for example, access rights to the operating systems or to
hardware resources (see section 3.5 on page 20).
Object-based system architecture: All the elements of the operating system are per-
ceived as objects, such as Message objects or Task objects.
No interrupt locks: Whereas it is common practice with other operating systems to lock
interrupts during scheduling, PXROS-HR does without interrupt locks. This means,
interrupts can be reacted to without any latencies.
Message-based data interchange: Data are exchanged between Tasks via Message ob-
jects. This method has the advantage of making additional synchronisation mecha-
nisms, such as semaphors, redundant.
Encapsulation: The concept of encapsulation arises from the object-based approach in
connection with hardware-assisted memory protection: a Task is perceived as a self-
contained capsule, which is sealed off from the exterior world. Interaction with the
exterior world can only be facilitated via a well-defined, narrow interface (Message
objects). Accidental interference, e.g. by misrouted access operations by pointers
is prevented by the hardware. An overall system consists of several such capsules.
Loose connections within the system increase the manageability of complex systems
considerably, while absence of reaction is ensured.
Realoading tasks: Based on the concept of encapsulation PXROS-HR makes it possible
to load and unload new Tasks during system runtime in the same way as applications
are started and finished on the operating system of a personal computer.
Debugging the running system: PXROS-HR makes it possible to stop individual Tasks
within a running system and to debug these Tasks while the overall system continues
to run.
Note:
Under PXROS-HR Tasks can be perceived as running each on an
individual controller.
Difference between system Tasks and application Tasks Due to the permission con-
cepts it is possible to distinguish between system Tasks and application Tasks. Sys-
Users Guide V1.1

tem Tasks, which usually have high privileges, provide basic services and can also
provide important application functionlaities. They form a system platform similar
to the operating system of a personal computer. Application Tasks are potentially
error-prone (e.g. supplied modules) and thus have lower privileges. These Tasks
usually implement application-specific functionalities rather than system function-
alities. Application Tasks can also be reloaded.
Note:
The basic system also consists of individual capsules on Task level
with different rights (see Figure 3.2 on page 11).

Microkernel: PXROS-HR contains a microkernel, i.e. only the basic functionalities of the
operating system are implemented in the kernel. Additional functionalities, such as
the TCP/IP stack or file system, are realised in the form of separate modules running
as application Tasks.

HighTec EDV-Systeme GmbH 9

3 PXROS-HR Architecture
The following chapter will explain the components and mechanisms used for building up
a PXROS-HR system.

3.1 Overview - Architecture

The architecture of PXROS-HR is object-based, i.e. all the elements of a PXROS-HR
system are regarded as objects. Objects can, themselves, contain other objects or be
assigned to other objects. (see Figure 3.1 on page 10.

Figure 3.1: Object relations

The characteristics of the PXROS-HR architecture make it possible to create a basic

PXROS-HR system, which can provide basic services. This basic system can be extended
by loading application Tasks.
Users Guide V1.1 3.1 Overview - Architecture

Figure 3.2: PXROS-HR System

HighTec EDV-Systeme GmbH 11

Users Guide V1.1 3.2 Functional units

3.2 Functional units

Functional units are elements of the system that contain executable code and represent
each one control flow path. In this context, a differentiation is made between Tasks and
Handlers, as described below.

3.2.1 Tasks
Tasks are the basic elements of a PXROS-HR system. Tasks represent parallel processing
within a software. They are prioritised among each other, yet never of higher priority than
the Handlers.
Tasks run in a quasi-parallel way; however, since there is only one processor physically,
the Tasks have assigned their computing time by the operating system. In practice, this
means that if a Task is willing to run and has a higher priority than the current Task, it
will replace the current Task.

Note:
A Task of equal priority is not supplanted. Exception: if timeslicing
is activated, this means, as soon as its timeslice has expired, the Task
can be supplanted by one of equal priority.

A Task can have any one of the following four states:

waiting the Task waits for an event to wake it, e.g. the arrival of a message
ready the Task has been woken and is now willing to run, but it does not have the highest
priority of all the Tasks willing to run
active if a Task is ready and in possession of the highest priority (e.g. because a Task of
higher priority has changed into the waiting state), it becomes active and is then in
possession of the processor
suspended a Task was suspended by another Task, meaning it does not become active,
even if it were ready and in possession of the highest priority

HighTec EDV-Systeme GmbH 12

Users Guide V1.1 3.2 Functional units

Figure 3.3: Task states

PXROS-HR uses a permission concept for Tasks, i.e. Tasks have to be authorised in order
to access system resources. These types of permission are called privileges (hardware-
based) or access rights (based on the operating system) (see section 3.5 on page 20).

Note:
Under PXROS-HR it is possible to reload Tasks into the basic system
during runtime.

3.2.2 Handlers
Handlers are functions that are called whenever a hardware or software interrupt occurs.
Handlers have a higher priority than any Task.
To speed up the processing of a Handler or to avoid blocking, Handlers have a restricted
access to PXROS-HR system services.
There are two types of Handlers: local Handlers, which are assigned to certain Tasks, and
global Handlers.

3.2.2.1 Global Handlers

Global Handlers, also called fast Handlers, work on interrupt level, meaning these are the
fastest and have the highest priority within the system. Global Handlers must be processed
as quick as possible since otherwise the processing of interrupts can be delayed. Global
Handlers are prioritised among each other; a handler of higher priority can interrupt one
of lower priority.
Global Handlers have all-encompassing permissions.
To install a global Handler, a Task has to have the appropriate permission.
The application of global Handlers can be possible, for example, to realise equidistant
sampling.

HighTec EDV-Systeme GmbH 13

Users Guide V1.1 3.3 Objects

3.2.2.2 Context Handlers

A context Handler is assigned to the Task by which it was installed.

Note:
A context Handler is executed in the context of the creating Task and
has access to the address space of this Task.

To install a local Handler, a Task has to have the appropriate permission. The installed
Handler will then have the same rights as the creating Task.

3.2.2.3 Local Handlers

A local Handler is assigned to the Task by which it was installed.

Note:
A local Handler is executed in the context of the creating Task and
has access to the address space of this Task.

Local Handlers have lower priority than global Handlers, and higher priority than Tasks.
To install a local Handler, a Task has to have the appropriate permission. The installed
Handler will then have the same rights as the creating Task.

Figure 3.4: Distribution of Priorities

3.3 Objects
All the elements of PXROS-HR are regarded as objects. There are two basic types of
objects: generic objects, which belong to an abstract base class and do not implement
any functionality, and specific objects, which are derived.

HighTec EDV-Systeme GmbH 14

Users Guide V1.1 3.3 Objects

Figure 3.5: Object hierarchy

3.3.1 Tasks
Task objects are used for modelling PXROS-HR processes, the so-called Tasks, with their
properties such as priority, stack size, protected memory assigned, etc. (see also subsec-
tion 3.2.1 on page 12).

Figure 3.6: Components of a Task object

3.3.2 MemoryClass object

A MemoryClass object represents a memory class: the available memory can be separated
into several disjoint blocks, the so-called memory classes. Tasks can be either granted
exclusive access to these memory classes, or several Tasks can share a memory class.

HighTec EDV-Systeme GmbH 15

Users Guide V1.1 3.3 Objects

When using several memory classes, Tasks can have different types of memory assigned
(slow memory / fast memory). Furthermore, by assigning a memory class exclusively to
one Task, memory shortage during runtime can be avoided in this Task, which would
otherwise occur if another Task utilises all the available memory.

3.3.3 Messages
Messages are objects, which are used by Tasks to exchange data. They also serve for
synchronising Tasks, since a sender Task can wait for a recipient Task to release a Message.
The content of a Message is not copied; a Message object is given a portion of memory
belonging to the owner of the Message. After sending the Message, this memory portion
changes into the possession of the recipient where it remains until the recipient releases,
forwards or returns it.

Figure 3.7: Access to the memory area of a Message

See subsubsection 3.3.4.2 on page 17.

3.3.4 Mailboxes
Mailboxes are the communication terminals for Message exchange. A Task sends a Message
object to a mailbox, while a recipient can wait for arriving Messages at this mailbox.

Note:
Mailboxes can contain an arbitrary number of Message objects.

3.3.4.1 Private Mailboxes

Private mailboxes are a special feature. In general, mailboxes can be made available for
any Task, yet each Task has its own private mailbox, which is unavailable for other Tasks.
The usual case of inter-Task-communication is an exchange of Messages between private
mailboxes.

HighTec EDV-Systeme GmbH 16

Users Guide V1.1 3.3 Objects

3.3.4.2 Messagepools

Messagepools are another special feature. They are storehouses for Message objects
created beforehand. This means, Messages are created during initialisation and stored in
a Messagepool. This procedure has several advantages:
1. Creating Messages during runtime can be avoided; the necessary Messages can be
extracted from the Messagepool
2. There is no shortage during runtime, e.g. because at a certain time there are no
more objects available.
This shows the usefulness of the feature that several Tasks can have access to the same
mailbox.

3.3.4.3 Mailboxhandler

Handlers can be defined for mailboxes. If a Handler was installed at a mailbox, then this
Handler is called whenever a Message is sent to this mailbox.
This feature is of particular usefulness if a Task wishes to receive Messages from several
mailboxes.

3.3.5 Objectpools
Object pools are used for storing objects until they are needed. There is a standard system
pool, where all objects can be found at the time of initialisation. Other object pools can
be created and filled with objects. These pools can be assigned to individual Tasks in
order to avoid object shortages during runtime, as they would occur with shared object
pools (see subsection 7.4.1 on page 40).

3.3.6 Interrupt objects

Interrupt objects represent access events to interrupt Handler routines. They can be used
for signing on/off interrupt Handlers with the operating system.

3.3.7 Objects for realising timer functionality

3.3.7.1 Delay objects

Delay objects are the most common objects for modelling timers: a Delay object makes
sure that a Handler function is called after a specified period.

3.3.7.2 Periodic event objects

A periodic event object (Pe) is a specialised version of a Delay object. A Task creating a
Pe object receives events in regular intervals.

HighTec EDV-Systeme GmbH 17

Users Guide V1.1 3.4 Inter-process communication

3.3.7.3 Timeout objects

A timeout object (To) is a specialised version of a Delay object. A Task creating a To

object receives a single event after a defined period.

Note:
Objects that were released after utilisation, are returned to the object
pool they were taken from.

3.4 Inter-process communication

Inter-process communication, meaning communication among different Tasks, is achieved
by two different mechanisms: Messages and Events.
The two types of communication are different in that Messages can contain data, which
can be processed by the recipient, whereas Events can only signal that an event has
occurred.

3.4.1 Messages
A Message object represents an element of communication that can transfer data.
A Task wishing to send a Message has to provide a data buffer for this Message.
The data buffer for a Message can be obtained in two ways: the sending Task can state a
memory class (see subsection 3.3.2 on page 15), from which the memory is to be taken,
i.e. it borrows the memory from this memory class and can use it as if it were its own
memory for as long as it owns the Message.
The other possibility is to provide the Message object with memory of the Tasks own
memory.
The data buffer can be filled with random data. As soon as the Message was sent to a
mailbox, the corresponding buffer is no longer part of the memory area of the Task, i.e.
the Task may no longer access this memory area.

HighTec EDV-Systeme GmbH 18

Users Guide V1.1 3.4 Inter-process communication

Figure 3.8: Sending a Message

If a recipient Task reads the Message from the mailbox, the contained buffer is allocated to
its memory area. The Task can access this area until it passes the Message on or releases
it. Once the Message was released, the contained memory is reallocated to its original
owner, i.e. the memory class or Task.

Figure 3.9: Receiving a Message

3.4.2 Events
An Event is used for signalling an occurrence to a Task. In comparison to Messages, Events
have the advantage of not using up any system resources. Up to 32 different Events can
be signalled, part of which can be freely defined by the application, and part of which are
predefined.
A Task can wait for several Events at the same time and is awakened as soon as one of
the Events occurs.

HighTec EDV-Systeme GmbH 19

Users Guide V1.1 3.5 Safety characteristics

3.5 Safety characteristics

The safety characteristics of PXROS-HR have the purpose of minimising the effects of
runtime errors. Runtime errors should be detected so that, firstly, they can be reacted to
properly via exception handling, and secondly, so that error propagation throughout the
system is avoided.

3.5.1 Hardware memory protection

The PXROS-HR safety concept is based on hardware-assisted memory supervision. This
concept relies upon the Memory Protection Unit (MPU) of the processor. The MPU
contains registers, in which the upper and lower bounds of the memory area of a Task (or
the system), as well as the corresponding rights (read and/or write) are stored.

Figure 3.10: Memory protection register

3.5.2 Memory protection and encapsulation

A Task is regarded as being enclosed in a capsule, which it cannot leave. Hardware memory
protection has the purpose of preventing a Task from reaching out of its capsule.
During initialisation, memory is allocated to a capsule, which it can access. The start and
end addresses of this area, as well as read and write permissions, are stored in registers of
the MPU, making it possible for the hardware to check memory access operations during
runtime. This memory area contains the data as well as the stack memory of the Task.

Note:
The MPU can even detect stack overflow if the memory is appro-
priately apportioned, i.e. if the stack is located at the end of the
individual memory.

Apart from this, memory can be mapped onto the address area of the Task if the Task
receives a Message object.

HighTec EDV-Systeme GmbH 20

Users Guide V1.1 3.5 Safety characteristics

Figure 3.11: Memory areas of a Task

In addition, extended memory areas can be defined for a Task. This method is, however,
subject to a loss in performance since the memory areas are stored in virtual protection
registers that have to be mapped to the hardware registers before they can be accessed.
If a Task reaches out of its memory areas, the MPU detects this violation of memory
protection and triggers a trap, thus avoiding error propagation. The cause of the error
can be detected and the erroneous module can be selectively deactivated. Functional safety
of the systems is thus guaranteed.
This type of memory protection makes it possible to realise the concept of encapsulation:
A Task and its local Handlers are regarded as being located within a capsule, being thus
separated from the rest of the system, which in itself also consists of capsules. Communi-
cation is achieved purely via Message objects and Events.
This leads to the separation of the individual functional units. The capsules can be con-
sidered as each running on a processor of its own. Complexity of the system is thus
reduced, and the probability of error propagation. Should, nevertheless, an error occur,
its effects are restricted to the corresponding capsule. Thanks to these characteristics, test
procedures for applications can be modularised.

3.5.3 Permissions
Tasks in general do not have any permission to access resources; such access has to be
granted explicitly in individual cases. The permission concept knows two types of permis-
sion: privileges and access rights.

HighTec EDV-Systeme GmbH 21

Users Guide V1.1 3.5 Safety characteristics

Privileges are permission levels of the hardware. They can be subdivided into two cate-
gories: system privileges allow full access and are only available to the operating system
and certain interrupt Handlers; user privileges exist in several levels and can be assigned
to parts of the application.
The following privilege levels exist:
Usermode0 allows access to the internal memory area exclusively
Usermode1 allows access to the internal memory area and to the periphery
Systemmode allows full access (only available to the operating system and certain inter-
rupt Handlers)
Access rights are managed by the operating system. The following access rights can be
granted:
PXACCESS HANDLERS for installing Handlers that own system rights
PXACCESS INSTALL HANDLERS for installing Handlers that own the rights of the
Task
PXACCESS INSTALL SERVICES for installing certain PXROS-HR services as Han-
dlers
PXACCESS REGISTER for executing system functions that have access to special reg-
isters of the processor
PXACCESS SYSTEMDEFAULT give access to the system memory class and system
object pool
PXACCESS RESOURCES allows a Task to access, in addition to its own resources
(those that were assigned to it during creation or that it created itself), but also to
resources that it does not own
PXACCESS NEW RESOURCES allows a Task to create object pools or memory classes
PXACCESS SYSTEM CONTROL allows a Task to suspend or continue other Tasks
PXACCESS MODEBITS allows a Task to set its modebits
PXACCESS OVERRIDE ABORT EVENTS allows a Task to override its aborting events
In cases where a system service is called without having the required access rights, an
error code is returned.

3.5.4 Error handling

The safety characteristics of PXROS-HR include the ability to detect and react to runtime
errors, such as memory access violations.
There are, essentially, two kinds of error treatment:
First: Errors are detected during the regular control flow, i.e. during system calls PXROS-
HR checks, whether a call is valid and returns the corresponding error code. Invalid system

HighTec EDV-Systeme GmbH 22

Users Guide V1.1 3.5 Safety characteristics

calls include calls with faulty parameters, such as invalid object IDs, missing permissions
or invalid system function calls within a Handler.
Second: Exceptional treatment aborts the regular control flow: invalid memory access
operations cause the MPU to trigger a trap. The trap can be processed by an application-
specific trap handler routine.

HighTec EDV-Systeme GmbH 23

4 Services of the system
In addition to the normal functionalities of an operating system, PXROS-HR provides
further services to an application. These services can be subdivided into services of the
core system, which can be used at any time, and supplementary services that have to be
linked in the form of independent modules.

4.1 Services of the core systems

A PXROS-HR system offers a number of central services that can be used by application
Tasks.

4.1.1 PxSysInfo services

PxSysInfo services give access to information on the internal system condition. Details to
be requested include the number and type of objects used, and the number of free objects.

4.1.2 Nameserver
Giving access to special PXROS-HR objects, the Nameserver acts as an addressbook
where the requested objects can be browsed. For example: A reloaded Task can request
another Task, which it wishes to communicate with.
Objects can be registered with the Nameserver by a unique name. Later this name can
be used for requesting the object from the Nameserver. Any attempt to register an object
by a name that already exists, will fail; an error code is returned in such a case.
Names are assigned in accordance with a specific pattern: a name always consists of
four numbers ranging from 0 to 255. This combination of numbers, which has to be
unique within the system, makes it possible to group objects. The combination 1,1,5,x,
for example, is reserved for the file system (see also section 8.2 on page 61).

Note:
This service is necessary for a reloaded Task to communicate with the
rest of the system.

4.1.3 Tracing
The PXROS-HR tracing service makes it possible to record system calls, message exchange
and events for debugging purposes. The called function and its arguments as well as a
time stamp are stored in a buffer. These stored data can then be read by the application
and interpreted by an analysing tool such as PxView (see subsection 4.2.3 on page 25).
Users Guide V1.1 4.2 Additional services

4.1.4 PXROS-HR Service Task

A PXROS-HR Service Task is used in certain situations for calling system services. A
Handler can, for example, prompt the Service Task to release resources, a process that is
denied to the Handler itself. Any Task can be declared as a Service Task.

4.1.5 System monitor

Communication between the bebugger on the host side and the PXROS-HR system re-
quires an appropriate interface, which is provided by the system monitor. Besides the
interface for the debugging functionality there is also a second interface for reloading
Tasks. The system monitor is included in the functional range of the operating system.

Note:
The system monitor is capable of intercepting memory protection
traps, and passing them on to the debugger.

4.2 Additional services

In addition to the services provided by the core system, supplementary services can be
iincluded into a PXROS-HR basic system.

4.2.1 TCP/IP stack

PXtcp implements a TCP/IP stack. An appropriate ethernet driver is required in order
to be able to use PXtcp.

4.2.2 PXfile
PXfile makes the functionalities of a file system available, which can either be a local FAT
system of a remote NFS system. The NFS type requires PXtcp.

4.2.3 PXview Tracing

PXview is an extension of PXROS-HR tracing (subsection 4.1.3 on page 24), which makes
it possible for the user to define and record his own log entries.
Furthermore, a tool is available for loading the recorded data from the target and dis-
playing them. The data can be loaded via serial port or ethernet interface. The use of
ethernet requires PXtcp.

HighTec EDV-Systeme GmbH 25

 Part II

Usersguide
5 Summary
This part of the PXROS-HR user manual describes the practical operation of the system.
Examples will illustrate how applications are created under PXROS-HR.
A PXROS-HR application usually consists of one or more Tasks, as well as local and
global Handlers, which communicate with each other by means of message objects or
Events. A Task has a dedicated main function, which is called when the Task is started.
Normally, this Task function is never quit, i.e. it contains an infinite loop.
First an initialisation Task is started that creates further Tasks and carries out the neces-
sary initialisation processes. Once initialisation is finished, the priority of the initialisation
Task is usually set to the lowest level, and it is used as an idle Task, i.e. it is only used if
no other Task or Handler is active.
6 Layout of a programming interface
The PXROS-HR programming interface (API) has a schematical layout:
Function and type identifiers of the PXROS-HR interface always start with the prefix Px,
macros with PX.
With function names, said prefix is followed by the type of the object, which the function
refers to, followed by the action that is performed. Example: PxTaskGetPrio returns the
priority of a Task.
Type identifiers consist of the prefix, a unique name and the suffix _t or _T, e.g. PxTask_t.
7 Programming the core system
The following chapter describes how to program a PXROS-HR application. For this pur-
pose, the basic concepts and terms, as well as best practice procedures are explained
and illustrated by examples.

7.1 Basic concepts

Below some of the fundamental terms in connection with PXROS-HR are explained.
Event : An Event is represented by a value between 1 and 31. Thus, several Events to be
sent or to be waited for can be stored in a four bytes bitmask, i.e. a long value.
Priority : the priority of a Task can have a value between 1 and 31, wherein a lower value
means a higher priority.
Ticks : the hardware-independent time basis of a PXROS-HR system; the attribution of
ticks to milliseconds can be defined by the user at random.
Handles : PXROS-HR objects cannot be accessed directly; to use PXROS-HR objects,
Handles are utilised, which represent objects at the interface (see subsection 7.3.1
on page 39)

7.2 The first simple application

The simple application created below does not contain any functionality, yet it imple-
ments an executable basic PXROS-HR system consisting of the following basic elements:
initialisation of PXROS-HR, the Inittask, and an empty Task.

7.2.1 Initialising PXROS-HR

Before PXROS-HR system calls can be used, PXROS-HR has to be initialised. This is
done via the function PxInit . This function receives a parameter of the PxInitSpec_T type.

7.2.1.1 PXROS specification

The PXROS-HR initialisation structure PxInitSpec_T is defined as follows:

PxMcType_t is_sysmc_type:
the type of system memory class; permitted values are
PXMcVarsized and PXMcVarsizedAdjusted

PxSize_t is_sysmc_size:
size of a block of the system memory class
(is ignored if a variable size is defined)
Users Guide V1.1 7.2 The first simple application

PxAligned_t is_sysmc_blk:
pointer to the beginning of the system memory class

PxSize_t is_sysmc_blksize:
overall size of the system memory class

PxUInt_t is_obj_number:
number of PXROS objects

PxObjId_t is_obj_namelength:
maximum length of the object names, including zero fillers

PxTaskSpec_ct is_inittask:
Task specification of the Inittask
subsubsection 7.2.1.3 on page 31

PxInt_t is_monitoring:
This flag states if requests of variable memory blocks
and creation of Tasks is to be logged

PxGlobalSchedExt_ct is_schedext:
this parameter is presently not in use

PxMcType_t is_taskmc_type:
type of memory class of the Inittask; permitted values are
PXMcVarsized and PXMcVarsizedAdjusted

PxSize_t is_taskmc_size:
is ignored

PxAligned_t PXDptr_q is_taskmc_blk:

pointer to the beginning of the memory class of the Inittask

PxSize_t is_taskmc_blksize:
overall size of the memory class of the Inittask

PxProtectRegion_T is_sys_data_protection[4]:
protected data areas of the system

PxProtectRegion_T is_sys_code_protection[1]:
protected code area of the system

PxProtectRegion_T is_task_code_protection[1]:
protected code area of the application

HighTec EDV-Systeme GmbH 30

Users Guide V1.1 7.2 The first simple application

7.2.1.2 Init function

Calling PxInit starts the Inittask and only returns if an error occurred during initialisation.
In this case, the function returns a corresponding error code:
PXERR INIT ILLALIGN Erroneous alignment of system memory class
PXERR INIT ILLMCTYPE System memory class is not of type PXMcVarsized or PXMcVarsizedAdjusted
PXERR INIT NOMEM Not enough memory available
PXERR PROT ILL REGION Invalid memory protection areas defined
After a successful PxInit call, the PXROS-HR system services are available.

7.2.1.3 The Inittask

The Inittask is the first Task of the system. It is automatically started after system ini-
tialisation and corresponds in layout and handling to a normal Task (see subsection 7.2.3
on page 34). The differences lie in that it is created and started by PxInit , and that its
memory class is not stated in the Task specification but defined in PxInitSpec_T. This
is because no PXROS-HR system calls are available before system initialisation, so no
memory class can be created at this time.
The Inittask can be used for initialising the application and for creating and starting the
application Tasks. Typically, the priority of the Inittask set to lowest priority after the
initialisation phase, i.e. it is only activated if no other Task or Handler is active (Idletask).

Note:
The existence of an Idletask is not compulsory. The Inittask could also
be terminated after execution, yet it should be kept running since it
doesnt use up any processing time (lowest priority), and makes it
easier to analyse the scheduling behaviour of the system, for example
via PxView (see subsection 8.5.2 on page 64).

7.2.1.4 Sample code

The initialisation of the PXROS-HR system is exemplified by the below code:

// for more information on this structure, see chapter

// "Layout and initialisation of a Task"
static const PxTaskSpec_T InitTaskSpec =
{
.ts_name = "InitTask",
.ts_fun = InitTask_Func,
.ts_mc = PXMcSystemdefault,
.ts_opool = PXOpoolSystemdefault,
.ts_prio = 0,
.ts_privileges = PXUser1Privilege,
.ts_context = &InitTaskContext,
.ts_taskstack.stk_type = PXStackFall,

HighTec EDV-Systeme GmbH 31

Users Guide V1.1 7.2 The first simple application

.ts_taskstack.stk_size = PXStackDontCheck,
.ts_taskstack.stk_src.stk = &inittask_stack[INITTASK_STACKSIZE],
.ts_inttaskstack.stk_type = PXStackFall,
.ts_inttaskstack.stk_size = PXStackDontCheck,
.ts_inttaskstack.stk_src.stk = &inittask_intstack[INITTASK_INTSTACKSIZE],
.ts_abortstacksize = 0
};

// PXROS-HR system specification

static const PxInitSpec_T InitSpec =
{
// type of the system memory class
.is_sysmc_type = PXMcVarsized,

// size of a block of the system memory class

// in this case 0 since variable block size is defined
.is_sysmc_size = 0,

// pointer to the system memory

.is_sysmc_blk = Sysmem,

// size of the system memory class

.is_sysmc_blksize = SYSMEMSIZE,

// number of available PXROS-HR objects

.is_obj_number = 100,

// maximum string length for names

// of PXROS-HR objects
.is_obj_namelength = PXROS_NAMESIZE,

// pointer to the Task specification of the

// Inittask
.is_inittask = &InitTaskSpec,

// this parameter is ignored

.is_monitoring = 0,

// this parameter is ignored

.is_schedext = 0,

// definitions of the protected areas

// read-only data area of the system

.is_sys_data_protection[0].lowerBound
= (PxUInt_t)&PxTricSystemRamBegin,
.is_sys_data_protection[0].upperBound
= (PxUInt_t)&PxTricSystemRamEnd,
.is_sys_data_protection[0].prot = ReadProtection,

// writeable data area of the system

.is_sys_data_protection[1].lowerBound
= (PxUInt_t)&PxTricSystemDataLowerBound,
.is_sys_data_protection[1].upperBound

HighTec EDV-Systeme GmbH 32

Users Guide V1.1 7.2 The first simple application

= (PxUInt_t)&PxTricSystemDataUpperBound,
.is_sys_data_protection[1].prot
= WRProtection,

// the writeable data area of the system in the internal RAM

.is_sys_data_protection[2].lowerBound
= (PxUInt_t)&PxTricSystemIntDataLowerBound,
.is_sys_data_protection[2].upperBound
= (PxUInt_t)&PxTricSystemIntDataUpperBound,
.is_sys_data_protection[2].prot
= WRProtection,

// these memory protection registers are not used

.is_sys_data_protection[3].lowerBound = (PxUInt_t)0,
.is_sys_data_protection[3].upperBound = (PxUInt_t)0,
.is_sys_data_protection[3].prot = NoAccessProtection,

// code area of the operating system

.is_sys_code_protection[0].lowerBound
= (PxUInt_t)&PxTricSystemExtCodeLowerBound,
.is_sys_code_protection[0].upperBound
= (PxUInt_t)&PxTricSystemExtCodeUpperBound,
.is_sys_code_protection[0].prot
= XProtection,

// code area of the application, operating system code and

// application code lie in the same memory area in this example
.is_task_code_protection[0].lowerBound
= (PxUInt_t)&PxTricSystemExtCodeLowerBound,
.is_task_code_protection[0].upperBound
= (PxUInt_t)&PxTricSystemExtCodeUpperBound,
.is_task_code_protection[0].prot
= XProtection,
};

// Since no memory class is defined for the Inittask,

// the system memory class is allocated by default

PxError_t error;

// the initialisation of PXROS-HR; if PxInit returns,

// the corresponding error code is logged in error

error = PxInit(&InitSpec);

7.2.2 Startup-initialisation
Before the initialisation of PXROS-HR, possible hardware configurations might be carried
out. Since this usually has to done with system permission, an application cannot carry
out these procedures since it runs in user mode. This problem can be circumvented if the
application passes random functions, which can be used for the purpose to the operating
system.
_PxInitCall( function ,params ...) adds the function function with its parameters params to an

HighTec EDV-Systeme GmbH 33

Users Guide V1.1 7.2 The first simple application

internal table; params is a random list of parameters.

The user can start the execution of these functions by calling PxInitializeBeforePxInit () .
The functions are executed with system permission and in the order, in which they were
entered in the table.

Note:
The function PxInitializeBeforePxInit has to be called before the ini-
tialisation PXROS-HR, i.e. before PxInit !

7.2.3 Layout and initialisation of a Task

7.2.3.1 General

Essentially, a PXROS-HR Task consists of a Task function, which is called when the Task
is started. After its creation a Task is started by sending an activation event, i.e. the Task
function is called, provided one or more activation events were defined. If no activation
event was defined when the Task was created, the Task is immediately started. Normally,
this Task function is never quit, i.e. it contains an infinite loop.
In exceptional cases a Task can be terminated by calling the system service PxDie. This
function does not return. To be able to use PxDie, a Service Task has to be initialised
beforehand (see section 8.4 on page 62).
The initialisation of the Task is carried out during creation via the function PxTaskCreate.
The necessary parameters for initialising the Task are passed to this function:
opool : the object pool, from which the Task object is taken.
taskspec : the Task specification, which contains the necessary data for initialisation (see
subsubsection 7.2.3.2 on page 34)
prio : the priority of the Task
actevents : Events activating the Task; usually only one

7.2.3.2 Task specification

Task specification is a structure of the type PxTaskSpec_T (the type designators PxTaskSpec_t
and PxTaskSpec_ct mentioned in the reference manual relate to pointers or constant point-
ers to PxTaskSpec_T). This structure is defined as follows:

PxUChar_t ts_name :
name of the Task; a random string

void (ts_fun)(PxTask_t task, PxMbx_t mbx, PxEvents_t events) :

pointer to the Task function

PxMc_t ts_mc :
Standard memory class of the Task

HighTec EDV-Systeme GmbH 34

Users Guide V1.1 7.2 The first simple application

PxOpool_t ts_opool :
Standard objectpool of the Task

PxStackSpec_T ts_taskstack :
Stack specification of the Task (see page 36)

PxStackSpec_T ts_inttaskstack :
Interrupt stack specification of the Task (see page 36)

PxUChar_t ts_prio :
Initial priority of the Task; this parameter is kept only for
compatibility; it is ignored

PxEvents_t ts_actevents :
Activation events for the Task, this parameter is kept only for
compatibility; it is ignored

PxTicks_t ts_timeslices :
size of the time slices for this Task;
if this value is set to 0, no time slices are used

PxSize_t ts_abortstacksize :
size of the abort stacks, stated by the number of frames

PxTaskSchedExt_t ts_sched_extension :
not implemented

PxArg_t ts_sched_initarg :
not implemented

PxArg_t ts_privileges :
Privileges of the Task

PxUInt_t ts_accessrights :
Access rights of the Task

PxTaskContext_ct ts_context :
Description of the address space of the Task (see page 36)

PxProtectRegion_ct ts_protect_region :
extended memory areas of the Task

Notes:
A standard memory class can be accessed via the macro PXMcTaskdefault
The standard object pool of the Task can be accessed via the macro PXOpoolTaskdefault

HighTec EDV-Systeme GmbH 35

Users Guide V1.1 7.2 The first simple application

Signalising an activation event starts the Task, i.e. after its creation the Task waits
until it receives an activation event; usually only one activation event is stated
The size of the Abort stacks determines the maximum nesting depth of PxExpectAbort
calls (see section 7.10 on page 58)
ts_protect_region defines extended memory areas of the Task. Extended memory
areas can be used in addition to the normal memory context of the Task. During
normal operation this should be avoided since the access to extended memory areas
is rather slow, yet in special cases this might be necessary, e.g. if a Task needs access
to a register set, or if access to configuration data is required.
The type PxStackSpec_T is used for describing Task and interrupt stacks. It contains
information on the stack type (ascending/descending), stack size, and from where the
memory is taken (for details, see the PXROS-HR reference manual).
The PxTaskContext_t structure describes the memory context of the Task. It contains two
protection regions (see below, PxProtectRegion_t). The first defines the read-only data area
of the Task, the second defines the read-write data area of the Task.
The structure PxProtectRegion_t defines protected memory areas, which can be made avail-
able to the Task. It contains the upper and lower boundary of the memory area (the first
valid and the first invalid address), as well as the access permission: no access; read only;
write only; read and write.
Sample code for creating and initialising the Task specification:
// Definition of the memory context of the Task; since the elements of
// protection[0] are set to 0, the read-only memory area is inherited
// from the creator of the Task

static const PxTaskContext_T Task1_Context = {

// read-only data area, inherited from the creator of the Task

.protection[0].lowerBound = 0,
.protection[0].upperBound = 0,
.protection[0].prot = NoAccessProtection,

// read-write data area

.protection[1].lowerBound = (PxUInt_t)Task1_data_base,
.protection[1].upperBound = (PxUInt_t)Task1_data_end,
.protection[1].prot = WRProtection
};

// Creating the Task specification

const PxTaskSpec_T Task1_Spec = {
// Name of the Task
.ts_name = "Task1",

// Task function (see above)

.ts_fun = Task1_Func,

// Memory block of the Task

.ts_mc = PXMcTaskdefault,

HighTec EDV-Systeme GmbH 36

Users Guide V1.1 7.2 The first simple application

// Objectpool of the Task

.ts_opool = PXOpoolTaskdefault,

// Start priority of the Task, this Parameter exists only

// for compatibility; it is ignored
.ts_prio = 0,

// Privileges of the Task

.ts_privileges = PXUser0Privilege,

// A pointer to the memory context of the Task

.ts_context = &Task1_Context,

// Stack type, here falling

.ts_taskstack.stk_type = PXStackFall,

// Stack size to be checked; is ignored in this case

// (PXStackDontCheck)
.ts_taskstack.stk_size = PXStackDontCheck,

// Stack memory of size TASK1_STACKSIZE

.ts_taskstack.stk_src.stk = &Task1Stack[TASK1_STACKSIZE],

// Abort stack size; is ignored in this case

.ts_abortstacksize = 0
};

The Task is created as follows:

// Creates a Task with the predefined specification,
// priority TASK1_PRIO and the activation events TASK1_ACTIVATION_EVENTS.
// The return value is the ID of the created Task
Task1_Id = PxTaskCreate(opool, &Task1_Spec, TASK1_PRIO, TASK1_ACTIVATION_EVENTS);

7.2.3.3 The Task function

A Task function has to conform to the following prototype:

void Task_Func(PxTask_t myID,
PxMbx_t myMailbox,
PxEvents_t myActivationEvents)

These parameters are passed from the system as soon as the function is called, i.e. if
the corresponding Task is activated for the first time. The parameters have the following
meaning:
myID ID of the Task
myMailbox Private mailbox of the Task
myActivationEvents Mask of the received activation events
If activation events were defined when creating the Task (see subsubsection 7.2.3.2 on
page 34), the Task will only become active if one or more of these events are received.

HighTec EDV-Systeme GmbH 37

Users Guide V1.1 7.2 The first simple application

The Task function can contain almost any code, yet it may not be terminated. This means,
it must either contain an infinite loop or be terminated via a blocking system call (e.g.
PxAwaitEvents(0)).

A typical Task function consists of a declaration and initialisation section and an infinite
loop. In this loop the function waits for events and/or messages. If an Event or a message
is received, the Task becomes ready for execution. If it has the highest priority of all Tasks
in ready state, it is executed.
Example for a Task function:
void InitTask_Func(PxTask_t myID,
PxMbx_t myMailbox,
PxEvents_t myActivationEvents)
{
// Declarations and initialisations
int foo = 0;
int bar;

if(myActivationEvents == EV_ACT_EV1)
{
bar = 1;
}
else
{
bar = 42;
}

// Main loop
while(1)
{
// Parallel waiting for events and messages
PxMsgEvent_t msgev;
msgev = PxMsgReceive_EvWait(myMailbox,EV_EVENT_MASK);
if(PxMsgIdIsValid(msgev.msg))
{
// message received
do_sth_with_msg(msgev.msg);
}

if(msgev.events != 0)
{
// event received
do_sth_with_events(msgev.events);
}
}
}

7.2.4 Summary
Summary of the Initialisation of a PXROS-HR system:

HighTec EDV-Systeme GmbH 38

Users Guide V1.1 7.3 Utilising system services

Figure 7.1: Initialisation

A complete module for implementing the initialisation of PXROS-HR and for creating a
Task can be found in the appendix A.1.

7.3 Utilising system services

7.3.1 Basics
In principle, every PXROS-HR system service returns a value that should be noted. This
value is either an object handle or a numeric type. A numeric value might be an error
code, an event bit mask or a priority.
Handles are interface representations of PXROS-HR objects. If objects are requested from
the system or passed on to system services, this is done via Handles.
If a service returns an error code, this code should be regarded in any case. If a service
returns an object handle, the user should always check if the Handle is valid or if an error
is on hand. PxMsgIdIsValid can be used for checking if a requested message object is valid.

7.3.2 Blocking and non-blocking system services

PXROS-HR system services can be blocking or non-blocking. Non-blocking system ser-
vices return immediately after having been called, while blocking services can set a Task
to the waiting state, which can cause scheduling. There are three reasons why a system
call can be blocking:
1. Waiting for an event: the function returns as soon as it receives an event
2. Waiting at a mailbox: the function returns as soon as the mailbox contains message
objects

HighTec EDV-Systeme GmbH 39

Users Guide V1.1 7.4 Object management

3. Waiting at an object pool: if an object (e.g. a message) is requested from an object

pool, a system service can block if the object pool is empty; it will then only return
if objects are available again

7.3.3 System calls in Tasks and Handlers

In system service calls a differentiation is made as to whether the call was made by a
Handler or by a Task. Handlers may only call system functions with the suffix _Hnd.
Tasks, in contrast, may only call functions, which do not have the _Hnd suffix. If a call
occurs at the wrong place, an error message will be returned: PXERR_HND_ILLCALL in
case a Handler service was called in a Task, or PXERR_TASK_ILLCALL in the opposite
case.

7.4 Object management

7.4.1 Object pools
PXROS-HR objects can, whenever they become necessary, be requested from an object
pool.
A standard object pool is passed to a Task during its creation, yet the Task can also
access other object pools if they are made available and if the Task has an access right to
such resources (see subsection 3.5.3 on page 21).
An object pool can be used by several Tasks; thus a flexible distribution of objects can
be achieved. The disadvantage of this method is that in the event of an object shortage,
all the Tasks that have access to this object pool might be affected.
A typical application for object pools could be that Tasks, which are important for the
system, have their own object pools assigned, while less important Tasks share a common
object pool.

7.4.2 Requesting PXROS-Objekten

PXROS-HR objects can be requested as generic objects via the general function PxObjRequest
and subsequently converted into the required type, or they can - which is usually done -
be requested by a specialised function, which returns the required type, e.g. PxMsgRequest,
which returns an object of the type PxMsg_t.
Requesting objects is only possible within a Task; within a Handler this is not permitted
(see subsection 7.3.3 on page 40).

7.5 Memory management

Memory management under PXROS-HR is based on memory classes. A memory class is
an object of the type PxMc_t. A memory class can manage memory in blocks of fixed or
variable size. Fixed block size allows a quicker access to memory blocks, while variable
block size makes it possible to access memory blocks in exactly the size in which they are

HighTec EDV-Systeme GmbH 40

Users Guide V1.1 7.6 Communication

needed, thus making memory utilisation more efficient. Memory classes are not usually
used for requesting memory explicitly, but mainly for making memory available to message
objects. By default, a Task has two memory classes at its disposal: PXMcSystemdefault, the
standard memory class of the system, and PXMcTaskdefault, the standard memory class
of the Task, which was assigned to it during creation. To use PXMcSystemdefault the Task
must have the appropriate rights (see subsection 3.5.3 on page 21).

7.6 Communication
Communication and synchronisation of different Tasks is achieved via Events and mes-
sages. Messages are objects containing data, while Events are flags signalling events.

7.6.1 Events
An Event is a flag signalling a certain event. A Task can wait for certain Events by the
function PxAwaitEvents(PXEvents_t events). The parameter events is a bitmask stating for
which Events the Task shall wait. PxAwaitEvents blocks until one or more of the events
defined in events occur. If events is set to zero, PxAwaitEvents will not return.

Note:
The uppermost four bits (28 - 31) are reserved for the operating sys-
tem and should not be used by the application!
...

#define EV_EV1 1
#define EV_EV2 (1<<1)
#define EV_EV3 (1<<2)

...

PXEvents_t ret_ev;

// wait for Event EV_EV1, EV_EV2 or EV_EV3

ret_ev = PxAwaitEvents(EV_EV1|EV_EV2|EV_EV3);

// check, which event has arrived

if( ret_ev & EV_EV1)
{
...
}
if( ret_ev & EV_EV2)
{
...
}
if( ret_ev & EV_EV3)
{
...
}

...

HighTec EDV-Systeme GmbH 41

Users Guide V1.1 7.6 Communication

PxGetSavedEvents returns the Events received but not yet processed by the Task. This
function returns immediately.
The non-blocking resetting of the Events of a Task is carried out by
PxResetEvents(PXEvents_t events). The parameter events states, which Events are to be
reset. This function returns a bitmask stating, which Events were reset.
...

PXEvents_t ret_ev;

// Events reset are returned

ret_ev = PxGetSavedEvents();

...

// all Events reset are deleted

ret_ev = PxReserEvents(ret_ev);

...

...

...

7.6.2 Messages
Messages are PXROS-HR objects containing a data buffer and are used for data inter-
change between Tasks. A Task creating a message object is called the Owner of the
message; the Task currently having access to a message object is called the User of the
message.

7.6.2.1 Requesting and releasing message objects

Message objects can be requested in two different ways: They can either be created by
PxMsgRequest or by PxMsgEnvelop. The differences lies in that that with PxMsgRequest the
data memory of the message is taken from a memory class, while with the envelope
mechanism the memory has to be provided by the requesting Task.
Message objects can be requested by Tasks but not by Handlers.
There are several ways of requesting message objects via PxMsgRequest:
PxMsgRequest(PxSize_t size, PxMcId_t mcid, PxOpoolId_t opool):
This function returns a message object taken from the object pool
opool. It contains a data buffer of the size size . The data buffer is
taken from the memory class mcid. Should the object pool be empty,
this function will block until objects are available again.
PxMsgRequest_NoWait(PxSize_t size, PxMcId_t mcid, PxOpoolId_t opool):
This function returns a message object taken from the object pool
opool. It contains a data buffer of the size size . The data buffer is
taken from the memory class mcid. Should the object pool be empty,
the returned Handle is invalid. This function returns immediately.

HighTec EDV-Systeme GmbH 42

Users Guide V1.1 7.6 Communication

PxMsgRequest_EvWait(PxSize_t size, PxMcId_t mcid, PxOpoolId_t opool, PxEvents_t ev):

This function returns a message object taken from the object pool
opool. It contains a data buffer of the size size . The data buffer is
taken from the memory class mcid. Should the object pool be empty,
this function will block until objects are available again or until one of
the Events stated in ev occurs.

Note:
PxMsgRequest is a way for a Task to request memory dynamically.

If the envelop mechanism is to be used, one of the following functions can be executed:
PxMsgEnvelop_EvWait(PxMsgData_t data,PxSize_t size,PxOpool_t opool): This function
packs the buffer data from the memory area of the Task into a message object taken
from the object pool opoolid and returns this package. Should the object pool be
empty, this function will block until objects are available again.
PxMsgEnvelop_NoWait(PxMsgData_t data,PxSize_t size,PxOpool_t opool)): This function
packs the buffer data from the memory area of the Task into a message object taken
from the object pool opoolid and returns this package. Should the object pool be
empty, this function will return an invalid Handle.
PxMsgEnvelop_EvWait(PxMsgData_t data,PxSize_t size, PxOpool_t opool,PxEvents_t ev):
This function packs the buffer data from the memory area of the Task into a mes-
sage object taken from the object pool opoolid and returns this package. Should the
object pool be empty, this function will block until objects are available again or
until one of the Events specified in ev occurs.

Note:
If the envelop mechanism is used, the data area of the message is not
taken from a memory class; instead the creating Task has to provide
a buffer from its own memory area.

A message can be released by the function PxMsgRelease or PxMsgRelease_Hnd. If a message

object is released, the Task or Handler abandons its access right to the data area of the
message. By default the message object is stored in its original object pool, and its data
buffer is returned to the memory class where it was taken from or, if the message was
created via PxMsgEnvelop..., data buffer is reallocated to the memory area of the original
Owner of the message.

Note:
To be precise, the memory buffer packed via PxMsgEnvelop is not really
taken from the memory area of the Task; the Task could, theoretically,
still access this area. The buffer should, however, be treated as if it
were extracted from the address space of the Task.

The behaviour of PxMsgRelease... can vary:

HighTec EDV-Systeme GmbH 43

Users Guide V1.1 7.6 Communication

If a message is fitted with a Release mailbox (via the function PxMsgInstallRelmbx(PxMsg_t msgid, PxM
the behaviour of PxMsgRelease... changes: the corresponding message object is not re-
leased but stored in the mentioned Release mailbox instead (see subsubsection 7.6.2.2
on page 44).
After a message was sent via the function
PxMsgAwaitRel(PxMsg_t msg), the Owner of the message can wait for release. To do
so, PxMsgSetToAwaitRel(PxMsg_t msg) has to be called before sending. Then, if the
recipient of the message calls PxMsgRelease, the message object is not released but
returned to the sender instead.
Note:
If a message was marked via PxMsgSetToAwaitRel, the function
PxMsgAwaitRel(PxMsg_t msg) has to be used for waiting for the release
call.
7.6.2.2 Mailboxes

Mailboxes are a central component of the communication mechanism. A message is not

sent directly to the recipient Task, but to a mailbox, from which the recipient can read
it. Mailboxes are organised according to the FIFO principle (first in, first out). A mailbox
has unlimited capacity; a random number of messages can be stored within it.
Apart from message interchange between Tasks, mailboxes can also serve as message pools
or release mailboxes.
Message pools are mailboxes containing prefabricated message objects, which can be
extracted and reused by a Task (see also section A.3 on page 72). In comparison to
the requesting of message objects, this has several advantages:
it is quicker since the message object already exists instead of having to be
requested from the system first
message objects are available even if no PXROS-HR objects are available and
a request for an object from the object pool would fail
the consumption of PXROS-HR objects is restricted, i.e. any object shortage
caused by excessive use of message objects is of local relevance only
The disadvantages of using message pools:
possibly, the number of stored message objects exceeds the number of required
ones
the size of the data areas of the message objects has to be such, that the largest
data record to be sent fits into every message
Release Mailboxes are mailboxes, where message objects are stored after release by the
user, instead of being released. To utilise a release mailbox, the mailbox has to be
assigned to the message via PxMsgInstallRelmbx.

HighTec EDV-Systeme GmbH 44

Users Guide V1.1 7.6 Communication

To fulfil their purpose, message pools have to be specified as release mailboxes for the
contained message objects, so that they can return to the pool after release by the message
recipient.
The following code exemplifies how a message pool can be created and used:
...

PxMbx_t mpool;
PxMsg_t msg;

msgpool = PxMbxRequest(my_opool); // request mailbox object

if(PxMbxIdIsValid(msgpool)) // check, if object valid

{

PxMsg_t tmpmsg;
for(i=0;i<10;i++) // request 10 messages
{
tmpmsg = PxMsgRequest(MSG_SIZE, my_memclass,my_opool);
if(PxMsgIdIsValid(tmpmsg))
{
PxMsgInstallRelmbx(tmpmsg,msgpoool); // set release mailbox
tmpmsg = PxMsgSend(tmpmsg,msgpool) // send message to messag pool
if(PxMsgIdIsValid(tmpmsg))
do_error_handling();
}
else
{
do_error_handling();
}
}
}
else
{
do_error_handling();
}

...

msg = PxMsgReceive(msgpool); // a message is requested from the

// message pool

fill_msg_data();

PxMsgSend(msg,targetmbx) // the message is sent to the mailbox

// targetmbx
...

7.6.2.3 Sending and receiving messages

Sending and receiving messages is always done via mailboxes. The sender sends a message
to a mailbox, and the recipient reads the message from this mailbox.
A message is sent via the function PxMsgSend, the necessary parameters are the message
object to be sent and the mailbox to which the message is to be sent. After sending,

HighTec EDV-Systeme GmbH 45

Users Guide V1.1 7.6 Communication

the sender does no longer have access to the message object, meaning the Handle of the
message is invalid after sending. In addition, the sender passes the exclusive access right
to the data area of the message to the recipient, i.e. a pointer to this area is invalid.

Note:
A message object and the corresponding data area belong exclusively
to one user, i.e. they are allocated to one Task or one Handler.

A Task can receive a message by taking it from a mailbox.

PxMsgReceive(PxMbx_t mbx) returns the next available message in accordance with the
FIFO principle; prioritised messages are an exception to this rule. A prioritised message
is sent to the mailbox in question via the function PxMsgSend_Prio. A prioritised message
overtakes the normal messages in the mailbox.
Messages can also be received in a non-blocking way: PxMsgReceive_NoWait(PxMbx_t mbx)
returns immediately, either with a message object or with an invalid Handle if the mailbox
is empty.
PxMsgReceive_EvWait(PxMbx_t mbx) makes it possible to wait for messages and Events at
the same time. The function returns an object of the type PxMsgEvent_t. The following
check helps find out whether a message or an Event (or both) was returned:
...

PxMsgEvent_t retval = PxMsgReceive_EvWait(mbx);

if(PxMsgIdIsValid(retval.msg))
{
// a message was received
do_sth();
}

if(retval.events != 0)
{
// one or more Events were received

if(retval.event & EV1)

{
...
}

if(retval.event & EV2)

{
...
}

...
}

7.6.2.4 Accessing the content of a message

A Task or a Handler can access the content of a message as soon as the message was re-
quested from the object pool or taken from a mailbox. The function PxMsgGetData(PxMsg_t msg)

HighTec EDV-Systeme GmbH 46

Users Guide V1.1 7.6 Communication

or PxMsgGetData_Hnd(PxMsg_t msg) returns a pointer to the data area of the message ob-
ject msg, PxMsgGetBuffersize(PxMsg_t msg) returns the size of the data buffer and PxMsgGetSize(PxMsg_t m
returns the size of the data within the buffer.
If access to a data area is no longer required, yet the message is not to be released or sent,
the data area should be released via the function
PxMsgRelDataAccess(PxMsg_t msg) since parallel access is limited to a maximum of two
message buffers.

Note:
If access to a data area was released via
PxMsgRelDataAccess(PxMsg_t msg), a pointer to this area may
only be used after it was reset via PxMsgGetData, thus having renewed
access to the data.

Figure 7.2: Creating an sending a message

HighTec EDV-Systeme GmbH 47

Users Guide V1.1 7.6 Communication

Figure 7.3: Receiving a message

7.6.2.5 Sample code

The following example shows how to create, send and receive a message how to access the
received data.
Task1 creates and sends a message to Task2:
// Task1
...

struct comm_data data;

PxMsg_t msg;
PxError_t error;

...

// create message with data as data area of the message

msg = PxMsgEnvelop(&data,sizeof(data),my_opool);

if(!PxMsgIdIsValid(msg))
{
do_error_handling();
return;
}

error = PxMsgSetToAwaitRel(msg);
if(error != PXERR_NOERROR)
{
do_error_handling();
return;
}

HighTec EDV-Systeme GmbH 48

Users Guide V1.1 7.6 Communication

// Send the message; access to data and msg

// is no longer permitted
msg = PxMsgSend(msg,mbx_task2);

// if sending was successful, the message Handle

// is invalid
if(PxMsgIdIsValid(msg))
{
do_error_handling();
return;
}

// wait for recipient to release the message

msg = PxMsgAwaitRel(msg);

if(!PxMsgIdIsValid(msg))
{
do_error_handling();
return;
}

...

// the message is finally released

PxMsgRelease(msg);

Task2 waits at its mailbox for messages from Task1:

// Task2
...

struct comm_data* pdata;

PxMsg_t msg;

// wait for message

msg = PxMsgReceive(my_mbx);
if(!PxMsgIdIsValid(msg))
{
do_error_handling();
return;
}

// read data area of the message

pdata = (struct comm_data*)PxMsgGetData(msg);

...

// Release message; access to msg and p_data

// is no longer permitted
PxMsgRelease(msg);

...

HighTec EDV-Systeme GmbH 49

Users Guide V1.1 7.6 Communication

7.6.2.6 Access restriction

Access to the data area can be restricted for a user of the message. Either the type of
access or the size of the accessible area can be restricted.
WRProtection : permits unrestricted access to the data area, i.e. the user has the right
to read and write
WriteProtection : permits the user to write into the data buffer
ReadProtection : permits the user to read from the data buffer
NoAccessProtection : permits no access to the data buffer
Access protection can only be changed by the owner of the message.
The user of a message can restrict the data area of a message; this is achieved via
PxMsgSetData and PxMsgSetSize. The start address of the data area is reset via PxMsgSetData;
the new address has to lie within the original data area. The size of the data area is au-
tomatically adjusted, so that the last address lies within the original data area.
The size of the data area can be reset via PxMsgSetSize; care has to be taken that the last
address of the new data area lies within the original data area.
An example:
Task1 sends a message to Task2:
...
struct foo
{
int x;
int y;
struct bar b;
int z;
} data;

...
// create message and pack data into message
msg = PxMsgEnvelop(&data,sizeof(data),defaultopool);
PxMsgSetToAwaitRel(msg);

// protect data area of the message; the recipient

// has only read rights to the buffer; he may not
// write into it
PxMsgSetProtection(msg, ReadProtection);

...
// send to Task2
PxMsgSend(msg,task2mbx);
...
// wait for release of message
msg = PxMsgAwaitRel(msg);

// reset to original data area

PxMsgSetData(msg,0);

HighTec EDV-Systeme GmbH 50

Users Guide V1.1 7.7 Interrupt and Trap Handler

// reset to original size of the data area

PxMsgSetSize(msg,sizeof(data));
...

Task2 passes the message on to Task3; Task3 shall only have access to the component b
of the structure foo:
...
struct foo* pData;
...
// receive message
msg = PxMsgReceive(task2mbx);
...
pData = PxMsgGetData(msg);
...
// restrict start address and size of the data area to Element b of
// the structure foo
// Set start address to b
PxMsgSetData(msg,&pData->b);

// Set size to size of b, i.e. z is removed

PxMsgSetSize(msg,sizeof(pData->b));

// Note: If only the beginning of the data area is #umgesetzt#, the

// size of the remaining area is automatically adjusted

...
// send to Task3
PxMsgSend(msg,task3mbx);
...

Task3 receives the message and then releases it:

...
struct bar* pData;
PxSize_t size;
...
// receive message
msg = PxMsgReceive(task3mbx);
...
// request data area and size of the area
pData = PxMsgGetData(msg);
size = PxMsgGetSize();
...
PxMsgRelease(msg);
..

7.7 Interrupt and Trap Handler

Handlers are functions reacting to asynchronous events, i.e. to hardware or software in-
terrupts or to traps. Handler have system privileges and are generally of higher priority
than Tasks, meaning a running Task can always be interrupted by a Handler.
There are two types of interrupt Handlers: global Handlers or Fast Handlers, and local
Handlers. The latter should be used where possible since they do not run in interrupt

HighTec EDV-Systeme GmbH 51

Users Guide V1.1 7.7 Interrupt and Trap Handler

mode (see subsubsection 3.2.2.1 on page 13).

Note:
When starting the system, interrupts are switched off, so it is neces-
sary to activate them explicitly after initialising the interrupt source
and installing the Handlers.

7.7.1 Global Handlers

Global Handlers (or Fast Handlers) are the fastest and highest prioritised interrupt Han-
dlers. They run with system privileges in interrupt mode and are activated as soon as an
interrupt occurs.
Only then can a Task install a global Handler if it has the appropriate permission
(PXACCESS_HANDLERS, see also subsection 3.5.3 on page 21).
A global Handler is installed via the function
PxIntInstallFastHandler(PxUnit_t intno,
void (*inthandler)(PxArg_t),
PxArg_t arg)

The parameters have the following meaning:

intno : the number of interrupts to be handled
inthandler : the Handler function
arg : the argument of the Handler function
The function returns the error code PXERR_REQUEST_INVALID_PARAMETER if intno lies
outside the specification, otherwise PXERR_NOERROR.
The argument arg can be used for exchanging data between the Handler and a Task. An
example for data exchange between Handler and Task can be found in section A.2 on
page 70.
Instead of a self-implemented Handler, a service provided by PXROS-HR can also be
installed as a global Handler. To do so, the function
PxIntInstallServive(PxUInt_t intno,
PxSvEnum_t service,
PxArg_t arg,
PxEvenst events)

is installed. The parameters have the following meaning:

intno : the number of interrupts to be handled
service : the service to be installed
arg : the argument of the service function
events : the Events possibly sent by the service function

HighTec EDV-Systeme GmbH 52

Users Guide V1.1 7.7 Interrupt and Trap Handler

The function returns the error code PXERR_REQUEST_INVALID_PARAMETER if intno lies

outside the specification, or PXERR_ILLEGAL_SERVICE_CALLED if an invalid service was
defined, otherwise PXERR_NOERROR.
To be able to install a service, the Task has to have the permission
PXACCESS_INSTALL_SERVICES .

The following services are available:

PxTickDefine_IntHnd_SvNo:
calls the functionPxTickDefine_Hnd (see subsection 7.8.1 on page 55), arg and events are
ignored
PxTaskSignalEvents_IntHnd_SvNo:
calls the function PxTaskSignalEvents_Hnd; the Handle of the recipient Task has to be
passed in arg, the Events to be sent in events

7.7.2 Local Handlers

Local Handlers are executed with the privileges of the Task they installed, and run in
the address space of said Task. The Task must have the right to install local Handlers
(PXACCESS_INSTALL_HANDLERS, see also subsection 3.5.3 on page 21).
A local Handler is not immediately called if the corresponding interrupt is occurred;
instead it is entered into a list, which is processed after returning from interrupt level to
system level.

Note:
Due to the fact that a local Handler is first entered into a list, no
assumption can be made regarding its execution time. Real time be-
haviour is not given!

Before a local Handler can be installed, an interrupt object has to be requested via
PxInterruptRequest. A Handler is installed via:
PxIntInstallHandler(PxUnit_t intno,
PxInterrupt_t intobj,
void (*inthandler)(PxArg_t),
PxArg_t arg)

The parameters have the following meaning:

intno : the number of Interrupts to be treated
intobj : the Handle of the corresponding interrupt object
inthandler : the Handler function
arg : the argument of the Handler function
The function returns the error code PXERR_REQUEST_INVALID_PARAMETER if intno lies
outside the specification, otherwise PXERR_NOERROR.

HighTec EDV-Systeme GmbH 53

Users Guide V1.1 7.7 Interrupt and Trap Handler

7.7.3 Context Handlers

Context Handlers are executed with the privileges of the Task they installed, and run
in the address space of said Task. The Task must have the right to install Handlers
(PXACCESS_INSTALL_HANDLERS, see also subsection 3.5.3 on page 21).
A context handler is called immediately if the corresponding interrupt is occurred.
A Handler is installed via:
PxIntInstallFastContextHandler(PxUnit_t intno,
void (*inthandler)(PxArg_t),
PxArg_t arg)

The parameters have the following meaning:

intno : the number of Interrupts to be treated
inthandler : the Handler function
arg : the argument of the Handler function
The function returns the error code PXERR_REQUEST_INVALID_PARAMETER if intno lies
outside the specification, otherwise PXERR_NOERROR.

7.7.4 Trap handler

A trap handler is similar to an interrupt handler and, in principle, has the same func-
tionality. The difference in the two lies in that an interrupt handler is triggered by a
hardware or software interrupt, while a trap handler is triggered by the occurrence of an
error situation, such as a faulty memory access operation. If a trap handler is called, all
hardware interrupts are blocked.
A trap handler is installed by the function
PxTrapInstallHandler(PxUnit_t trapno,
void (*traphandler)
(PxUInt_t,
PxUInt_t,
PxUInt_t,
PxUInt_t,
TC_CA_t*)
PxArg_t arg)

The five parameters of a trap handler are defined as follows:

1. the number of the trap class of the occurred traps
2. the number of the occurred traps
3. the object ID of the active Task at the time the trap was triggered
4. a user-defined argument passed in arg
5. a pointer to the stored CSA

HighTec EDV-Systeme GmbH 54

Users Guide V1.1 7.8 Timer functionality

7.8 Timer functionality

The time unit used by PXROS-HR is a Tick. A Tick is an abstract time unit, the length
of which has to be defined by the application.

7.8.1 Basic timer functionality

The internal time management of PXROS-HR is based on an internal, system-independent
time unit, the Tick. The consecutive number of Ticks having passed since the start-up of
the timer system is internally administered and can be read or incremented via system
services.
The allocation of Ticks to a tangible time basis is done via function
PxTickSetTicksPerSecond, which states how many Ticks correspond to one second. PxTickSetTicksPerSecond(
for example, sets the length of a Ticks to 10 milliseconds.

Note:
It should be ensured that the time basis is the same for the initialisa-
tion of the timer interrupts and when calling PxTickSetTicksPerSecond.

The continued counting of Ticks is performed by the function PxTickDefine_Hnd. This

function has to be called within the Handler of the timer interrupts and registered as a
service for the timer interrupt (see subsection 7.7.1 on page 52).
The number of Ticks since the first call of PxTickDefine_Hnd can be queried via
PxTickGetCount.

The time passed since the first call of PxTickDefine_Hnd can be queried via
PxTickGetTimeInMilliSeconds.

The function PxGetTicksFromMilliSeconds(unsigned long ms) converts ms milliseconds to Ticks.

7.8.2 Delay Jobs

A delay job executes a function as a Handler after a predefined period of time. A Delay Job
object can be requested from an object pool via PxDelayRequest (and PxDelayRequest_NoWait
and PxDelayRequest_EvWait).
With the system services
PxDelaySched(PxDelay_t delayId, PxTicks_t ticks, void (handler )(PxArg_t), PxArg_t arg)

and
PxDelaySched_Hnd(PxDelay_t delayId, PxTicks_t ticks, void (handler)(PxArg_t), PxArg_t arg)

a function can be registered for subsequent processing. In this context, delayId is the
Handle of the delay object, ticks the number of Ticks after which the function is to be
executed, handler the pointer to the function to be executed, and arg the argument passed
to the function.

HighTec EDV-Systeme GmbH 55

Users Guide V1.1 7.8 Timer functionality

In the below example, a Handler function is periodically called by repeatedly triggering

execution from within in the function itself:
void handler_function(PxDelay_t delay)
{
PxTicks_t ticks;
PxError_t error;

...

ticks = PxGetTicksFromMillis(100);
error = PxDelaySched_Hnd(delay,ticks,handler_function,delay);

...
}

...

void TaskFunc()
{
...

PxDelay_t delay;
PxTicks_t ticks;
PxError_t error;

...

delay = PxDelayRequest(defaultopool);

if(PxDelayIdIsValid(delay))
{
ticks = PxGetTicksFromMillis(100);
error = PxDelaySched(delay,ticks,handler_function,delay);
if(error != PXERR_NOERROR)
{
do_error_handling();
}

...

...
}

7.8.3 Timeout objects and periodical timers

A typical application for a Delay Job Handler is sending a timeout event to a Task.
Timeout objects can be used to avoid having to implement this action over again. A
Timeout object can be requested in the following way:
PxTo_t to = PxToRequest(PxOpool_t opool,PxTicks_t ticks,PxEvents_t ev)

The parameters have the following meaning:

HighTec EDV-Systeme GmbH 56

Users Guide V1.1 7.9 Access to peripherals

opool : the object pool from which the timeout object is to be taken
ticks : the number of Ticks after which the Events are to be sent
ev : the Events to be sent after expiry of the timeout
The timer starts after the function call PxToStart(PxTo_t to) and be terminated via PxToStop(PxTo_t to)
if it is not yet expired.
Periodical timers (PxPe_t) differ from timeout objects in that they do not just send a
single timeout Event but periodical ones.

7.9 Access to peripherals

There are two ways of accessing peripheral registers: a Task in Usermode0 can access
peripheral registers via system calls if it has explicit permission; a Task in Usermode1 has
full access to peripheral registers.

7.9.1 Access in Usermode1

In Usermode1 a Task has direct access to peripheral registers insofar as this is permitted
by the hardware. This has the advantage that peripheral registers can be read and written
fast.
The disadvantage of this method is that the Task has access to all the registers to which
the hardware has granted read/write permission, not only to those the Task actually
needs. Erroneous access operations are thus possible.

7.9.2 Access via system calls

In Usermode0 a Task can access peripheral registers for read/write operations solely via
system calls. Thus, peripheral access is slower in Usermode0 than in Usermode1.
In Usermode0 a Task can have read/write permission granted for certain registers. Under
safety aspects this is an advantage over direct access.
If a Task wishes to access peripheral registers via system calls, it has to have access permis-
sion PXACCESS_REGISTERS (see subsection 3.5.3 on page 21). Furthermore, the address
areas of the desired registers in the extended memory areas of the Task (PxTaskSpec_T.ts_protect_region,
see subsubsection 7.2.3.2 on page 36) must be defined with the required access rights (read
and/or write).
The following system function is available for reading a peripheral register:
PxInt_t PxRegisterRead(PxInt_t *register)

This function receives the address of the desired register as a parameter and returns the
contend of the register, zero in case of an error.

Note:
If the function returns zero, it cannot be determined whether this is
the actual content of the register or an erroneous access operation.

HighTec EDV-Systeme GmbH 57

Users Guide V1.1 7.10 The abort mechanism

The function
PxError_t PxRegisterWrite(PxInt_t *register, PxInt_t value)

writes the value value into the register with the address register . If the access was success-
ful, the function will return PXERR_NOERROR; in case of an error, it will return either
PXERR_PROT_ILL_REGION or PXERR_ACCESS_RIGHT.

With the function

PxError_t PxRegisterSetMask(PxInt_t *register, PxInt_t mask, PxInt_t value)

the bits masked in mask in the register register are set to the value stated in value . If the
access was successful, the function will return PXERR_NOERROR; in case of an error, it
will return either PXERR_PROT_ILL_REGION or PXERR_ACCESS_RIGHT.

7.10 The abort mechanism

PxExpectAbort makes it possible to abort the execution of a function from within another
Task. The function must have been started via PxExpectAbort(ev,func,params ...) . The pa-
rameters have the following meaning:
ev : the Events causing the abort of the function
func : the function to be executed func may have random parameters, yet it may not
return any values
params : a list of the parameters passed to func
PxExpectAbort returns the Event, which has caused the abort, or zero if the function was
regularly terminated.
In the following example the function func is called in Task1 via PxExpectAbort. By sending
the Event EV_ABORT Task2 aborts the execution of the function.
...

void func(int i)
{
...
}

void Task1Func()
{
...

PxEvents_t retval;

...

retval = PxExpectAbort(EV_ABORT,func,42);

if(retval == 0) // function was regularly terminated

{
...

HighTec EDV-Systeme GmbH 58

Users Guide V1.1 7.10 The abort mechanism

}
else // the function was aborted
{
...
}

...
}

void Task2Func()
{

...

PxTaskSignalEvents(Task1,EV_ABORT);

...
}
...

HighTec EDV-Systeme GmbH 59

8 Further information
In addition to the basic functionalities of an operating system, PXROS-HR provides
supplementary services.

8.1 PxSysInfo services

The PxSysInfo services make it possible to access information on the internal condition
of the system, such as the number of used objects or the properties of a certain object.
The following example shows how the number of free objects within a PXROS-HR system
is determined:
int CountFreeObjects(void)
{
int i;
int freeObjects = 0;
PxObj_t obj;
volatile _PxObjType_t otype;
PxUInt_t numObjects;

/*
* request number of all objects within the system
*/
numObjects = PxSysInfoGetNumberOfObjects();

/*
* iterate over objects and request properties
*/
for (i = 0; i < numObjects; i++)
{
/*
* request object ID and type
*/
obj = PxObjIdSet(i);
otype = PxSysInfoGetObjType(obj);

if (otype == _PXObjIllObject)
{
/*
* list of objects is processed
*/
break;
}

if (otype == _PXObjUnused)
{
/*
* count free objects
*/
freeObjects++;
}
Users Guide V1.1 8.2 The Nameserver

}
return freeObjects;
}

8.2 The Nameserver

The Nameserver is a central service, which makes it possible to publish any information
under a unique identifier. Via this identifier, any Task can receive a copy of this information
from the Nameserver.
Publishing an information is achieved by the function PxNameRegister(PxNameId_t id, PxSize_t size, void co
The parameters have the following meaning:
id : name by which to register the data
size : size of the data buffer to be registered
obj : pointer to the data buffer to be registered
Registered information can be accessed via
PxNameQuery(PxNameId_t id, PxSize_t buf_size, void buf, PxSize_t info_size)

The parameters have the following meaning:

id : name by which the requested information is registered
buf size : size of the transferred data buffer
buf : buffer for the requested data
info size : size of the returned data buffer
An identifier consists of four bytes in the range from 1 to 254, e.g. 42.21.7.33 .

Note:
Addresses starting with 1 are reserved; applications should not use
the address space 1.x.x.x.

Before the Nameserver can be utilised, it has to be initialised and started.

This should be done by the Inittask because then the Nameserver is available
at the time the application Tasks are started. The Nameserver is started via
PxNamesrvInit(PxUChar_t srvprio,PxAligned_t membase, PxSize_t memsize). The parameters
have the following meaning:
srvprio : priority of the Nameserver Task
membase : beginning of the memory area of the Nameserver Task
memsize : size of the memory area of the Nameserver Task

HighTec EDV-Systeme GmbH 61

Users Guide V1.1 8.3 Reloading Tasks

8.3 Reloading Tasks

PXROS-HR makes it possible to reload and unload Tasks within a running system.
To use reloadable Tasks, the PxMonitor Task has to be linked to the basic system (libpx-
monitor.a), and pxmonitor.h has to be included. Apart from this, the basic system has to
make the address space available for loading the Tasks into. The Tasks have access only
to these areas.
When linking reloaded Tasks, care has to be taken that they are linked to the correct
addresses.
For each reloaded Task, an instance of PxMonitor has to be created during runtime. This
is donce via PxMonitorInitTcp(int inst , PxChar_t prio, unsigned short port). The parameters
have the following meaning:
inst : number of the instance
prio : priority of the monitor instance
port : the port where the tcp connection for reloading is to be opened.
Since a reloaded Task has no linking connection to the rest of the system, the use of a
Nameserver is absolutely necessary if from within this Task data or objects of the basic
system are to be accessed.
Examples for creating and using reloadable Tasks can be found in the incluced sample
code.

8.4 PXROS-HR Service Task

A Service Task is required in the following situations:
1. if a message is to be released by a Handler
2. if a Task is to be terminated via PxDie
3. if reloadable Tasks are used
Any Task can be declared as a Service Task via PxServiceTaskInit . If an-
other Service Task was already created, the function returns the error message
PXERR_TASK_DIESRV_INITIALIZED.

A Service Task has to wait for the Events PXSERVICE_HND_MSGREL and

PXSERVICE_TASK_DIED and react accordingly.

The Service Task has to provide a Service Mailbox for handling

PXSERVICE_HND_MSGREL Events. The PxMsgrelService function reads and at the
same time releases the message objects from the Service Mailbox.
For handling PXSERVICE_TASK_DIED Events, the Service Task has to call the PxDieService
function.
Example:

HighTec EDV-Systeme GmbH 62

Users Guide V1.1 8.5 Event logging

PxError_t ServiceTaskCode(void)
{
PxMbx_t relmbx;
PxEvents_t ev;
PxError_t err;
relmbx = PxMbxRequest(PXOpoolTaskdefault);
/* or, if the local Mailbox is otherwise unused:
relmbx = PxTaskGetMbx(PxGetId());
*/

if (PxMbxIdError(relmbx) != PXERR_NOERROR)
return PxMbxIdError(relmbx);

// register as Service Task

err = PxServiceTaskInit();

if (err != PXERR_NOERROR)
return err;

// register the Release Service Mailbox

err = PxMsgrelServiceInit(relmbx);
if (err != PXERR_NOERROR)
return err;

while(1)
{
ev = PxAwaitEvents(PXSERVICE_TASK_DIED | PXSERVICE_HND_MSGREL);

// a Task is terminated
if (ev & PXSERVICE_TASK_DIED)
{
err = PxDieService();
if (err != PXERR_NOERROR)
do_error_handling();
}

// a message is released
if (ev & PXSERVICE_HND_MSGREL)
{
err = PxMsgrelService();
if (PxMsgIdError( msg) != PXERR_NOERROR)
do_error_handling();
}
}
}

8.5 Event logging

PXROS-HR provides a mechanism for logging system events, e.g. if a system function is
called or a message received. The occurrence of events is recorded together with a time
stamp in a ring buffer, which has to be made available by the application. The application
can define, which types of events are to be logged.

HighTec EDV-Systeme GmbH 63

Users Guide V1.1 8.5 Event logging

8.5.1 The internal trace mechanism

The application can provide a buffer via PxTraceAssignBuffer(PxUChar_t buf, PxULong_t num).
The buf parameter has to point to a buffer, which was created by the application. num
states the number of entries. The size of an entry is 24 bytes, i.e. buf has to have a size of
24 num bytes. A renewed call of PxTraceAssignBuffer replaces the previous buffer with a
new one.
The PxTraceGetBuffer(PxOpool_t opool) function returns the trace buffer or a message con-
taining the buffer. The opool parameter contains the object pool, from which the message
object is to be taken.
The behaviour of the trace mechanism can be influenced via PxTraceCtrl(PxTraceCtrl_t cmd,PxArg_t arg).
In this context, cmd is a command, and arg the corresponding argument (for a description
of the commands, see the PXROS-HR reference manual).

8.5.2 PxView
An analysis of the trace buffer can be carried out at will, yet the use of the PxView tool
is recommended. The PxView library has to be included for this purpose (libpxview.a,
and the header file pxview.h).
The PxView library provides certain functionalities, which make it possible to manipulate
the trace mechanism, and to pass logged data via communication interface to the PxView-
Client, which carries out the display of the logged data.
For information on the use of PxView, see the PxView reference manual.

HighTec EDV-Systeme GmbH 64

Part III

Appendix
A Example code
A.1 For starters: a simple application
#include <pxdef.h>

// Priority of the Inittask after initialisation

#define MIN_PRIO 31

// Priority of Task1
#define TASK1_PRIO 4

#define PXROS_NAMESIZE 12
#define SYSMEMSIZE 20000
#define TASK1MEMSIZE 10000

#define INITTASK_STACKSIZE 200

#define INITTASK_INTSTACKSIZE 32

#define TASK1_STACKSIZE 200

#define TASK1_INTSTACKSIZE 32

// Function prototypes

// Task function of the Inittask

static void InitTask_Func(PxTask_t myID,
PxMbx_t myMailbox,
PxEvents_t myActivationEvents);

// Task function of Task1

static void Task1_Func(PxTask_t myID,
PxMbx_t myMailbox,
PxEvents_t myActivationEvents);

// System data areas

extern PxUInt_t PxTricSystemRodataLowerBound;
extern PxUInt_t PxTricSystemRodataUpperBound;

extern PxUInt_t PxTricSystemIntDataLowerBound;

extern PxUInt_t PxTricSystemIntDataUpperBound;

extern PxUInt_t PxTricSystemExtCodeLowerBound;

extern PxUInt_t PxTricSystemExtCodeUpperBound;

extern PxUInt_t PxTricSystemRamBegin;

extern PxUInt_t PxTricSystemRamEnd;
Users Guide V1.1 A.1 For starters: a simple application

extern PxUInt_t PxTricSystemDataLowerBound[];

extern PxUInt_t PxTricSystemDataUpperBound[];

extern unsigned int INIT_DATA_BASE;

extern unsigned int INIT_DATA_END;

extern unsigned int TASK1_DATA_BASE;

extern unsigned int TASK1_DATA_END;

#pragma section .systemmemory 8 aw

PxAligned_t Sysmem[(SYSMEMSIZE + sizeof(PxAligned_t) - 1)/sizeof(PxAligned_t)];
#pragma section

PxAligned_t inittask_stack[INITTASK_STACKSIZE];
PxAligned_t inittask_intstack[INITTASK_INTSTACKSIZE];

#pragma section .task1memory 8 aw

PxAligned_t Task1mem[(TASK1MEMSIZE + sizeof(PxAligned_t) - 1)/sizeof(PxAligned_t)];
#pragma section

#pragma section .task1stack 8 aw

PxAligned_t task1task_stack[TASK1_STACKSIZE];
PxAligned_t task1task_intstack[TASK1_INTSTACKSIZE];
#pragma section

// Memory context of Inittask

static const PxTaskContext_T InitTaskContext =
{
.protection[0].lowerBound = (PxUInt_t)&PxTricSystemRodataLowerBound,
.protection[0].upperBound = (PxUInt_t)&PxTricSystemRodataUpperBound,
.protection[0].prot = ReadProtection,

.protection[1].lowerBound = (PxUInt_t)&INIT_DATA_BASE,
.protection[1].upperBound = (PxUInt_t)&INIT_DATA_END,
.protection[1].prot = WRProtection,
};

// Specification of Inittask
static const PxTaskSpec_T InitTaskSpec =
{
.ts_name = "InitTask",
.ts_fun = InitTask_Func,
.ts_mc = PXMcSystemdefault,
.ts_opool = PXOpoolSystemdefault,
.ts_prio = 0,
.ts_privileges = PXUser1Privilege,
.ts_context = &InitTaskContext,
.ts_taskstack.stk_type = PXStackFall,
.ts_taskstack.stk_size = PXStackDontCheck,
.ts_taskstack.stk_src.stk = &inittask_stack[INITTASK_STACKSIZE],
.ts_inttaskstack.stk_type = PXStackFall,
.ts_inttaskstack.stk_size = PXStackDontCheck,

HighTec EDV-Systeme GmbH 67

Users Guide V1.1 A.1 For starters: a simple application

.ts_inttaskstack.stk_src.stk = &inittask_intstack[INITTASK_INTSTACKSIZE],
.ts_abortstacksize = 0
};

// Memory context of Task1

static const PxTaskContext_T Task1Context =
{
.protection[0].lowerBound = (PxUInt_t)&PxTricSystemRodataLowerBound,
.protection[0].upperBound = (PxUInt_t)&PxTricSystemRodataUpperBound,
.protection[0].prot = ReadProtection,

.protection[1].lowerBound = (PxUInt_t)&TASK1_DATA_BASE,
.protection[1].upperBound = (PxUInt_t)&TASK1_DATA_END,
.protection[1].prot = WRProtection,
};

// Specification of Task1
static const PxTaskSpec_T Task1Spec =
{
.ts_name = "Task1",
.ts_fun = Task1_Func,
.ts_mc = PXMcSystemdefault,
.ts_opool = PXOpoolSystemdefault,
.ts_prio = 0,
.ts_privileges = PXUser1Privilege,
.ts_context = &Task1Context,
.ts_taskstack.stk_type = PXStackFall,
.ts_taskstack.stk_size = PXStackDontCheck,
.ts_taskstack.stk_src.stk = &task1_stack[TASK1_STACKSIZE],
.ts_inttaskstack.stk_type = PXStackFall,
.ts_inttaskstack.stk_size = PXStackDontCheck,
.ts_inttaskstack.stk_src.stk = &task1_intstack[TASK1_INTSTACKSIZE],
.ts_abortstacksize = 0
};

// PXROS-HR system specification

static const PxInitSpec_T InitSpec =
{
.is_sysmc_type = PXMcVarsized,
.is_sysmc_size = 0,
.is_sysmc_blk = Sysmem,
.is_sysmc_blksize = SYSMEMSIZE,
.is_obj_number = 100,
.is_obj_namelength = PXROS_NAMESIZE,
.is_inittask = &InitTaskSpec,
.is_monitoring = 0,
.is_schedext = 0,

/* protection definition */
.is_sys_data_protection[0].lowerBound = (PxUInt_t)&PxTricSystemRamBegin,
.is_sys_data_protection[0].upperBound = (PxUInt_t)&PxTricSystemRamEnd,
.is_sys_data_protection[0].prot = ReadProtection,

.is_sys_data_protection[1].lowerBound = (PxUInt_t)&PxTricSystemDataLowerBound,

HighTec EDV-Systeme GmbH 68

Users Guide V1.1 A.1 For starters: a simple application

.is_sys_data_protection[1].upperBound = (PxUInt_t)&PxTricSystemDataUpperBound,
.is_sys_data_protection[1].prot = WRProtection,

.is_sys_data_protection[2].lowerBound = (PxUInt_t)&PxTricSystemIntDataLowerBound,
.is_sys_data_protection[2].upperBound = (PxUInt_t)&PxTricSystemIntDataUpperBound,
.is_sys_data_protection[2].prot = WRProtection,

.is_sys_data_protection[3].lowerBound = (PxUInt_t)0,
.is_sys_data_protection[3].upperBound = (PxUInt_t)0,
.is_sys_data_protection[3].prot = NoAccessProtection,

.is_sys_code_protection[0].lowerBound = (PxUInt_t)&PxTricSystemExtCodeLowerBound,
.is_sys_code_protection[0].upperBound = (PxUInt_t)&PxTricSystemExtCodeUpperBound,
.is_sys_code_protection[0].prot = XProtection,

.is_task_code_protection[0].lowerBound = (PxUInt_t)&PxTricSystemExtCodeLowerBound,
.is_task_code_protection[0].upperBound = (PxUInt_t)&PxTricSystemExtCodeUpperBound,
.is_task_code_protection[0].prot = XProtection,
};

// Code of Inittask
static void InitTask_Func(PxTask_t myID,
PxMbx_t myMailbox,
PxEvents_t myActivationEvents)
{
PxTask_t taskID = PxTaskCreate(PXOpoolSystemdefault,
&Task1Spec,
TASK1_PRIO,
0);
PxTaskSetPrio(myID,MIN_PRIO);
}

// Code of Task function Task1_Func

static void Task1_Func(PxTask_t myID,
PxMbx_t myMailbox,
PxEvents_t myActivationEvents)
{
// Declarations and initialisation
int foo = 0;
int bar;

if(myActivationEvents == EV_ACT_EV1)
{
bar = 1;
}
else
{
bar = 42;
}

// Main loop

HighTec EDV-Systeme GmbH 69

Users Guide V1.1 A.2 Data exchange between Handler and Task

while(1)
{
// parallel waiting for events and messages
PxMsgEvent_t msgev;
msgev = PxMsgReceive_EvWait(myMailbox,EV_EVENT_MASK);
if(PxMsgIdIsValid(msgev.msg))
{
// message received
do_sth_with_msg(msgev.msg);
}

if(msgev.events != 0)
{
// event received
do_sth_with_events(msgev.events);
}
}
}

int main(void)
{
PxError_t error;

error = PxInit(&InitSpec);
if (error != PXERR_NOERROR)
{
PxPanic();
return 1;
}
return 0;
}

A.2 Data exchange between Handler and Task

struct
{
PxTask_t commTask; // TaskID
PxEvents_t commEv; // Data-Ready event
PxUChar commMem[0]; // Memory areas of the communication structure
} TaskHandlerComm;

#define MY_HANDLER_EVENT 1

#define COMM_BUFFER_SIZE 512

void HandlerFunc(PxArg_t arg);

TaskFunc(PxTask_t myID, PxMbx_t myMailbox, PxEvents_t myActivationEvents)

{
struct TaskHandlerComm *myTaskHandlerComm;
PxMsg_t commMsg;

...

HighTec EDV-Systeme GmbH 70

Users Guide V1.1 A.2 Data exchange between Handler and Task

// Requesting a message
// Memory has to be the same system memory class
//
commMsg = PxMsgRequest(sizeof(struct TaskHandlerComm) + COMM_BUFFERSIZE,
PXMcSystemdefault,
PXOpoolTaskdefault);

if (!PxMsgIdIsValid(commMsg))
{
PxPanic();
}

// Initialising the communication object

myTaskHandlerComm = (struct TaskHandlerComm*)PxMsgGetData(commMsg);
myTaskHandlerComm->commTask = myID;
MyTaskHandlerComm->commEv = MY_HANDLER_EVENT;

// Installing Handler with communication structure

// as an argument
PxIntInstallFastHandler(COMM_INTERRUPT,
(void (*) (PxArg_t)) HandlerFunc,
myTaskHandlerComm);

while (1)
{
...
if (ev & MY_HANDLER_EVENT)
{
// Handler has received data and entered
// them in communication structure
ProcessInputData(myCommMem);
}
...
}
}

void HandlerFunc(PxArg_t arg)

{
struct TaskHandlerComm *myTaskHandlerComm;
PxUChar_t byte;

myTaskHandlerComm = (struct TaskHandlerComm *) arg;

// Store input data in communication structure

byte = GetInputByte();
StoreInputData(myTaskHandlerComm->commMem);

if (DataReadyForTask())
{
// Complete set of data received, Task is
// informed

HighTec EDV-Systeme GmbH 71

Users Guide V1.1 A.3 Messagepools

PxTaskSignalEvents_Hnd(myTaskHandlerComm->commTask,
myTaskHandlerComm->commEv);
}
}

A.3 Messagepools
A.3.1 Creating a Messagepool

// creates a new Mailbox as a Messagepool

// and enters "cnt" new Messages with data buffers
// of "size" bytes size in this Mailbox
// Objects are extracted from "srcpool", memory from "srcmc"
// Messages have "poolmbx" as their release Mailbox,
// i.e. they are stored here after release.

PxMbx_t MsgPoolCreate(PxUInt_t cnt,

PxSize_t size,
PxMc_t srcmc,
PxOpool_t srcopool)
{
PxMbx_t poolmbx;
PxError_t err;
PxTmode_t oldmode;
PxMsg_t msg;

// Avoid interruptions
oldmode = PxSetModebits(PXTmodeDisableAborts | PXTmodeDisableRemprocs);

// Create new Mailbox

poolmbx = PxMbxRequest_NoWait(srcopool);

if (!PxMbxIdIsValid(Poolmbx))
{
// Creation error
PxSetError(poolmbx.error);
PxClearModebits(oldmode);
return poolmbx;
}

// Request "cnt" Messages and store in Mailbox

while (cnt--)
{
// Request Message
msg = PxMsgRequest_NoWait(size, srcmc, srcopool);
if (PxMsgIdIsValid(msg))
{
// Install release Mailbox
PxMsgInstallRelmbx(msg, poolmbx);

// Message is stored in Messagepool

PxMsgSend(msg, poolmbx);
}
else

HighTec EDV-Systeme GmbH 72

Users Guide V1.1 A.3 Messagepools

{
// Error has occurred, Messagepool is
// deleted
err = msg.error;

// Release existing Messages

poolmbx = MsgPoolDelete(Poolmbx);
poolmbx.error = err;
PxSetError(poolmbx.error);
break;
}
}

// Reset mode bits

PxClearModebits(oldmode);

// Return Messagepool
return poolmbx;
}

A.3.2 Deleting a Messagepool

// Deletes a Messagepool, which was created via
// MsgPoolCreate. All concerned Messages must
// be present within the Messagepool.
// If a pool Message is deleted after
// deletion of the Messagepool, a
// "PXERR_MBX_ILLMBX" will occur.
// Tasks may not wait at this Mailbox,
// otherwise Mailbox cannot be deleted.
PxMbx_t MsgPoolDelete(PxMbx_t poolmbx)
{
PxMsg_t msg;
PxTmode_t oldmode;

// Avoid interruptions
oldmode = PxSetModebits(PXTmodeDisableAborts | PXTmodeDisableRemprocs);

// Release all messages

for (msg = PxMsgReceive_NoWait(poolmbx); PxMsgIdIsValid(msg); )
{
PxMsgInstallRelmbx(msg, PxMbxIdInvalidate());
PxMsgRelease(msg);
}

// Reset mode bits

PxClearModebits(oldmode);

// Delete Mailbox
return PxMbxRelease(poolmbx);
}

HighTec EDV-Systeme GmbH 73