ProOSEK UsersGuide · Removed duplicate sect1 1.18 30.09.2004 haberstu Fixed typos 1.17 03.08.2004 haberstu Fixed typos 1.16 03.08.2004 haberstu Removed Version Number Documented

ProOSEK UsersGuideBuild–Version 20050623

Revision 1.20 (UsersGuide.pdf )

Copyright c©1996 - 2003 3SOFT GmbH

ALL RIGHTS RESERVED. No part of this publication may be copied in any form, by pho-tocopy, microfilm, retrieval system, or by any other means now known or hereafter inventedwithout the prior written permission of 3SOFT GmbH.

ProOSEKTM is a registered trademark of 3SOFT GmbH.

All other trademarks used in this document are the property of their respective owners.

3SOFT GmbH Frauenweiherstr. 1491058 ErlangenGERMANY

support telephone:+49 - 9131 - 7701 - 360

support fax: +49 - 9131 - 7701 - 369

http://www.3SOFT.de

Revision History

Editor Description Rev. Releasedatethse2247 RT-Id: 5001 added role for AutosarOS build 1.20 16.06.2005drothler RT-Id: 4249

explained USERESSCHEDULER1.19 13.06.2005

haberstu RT-Id: 4181Removed duplicate sect1

1.18 30.09.2004

haberstu Fixed typos 1.17 03.08.2004haberstu Fixed typos 1.16 03.08.2004haberstu Removed Version Number

Documented Build-Version and Revision1.15 03.08.2004

herrmanu documented dot usage 1.14 08.07.2004herrmanu improved documentation of StartOS(), fixed

repetition of GetMessageStatus()1.13 29.06.2004

herrmanu improved version numbers 1.12 28.06.2004herrmanu adapted documentation of ProjectWizard 1.11 03.06.2004

http://www.3SOFT.de

3

haberstu Reviewed und Fehler korrigiert 1.10 14.05.2004herrmanu spell checked 1.9 12.05.2004herrmanu first ProOSEK Version 1.8 12.05.2004herrmanu preliminary adaption for tresos/ProOSEK

merge1.7 11.05.2004

herrmanu clarifications on alarms, callback, orti stuff 1.6 10.05.2004herrmanu added Isr hooks 1.5 10.05.2004herrmanu minor corrections, corrected description of

SetRelAlarm1.4 10.05.2004

haberstu tresos version 1.3 29.04.2004haberstu Added ProOSEK title image 1.2 28.04.2004herrmanu added ReleaseNotes 1.1 08.10.2003herrmanu reworked for COM30, reworked ERRNO,

fixed typos0.3 02.10.2003

haberstu Added ErrorCodes 0.2 15.09.2003haberstu Initial Version 0.1 22.08.2003

Copyright c© 2003 3Soft GmbH

Contents

1 ProOSEK Overview 13

1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.2 How to interpret Build and Revision . . . . . . . . . . . . . . . . . . . . 14

1.3 A Static Operating System . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.4 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.4.1 Multitasking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.4.2 Task Types and Conformance Classes . . . . . . . . . . . . . . 16

Basic Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Extended Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Conformance Classes . . . . . . . . . . . . . . . . . . . . . . . 16

1.4.3 Task State Transition . . . . . . . . . . . . . . . . . . . . . . . . 17

1.4.4 Task Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Preemptive Scheduling . . . . . . . . . . . . . . . . . . . . . . 18

Non-Preemptive Scheduling . . . . . . . . . . . . . . . . . . . . 19

Mixed Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . 20

Task Grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.4.5 Task Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.4.6 Task Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.5 Task Coordination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.5.1 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Deadlock Prevention . . . . . . . . . . . . . . . . . . . . . . . . 22

CONTENTS 5

Priority Inversion . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Scheduler Resource . . . . . . . . . . . . . . . . . . . . . . . . 23

Internal Resources . . . . . . . . . . . . . . . . . . . . . . . . . 24

Linked Resources . . . . . . . . . . . . . . . . . . . . . . . . . 24

Resource Control . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Restrictions while resources are held . . . . . . . . . . . . . . 25

1.5.2 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Event Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.5.3 Intertask Messages . . . . . . . . . . . . . . . . . . . . . . . . 26

1.6 Counters and Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.6.1 Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Counter Control . . . . . . . . . . . . . . . . . . . . . . . . . . 27

1.6.2 Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Alarm Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1.7 Interrupt Service Routines (ISRs) . . . . . . . . . . . . . . . . . . . . . 28

ISR Category 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

ISR Category 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Interrupt Control . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Architecture Issues . . . . . . . . . . . . . . . . . . . . . . . . . 29

Compiler Issues . . . . . . . . . . . . . . . . . . . . . . . . . . 30

1.8 Miscellaneous Features . . . . . . . . . . . . . . . . . . . . . . . . . . 30

1.8.1 System Startup and Shutdown . . . . . . . . . . . . . . . . . . 30

1.8.2 Hook Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

ErrorHook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

PreIsrHook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

PostIsrHook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

PreTaskHook . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

PostTaskHook . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

StartupHook . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

ShutDownHook . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

1.8.3 Debugging Support . . . . . . . . . . . . . . . . . . . . . . . . 33

1.8.4 The OS Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

CONTENTS 6

1.8.5 API Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

1.8.6 Version Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

1.8.7 The Extended Runtime Checker . . . . . . . . . . . . . . . . . 35

1.8.8 The Stack Checker . . . . . . . . . . . . . . . . . . . . . . . . . 35

1.8.9 Isr Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

2 Communication 38

2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

2.2 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

2.3 Message API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

2.4 Semantics of API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

2.4.1 Queued Messages . . . . . . . . . . . . . . . . . . . . . . . . . 40

2.4.2 Unqueued Messages . . . . . . . . . . . . . . . . . . . . . . . 41

WithCopy Messages . . . . . . . . . . . . . . . . . . . . . . . . 42

WithoutCopy Messages . . . . . . . . . . . . . . . . . . . . . . 42

2.4.3 Notification Mechanisms . . . . . . . . . . . . . . . . . . . . . . 43

2.4.4 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

2.5 Message setup files and macros . . . . . . . . . . . . . . . . . . . . . 44

2.5.1 COMUserData.h - Message data types . . . . . . . . . . . . . 44

2.5.2 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

3 Developing with ProOSEK 46

3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.2 Development Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

3.3 The Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

3.4 The File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

4 Configurator 50

4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4.2 The Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

4.3 File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4.3.1 Create a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

4.3.2 Open a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

CONTENTS 7

Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

4.3.3 Closing a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

4.3.4 Saving a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

4.4 Choosing a Target System . . . . . . . . . . . . . . . . . . . . . . . . . 59

4.4.1 Moving to a Different Target Architecture . . . . . . . . . . . . . 59

4.5 Managing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

4.5.1 Adding/Creating a New Object . . . . . . . . . . . . . . . . . . 61

4.5.2 Editing an Object . . . . . . . . . . . . . . . . . . . . . . . . . . 62

4.5.3 Duplicating an Object . . . . . . . . . . . . . . . . . . . . . . . 62

4.5.4 Deleting an Object . . . . . . . . . . . . . . . . . . . . . . . . . 62

4.5.5 Moving an Object . . . . . . . . . . . . . . . . . . . . . . . . . . 62

4.6 Managing Attributes and References . . . . . . . . . . . . . . . . . . . 63

Attributes and References . . . . . . . . . . . . . . . . . . . . . 63

Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

The Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Description of Attributes . . . . . . . . . . . . . . . . . . . . . . 65

4.6.1 The OS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Card: ”General” . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

4.6.2 Appmodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

4.6.3 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Card: ”General” . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Card: ”ACCESSORs” . . . . . . . . . . . . . . . . . . . . . . . 72

Card: ”RESOURCEs” . . . . . . . . . . . . . . . . . . . . . . . 73

Card: ”EVENTs” . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Card: ”AUTOSTART” . . . . . . . . . . . . . . . . . . . . . . . . 73

4.6.4 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Card: ”RESOURCEPROPERTY” . . . . . . . . . . . . . . . . . 73

4.6.5 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Card: ”General” . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

4.6.6 Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Card: ”General” . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

4.6.7 Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

CONTENTS 8

Card: ”General” . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Card: ”AUTOSTART” . . . . . . . . . . . . . . . . . . . . . . . . 78

Card: ”ACTION” . . . . . . . . . . . . . . . . . . . . . . . . . . 79

4.6.8 ISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Card: ”General” . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Card: ”ACCESSORs” and ”RESOURCEs” . . . . . . . . . . . . 82

4.6.9 The COM Object . . . . . . . . . . . . . . . . . . . . . . . . . . 82

4.6.10 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

4.6.11 The NM Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

4.7 Working with a Configuration . . . . . . . . . . . . . . . . . . . . . . . 86

4.7.1 Verifying a Configuration . . . . . . . . . . . . . . . . . . . . . . 86

4.7.2 Generating a System . . . . . . . . . . . . . . . . . . . . . . . 87

Generated Files . . . . . . . . . . . . . . . . . . . . . . . . . . 87

4.7.3 Generating a Template . . . . . . . . . . . . . . . . . . . . . . . 88

The Save File Dialog Box . . . . . . . . . . . . . . . . . . . . . 88

Generated Files . . . . . . . . . . . . . . . . . . . . . . . . . . 88

4.7.4 Generating a HTML Summary Page . . . . . . . . . . . . . . . 89

4.7.5 Generating ORTI Data . . . . . . . . . . . . . . . . . . . . . . . 89

4.7.6 Getting Memory Requirements . . . . . . . . . . . . . . . . . . 90

4.7.7 Working in Command-Line Mode . . . . . . . . . . . . . . . . . 90

Generator Command Line Options . . . . . . . . . . . . . . . . 91

Cnf2orti Command Line Options . . . . . . . . . . . . . . . . . 91

Usage examples . . . . . . . . . . . . . . . . . . . . . . . . . . 92

4.8 Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

4.9 Update Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

A ProOSEK OS API Reference 96

OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

ActivateTask() . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

AdvanceCounter() . . . . . . . . . . . . . . . . . . . . . . . . . 102

ALARMCALLBACK() . . . . . . . . . . . . . . . . . . . . . . . . 103

CancelAlarm() . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

CONTENTS 9

ChainTask() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

ClearEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

DeclareAlarm() . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

DeclareEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

DeclareResource() . . . . . . . . . . . . . . . . . . . . . . . . . 110

DeclareTask() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

DisableAllInterrupts() . . . . . . . . . . . . . . . . . . . . . . . . 112

EnableAllInterrupts() . . . . . . . . . . . . . . . . . . . . . . . . 113

ErrorHook() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

GetActiveApplicationMode() . . . . . . . . . . . . . . . . . . . . 115

GetAlarm() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

GetAlarmBase() . . . . . . . . . . . . . . . . . . . . . . . . . . 117

GetEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

GetResource() . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

GetTaskID() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

GetTaskState() . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

IAdvanceCounter() . . . . . . . . . . . . . . . . . . . . . . . . . 125

OSErrorGetServiceId() . . . . . . . . . . . . . . . . . . . . . . 126

OSError x1 x2() . . . . . . . . . . . . . . . . . . . . . . . . . . 127

PostTaskHook() . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

PreTaskHook() . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

ReleaseResource() . . . . . . . . . . . . . . . . . . . . . . . . 132

ResumeAllInterrupts() . . . . . . . . . . . . . . . . . . . . . . . 134

ResumeOSInterrupts() . . . . . . . . . . . . . . . . . . . . . . . 135

Schedule() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

SetEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

SetAbsAlarm() . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

SetRelAlarm() . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

ShutdownHook() . . . . . . . . . . . . . . . . . . . . . . . . . . 145

ShutdownOS() . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

StartOS() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

StartupHook() . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

CONTENTS 10

SuspendAllInterrupts() . . . . . . . . . . . . . . . . . . . . . . . 149

SuspendOSInterrupts() . . . . . . . . . . . . . . . . . . . . . . 150

TerminateTask() . . . . . . . . . . . . . . . . . . . . . . . . . . 151

WaitEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

B OSEK Communications API Reference 155

COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

StartCOM() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

MessageInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

SendMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . 159

ReceiveMessage() . . . . . . . . . . . . . . . . . . . . . . . . . 161

GetMessageStatus() . . . . . . . . . . . . . . . . . . . . . . . . 163

GetMessageResource() . . . . . . . . . . . . . . . . . . . . . . 164

ReleaseMessageResource() . . . . . . . . . . . . . . . . . . . 165

ReadFlag() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

ResetFlag() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

C OSEK Error Codes 168

Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

D ProOSEK Release Notes 186

Release Notes Configurator . . . . . . . . . . . . . . . . . . . . 186

E Tools 188

E.1 Dot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

List of Figures

3.1 ProOSEK developing process . . . . . . . . . . . . . . . . . . . . . . . 47

4.1 The Configurator at Start-up . . . . . . . . . . . . . . . . . . . . . . . . 52

4.2 Configurator main window - Objects view . . . . . . . . . . . . . . . . 53

4.3 Configurator main window - Files view . . . . . . . . . . . . . . . . . . 54

4.4 The File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

4.5 Opening OSEK Configuration Files . . . . . . . . . . . . . . . . . . . . 56

4.6 Opening OSEK Configuration Files . . . . . . . . . . . . . . . . . . . . 57

4.7 The System Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

4.8 Edit Menu in Objects View (right click on objects) . . . . . . . . . . . . 60

4.9 Edit Menu in Files View (right click on objects) . . . . . . . . . . . . . . 61

4.10 The Task Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

4.11 The OS Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

4.12 The TASK Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

4.13 Accessor list in the task editor . . . . . . . . . . . . . . . . . . . . . . . 72

4.14 The EVENT Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4.15 The COUNTER Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

4.16 The ALARM Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

4.17 The ALARM Editor - AUTOSTART card . . . . . . . . . . . . . . . . . 79

4.18 The ALARM Editor - ACTION card . . . . . . . . . . . . . . . . . . . . 80

4.19 The ISR Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

4.20 The COM Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

LIST OF FIGURES 12

4.21 The MESSAGE Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

4.22 The Menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

1ProOSEK Overview

1.1 Introduction

The ProOSEK R© kernel represents an implementation of the operating system stan-dard OSEK/VDX-OS 2.2.1 (OSEK 2.2.1). It follows the binding specification SB4which includes OIL2.3, OS2.2 and COM2.2.2.

The purpose of this chapter is to give an overview of the ProOSEK R© kernel. Itdescribes the concepts of OSEK 2.2.x. It is, however, not intended to replace theofficial OSEK specification.

Modern real-time systems are based on the complementary concepts of multitaskingand inter-task communications. A multitasking environment allows a real-time appli-cation to be constructed as a set of independent tasks, each with its own thread ofexecution and set of system resources. The inter-task communication facilities allowthese tasks to synchronize and communicate in order to coordinate their activities. InProOSEK R©, the inter-task communication facilities include resources, events, andmessages.

Another key facility in real-time systems is hardware interrupt handling, becauseinterrupts are the usual mechanism used to inform a system of external events.To get the fastest possible response to interrupts, interrupt service routines (ISRs)in ProOSEK R© run in a special context of their own outside the context of a task.

CHAPTER 1. PROOSEK OVERVIEW 14

Counters and alarms provide additional support for recurring events.

This chapter discusses the multitasking kernel, tasking facilities, inter-task commu-nication, and interrupt handling facilities, which are at the heart of the ProOSEK R©kernel.

As each target architecture is different, this may place certain constraints on aProOSEK R© system. Such architecture-specific details are discussed in a sepa-rate document: ProOSEK R© Architecture Notes. Please refer to the appropriatesupplement for the desired target system.

1.2 How to interpret Build and Revi-sion

This book has a build number and a revision number on the title page. The buildnumber is a 8 digits number representing the date on which the ProOSEK R© instal-lation was build. The revision number is the current revision from the revision historyon page 2.

When the content of ProOSEK R© User Guide changes the revision number alsochanges and an additional entry is added to the revision history describing thechanges in the document.

Appendix C and appendix D are automatically generated when the system is buildand therefore change with each release of ProOSEK R©. On each change of thebuild of the document the release notes and error code list therefore is exchanged.

1.3 A Static Operating System

The OSEK operating system specification is targeted at deeply embedded systemswith hard real-time constraints. In such systems, any non-deterministic behaviorthat might conflict with the real-time requirements should be avoided. Therefore thespecification defines OSEK as a static operating system. This means that systemobjects can never be created dynamically - the entire layout of the system, including


every single object, must be determined before the system is built.

The ProOSEK R© kernel implements this static notion of an operating system, thusno system services are provided to dynamically create new objects like tasks or re-sources. As a consequence, the application programmer must specify the layout ofhis or her application prior to starting the system. ProOSEK R© provides a graphi-cal tool, the Configurator, which supports the process of system configuration. TheConfigurator includes tools which can verify a configuration, generate an operatingsystem, calculate the amount of memory required for the system configured, gener-ate ORTI data where supported, and more. Please refer to Chapter 4, Configuratorfor a detailed discussion of these tools.

1.4 Tasks

It is often essential to organize an application into independent, though cooperating,programs. Each of these independent programs, while executing, is called a task. InProOSEK R©, tasks have immediate, shared access to most system resources, whilealso maintaining enough separate context to maintain individual threads of control.

1.4.1 Multitasking

Multitasking provides the fundamental mechanism for an application to control andreact to multiple, discrete real-world events. The ProOSEK R© kernel provides a basicmultitasking environment. Multitasking creates the appearance of many threadsrunning concurrently, when, in fact, the kernel interleaves their execution on thebasis of a scheduling algorithm. Each apparently independent program is called atask. Each task has its own context, which is the CPU environment and systemresources that the task sees each time it is scheduled to run by the kernel. Ona context switch, a task’s context is saved in the appropriate save area. A task’scontext includes:

• a thread of execution, that is, the task’s program counter

• the CPU registers

• a stack for dynamic variables and function calls


• kernel control structures

In ProOSEK R©, one important resource that is not part of a task’s context is memoryaddress space: all code executes in a single common address space (as embeddedsystems often have tight memory constraints).

1.4.2 Task Types and Conformance Classes

Task contexts are expensive resources in a light weight operating system likeProOSEK R©. In order to provide the best optimization possible, tasks are subdi-vided into two categories, basic and extended, depending on their synchronizationneeds.

Basic Tasks

The key property of a basic task is that it does not use blocking synchronizationto coordinate its activity with that of other tasks. Thus, basic tasks release theprocessor only if one of the following situations occurs:

• the task is terminated

• a higher priority task is scheduled

• an interrupt causes the processor to execute an interrupt service routine (ISR)

Extended Tasks

The key property of an extended task is that it may use blocking synchronization.In ProOSEK R©, the only system service that may block a task is WaitEvent() . Thisservice blocks if the specified event has not yet been set.

Conformance Classes

The OSEK specification describes a scalable operating system that can be opti-mized according to the needs of an application. The configurable capabilities are


described by conformance classes (CC). A conforming implementation of OSEKmust implement at least one of the four conformance classes defined by the OSEKspecification. ProOSEK R© supports all four of them. The characteristics of the fourconformance classes are listed in the following table:

Table 1.1: OSEK Conformance Classes

Characteristics BCC11

BasicConformanceClass 1

BCC2BasicConformanceClass 2

ECC12

ExtendedConformanceClass 1

ECC1ExtendedConformanceClass 2

Multiple requesting oftask activation

no yes no basic tasksonly

Multiple tasks per pri-ority

no yes no yes

Events allowed? no no yes yesResources allowed? no3 yes yes yesAlarms allowed? yes yes yes yes

1.4.3 Task State Transition

The kernel maintains the current state of each task in the system. A task changesfrom one state to another as the result of kernel function calls made by the applica-tion. As ProOSEK R© is a static operating system, there is no means of creating newtasks. Tasks are always present in the system.

The default task state is the suspended state. When activated, a task enters theready state. Only one task at a time is in the running state, that is the task thatcurrently holds the CPU. Depending on the type of the task, a fourth state may beapplicable: extended tasks are in the waiting state while they are waiting for an eventto be set.

1BCC: Basic Conformance Class2ECC: Extended Conformance Class3Can only use the resource RES SCHEDULER


1.4.4 Task Scheduling

Multitasking requires a scheduling algorithm to allocate the CPU between taskswhich are in the ready state. Scheduling in the ProOSEK R© kernel is always pri-ority driven. Priorities are assigned during configuration and cannot be changedduring runtime except using resources. It is possible to choose between fully pre-emptive scheduling, purely non-preemptive scheduling, and mixed scheduling. Thechoice of the scheduling algorithm is a static decision that must be made duringconfiguration, before the system is generated. It cannot be changed at run-time.

Preemptive Scheduling

With a preemptive scheduler, the kernel ensures that the CPU is allocated to thehighest priority task that is ready to run. This scheduling method is preemptive inthat if a task with a higher priority than the current task becomes ready to run, thekernel immediately saves the current task’s context and switches to the context ofthe higher priority task.

However, this action will only be performed as a result of a call to a system serviceby either the task currently running or an ISR running asynchronously to it. The nextTable Table 1.2 presents a full list of the scheduling points for preemptive scheduling.

Table 1.2: Scheduling Points for Preemptive Schedul-ing

Situation System ServiceActivation of a Task ActivateTask()Termination of a Task TerminateTask()

ChainTask()Explicit call to the scheduler Schedule()Task state transition to the waitingstate

WaitEvent()

Sending an event to a task SetEvent()Incrementing a counter

AdvanceCounter() 4

IAdvanceCounter()

Releasing a resource ReleaseResource()Leaving a category 2 ISR


Non-Preemptive Scheduling

With a non-preemptive scheduler, rescheduling can only occur at a subset of thescheduling points mentioned above. These are system services which explicitlyallow for rescheduling. Table 1.3 presents a full and complete list of ProOSEK R©scheduling points for non-preemptive scheduling. Scheduling Points for Non-Preemptive Scheduling

Table 1.3: Scheduling Points for Non-PreemptiveScheduling

Situation System ServiceTermination of a Task TerminateTask()

ChainTask()Explicit call to the scheduler Schedule()Task state transition to the waiting 5

stateWaitEvent()

WARNING

The use of non-preemptive scheduling can result in a high pri-ority task being delayed by a running task of lower priority if thelatter does not hit any scheduling points. Therefore, special caremust be taken for timing considerations in non-preemptive real-time systems.

4Point of rescheduling if an alarm is triggered which leads to a call of SetEvent() or ActivateTask()(also: ”IAdvanceCounter()”)

5In the case that the event which WaitEvent() should wait for is already set, then this is NOT apoint of rescheduling!


NOTE

The OSEK specification explicitly entitles conforming implemen-tations to restrict the use of system services that serve asscheduling points to top level functions. Application code whichdoes not comply to this restriction will run in a ProOSEK R© sys-tem, however, it may not be portable to other OSEK systems.

Mixed Scheduling

Mixed scheduling is a combination of preemptive and non-preemptive scheduling.The justification for a mixed scheduling algorithm is that in a fully preemptive systemthere might be reasons for introducing non-preemptive tasks, such as:

• A task must not be preempted for certain reasons.

• A task is so small that its execution time is in the same order of magnitude asthe time needed for a task switch.

• RAM which is used by the system to save task contexts needs to be usedeconomically.

When mixed scheduling is used, each task must specify whether it may be pre-empted or not.

Task Grouping

Groups of tasks can be defined by associating an internal resource with them. Sucha group of tasks behaves like a single task with the same priority as the highest oneof all tasks within the group.

• The group behaves like a non-preemtable task for tasks which have the sameor lower priority as the group (i.e. rescheduling takes place as described fornon-preemptive scheduling above).


• It behaves like a preemptable task for tasks that have a higher priority than thegroup (i.e. rescheduling takes place as described for preemptive schedulingabove).

1.4.5 Task Control

Table 1.4 gives an overview of the basic ProOSEK R© tasking routines. These rou-tines provide the means for task control and gaining run-time information. For adetailed description of the ProOSEK R© operating system services, see Appendix A.

Table 1.4: Services for Task Control

Service DescriptionActivateTask(), ChainTask() Activation of a taskGetTaskState() Get state of a taskTerminateTask(), ChainTask() Change the current task’s state to Sus-

pendedSchedule() Call the scheduler explicitlyGetTaskID() Returns the ID of the currently running task

1.4.6 Task Stacks

In order to optimize the stack requirements of an application, the Configurator sharesstacks of basic tasks of the same priority. This means that all basic tasks with thesame priority will use the same task stack!

1.5 Task Coordination

The complement to the multitasking routines described in Section 1.4, Tasks are thetask coordination facilities. These facilities permit independent tasks to coordinatetheir actions.

ProOSEK R© provides a set of task coordination mechanisms, including:


• Resources, for granting exclusive or semi-exclusive access to critical sectionsof code

• Events, for notification of changes to the environment (external or internal)

• Messages, for exchange of more complex information between tasks

1.5.1 Resources

In a multitasking environment, tasks typically share access to a number of physi-cal as well as system resources. In ProOSEK R© these include for example: codesections, the scheduler, memory, and hardware devices. In ProOSEK R©, Resourcesprovide a means to coordinate concurrent access to these shared facilities.

OSEK imposes restrictions on system services which often make the use of re-sources unnecessary. Resources are only needed in two cases:

• preemptive systems

• non-preemptive systems in which some tasks need to exclude other ISRs fromsystem resources.

For some architectures it makes sense to support the Resource concept for coordi-nation between tasks and interrupts as well. Please consult the Architecture Notesto find out whether a specific architecture offers this feature.

Deadlock Prevention

A deadlock occurs when two tasks wait for resources that are held each by the other.OSEK prevents deadlock situations by imposing a set of restrictions:

• a task makes the transition from ready to running only if all of the tasks re-sources are available.

• a task must not terminate nor enter the waiting state while it holds resources.

• multiple resources must be acquired and released in LIFO (last in first out)order. That means each task logically manages the resources it needs on astack.


• a task must not acquire a resource which it already holds (when required, thiscan be facilitated using linked resources. Refer to Linked Resources for moreinformation)

Priority Inversion

Priority inversion arises when a higher-priority task is forced to wait an indefiniteamount of time for a lower-priority task to complete. This situation can arise whenthe lower-priority task TL holds a resource that is required by the higher-priority taskTH. The task TH will not enter the running state as long as it cannot acquire theresource. The resource does not become available while TL holds it. However, anytask that has a priority between that of TL and that of TH can preempt TL if it doesnot request access to the resource. TH will see an indefinite number of lower-prioritytasks run while TL occupies the resource.

OSEK prevents this situation by imposing the priority ceiling protocol on its resourcemanagement. The precondition of this protocol is that priorities are relative. Thus,between two priority levels there is always room to introduce a new priority level.Priorities are calculated according to the following rules:

• when a task acquires a resource, the task’s priority is set to a value equal to orhigher than that of the highest-priority task TH that uses this resource at sometime in the application.

• the new priority of the task is lower than the priority of any task in the applica-tion which has higher priority than TH.

• once the task releases all its resources, the priority of the task is immediatelyreset to its old priority.

This protocol ensures that no task of lower priority than task TH will execute whiletask TL holds the resource. Task TL is executed preferentially until the moment itreleases its resources, thus enabling task TH to change into the running state.

Scheduler Resource

A preemptive task might be in a situation in which it must avoid preemptionby all means. For this purpose, the system provides a predefined resourceRES SCHEDULER. Acquisition of this resource deactivates the scheduler. Releas-ing RES SCHEDULER reactivates scheduling.


NOTE

Interrupts are received and processed independently of the cur-rent state of the scheduler.

Internal Resources

Internal resources are not visible to the user and are defined during configuration.Each task can be associated with at most one internal resource. Internal resourcesare automatically handled by ProOSEK R©. When a task enters the running stateit takes the resource. The resource is only released when the task is terminated,calls WaitEvent() and thus enters the waiting state or calls Schedule() . If the taskchanges into the preempted state then it still holds the resource. Refer to TaskGrouping for further information.

Linked Resources

Linked resources can be used in place of nested acquisitions of a single resource.A linked resource acts as a second copy of the resource. Linked resources can linkto RES SCHEDULER only if it is explicitly defined.

Resource Control

Table 1.5 provides an overview of the basic ProOSEK R© resource services. Theseroutines provide the means for getting and releasing resources. See Appendix A fora detailed description of the ProOSEK R© operating system services.

Table 1.5: Services for Resource Control

Description ServiceGet (acquire) a resource GetResource()Release a resource ReleaseResource()


Restrictions while resources are held

The system services TerminateTask(), ChainTask(), Schedule() and WaitEvent()must not be called while a resource is held. In the case that the architecture supportsresources for interrupt service routines, the ISR must not finish while a resource isheld. The only exception is internal resources as they are managed internally byProOSEK R©.

1.5.2 Events

In an embedded system it is often necessary to asynchronously inform a task of astate transition. This may be a value which is calculated by another task or an inputfrom a device that must be sent from the interrupt handler to a certain task.

An event is an exclusive signal which is assigned to an arbitrary extended task. Morethan one event can be assigned to the same task. A task may wait for one or moreevents and thus enter the waiting state. Any task (basic or extended) can set eventsfor arbitrary tasks. This causes the receiving task to enter the ready state if it hasbeen waiting for at least one of these events.

Event Control

Table 1.6 provides an overview of the basic ProOSEK R© event services. Theseroutines provide the tools for manipulating event services. See Appendix A for adetailed description of the ProOSEK R© operating system services.

Table 1.6: Services for Event Control

Description ServiceSet an Event of a specific task SetEvent()Wait for specific events WaitEvent()Get the events of a specific task GetEvent()Clear events ClearEvent()


1.5.3 Intertask Messages

Intertask messages are a special case of the ProOSEK R© communication library.Even if an application is not connected to a network and does not require fullmessage support, it can make use of local messages for intertask communication.Please refer to Chapter 2, Communication for a detailed discussion of messages.

1.6 Counters and Alarms

The ProOSEK R© operating system provides services to handle recurring events typ-ically associated with an interrupt. Such events may occur at regular intervals, suchas timer interrupts, or irregularly, such as interrupts transmitting the state of a certaindevice. The support of such events is divided into two elements:

• counters which register the occurrences of the events.

• alarms which are triggered when a counter reaches a certain value.

1.6.1 Counters

A counter consists of a current value, expressed in ticks, and a number of constantsdescribing the behavior of the counter. These include:

MAXALLOWEDVALUE the value at which the counter rolls over and restarts fromzero

MINCYCLE the minimum number of ticks a cyclic alarm associated with the countermust specify for expiration

TICKSPERBASE the number of ticks that are needed to reach a specific valuedefined by the user


Counter Control

Table 1.7 gives an overview of the basic ProOSEK R© counter services. See Ap-pendix A for a detailed description of the ProOSEK R© operating system services.

Table 1.7: Services for Counter Control

Description ServiceIncrement the counter value from task level AdvanceCounter()Increment the counter value from ISR level IAdvanceCounter()

1.6.2 Alarms

Counters are used to register the occurrence of certain events. Typically, when acertain number of these events have occurred, some action needs to be taken bythe application. Alarms are the mechanism used to connect a counter to an action -either the activation of a task, the setting of an event, or the running of a user-definedalarm-callback routine.

Each alarm is associated with exactly one counter, however multiple alarms canuse the same counter. When the counter reaches a user-defined value the alarmexpires. Alarm expiration results in the defined action being carried out (i.e. taskactivation, setting of an event or running of an alarm-callback routine). The actiondepends on the alarms static properties.

It may be:

• Activating a task

• Setting of an event or

• Running of an alarm-callback routine. The callback must be defined usingALARMCALLBACK(name) . The callback is run in the current context of theAdvanceCounter() call. I.e. for timer counter it is run on interrupt level. Sincethe operating system does not know about the stack usage of this callback, theuser must care for this. It might be even necessary to introduce a dummy ISRto artificially increase the interrupt stack size. Generally it is a good idea to doonly small things in a callback (setting a global variable, etc.)


Alarm Control

Table 1.8 gives an overview of the basic ProOSEK R© alarm services. These rou-tines provide the mechanism for manipulating alarms and getting information aboutalarms. See Appendix A for a detailed description of the ProOSEK R© operatingsystem services.

Table 1.8: Services for Alarm Control

Description ServiceSet or activate an alarm SetRelAlarm()

SetAbsAlarm()Cancel an alarm CancelAlarm()Get information about an alarm andthe counter to which the alarm be-longs

GetAlarm()GetAlarmBase()

1.7 Interrupt Service Routines (ISRs)

ISRs are typically short pieces of code which differ in their use of system ser-vices. OSEK defines two categories of ISRs, all of which are implemented in theProOSEK R© kernel.

Irrespective of the category, no scheduling will take place inside an interrupt rou-tine. Rescheduling may take place once the execution of a category 2 interrupthas finished as long as it does not return to another interrupt routine, and no otherinterrupts are pending.

ISR Category 1

ISRs of this category do not call the operating system. After the processing of theinterrupt the execution of the application code will continue at the very instruction atwhich it was interrupted. This is the fastest category of ISR.


ISR Category 2

ISRs of this category may call system services. Therefore, the system generator willprovide an execution frame for the ISR. The user code for the ISR will be insertedinto this frame when the system is generated.

NOTE

The application cannot call arbitrary system services from anISR. Please refer to the API appendices in order to find out whichroutines can be called from an interrupt.

Interrupt Control

Table 1.9 provides an overview of the basic ProOSEK R© interrupt services. Refer toAppendix A for a detailed description of the ProOSEK R© operating system services.

Table 1.9: Services for Interrupt Control

Description ServiceEnable or disable all category 2 interrupts ResumeOSInterrupts()

SuspendOSInterrupts()Enable or disable all interrupts(including category 1, nesting not allowed)

EnableAllInterrupts()DisableAllInterrupts()

Enable or disable all interrupts(including category 1, nesting allowed)

ResumeAllInterrupts()SuspendAllInterrupts()

Architecture Issues

On some architectures, there are only one or two hardware pins for an interrupt. Onsuch hardware systems, the interrupts are often connected to a dispatcher which willdetect the actual source of the interrupt. This may be due to a timer under-/overflow,


data sent or received on a serial device, etc.

Other architectures may provide prioritized interrupt handling for interrupt sources.In those cases a dispatcher is not required.

Please refer to the Architecture Supplement specific to your target architecture tolearn more about the implementation of interrupt handling.

Compiler Issues

Many compilers for embedded systems offer direct support for interrupt service rou-tines written in C through special keywords (for example, interrupt ). Whether sucha keyword is supported in ProOSEK R© depends on whether the compiler used offerssuch a keyword for the specific target architecture. Refer to the Architecture Notesfor your architecture.

1.8 Miscellaneous Features

1.8.1 System Startup and Shutdown

A pair of system services, StartOS() and ShutdownOS() are provided to startProOSEK R© and shut it down.

StartOS() must be called by an application before any other service call.

ShutdownOS() is called by the kernel when it incurs a fatal error. It may be calledexplicitly by the application as well. After this call, the ProOSEK R© system servicesare no longer available.

1.8.2 Hook Routines

ProOSEK R© supports a number of hook routines which are called at specific pointsin the system. They execute at a higher priority than any other task in the system.


The following needs to be done in order to establish a hook:

• A function must be implemented that uses the exact interface of the hook.

• The hook must be included into your configuration by checking the appropriatecheck box in the Configurator (see Section 4.6.1, The OS Object).

This section gives an overview of the hooks and when they are executed. Pleaserefer to Appendix A for the hook interface specifications.

NOTE

The application cannot arbitrarily call system services from ahook. Please refer to the API appendices in order to find outwhich routines can be called by individual hooks. Violating thisrule may cause the whole system to behave in an unpredictablemanner.

ErrorHook

This hook is called by the kernel when a system service returns anything other thanE OK. More information on the cause of the error can be retrieved by using theservices OSErrorGetServiceId() and OSError x1 x2(). GetTaskID() can be usedto get the ID of the task which produced the error.

NOTE

This hook is executed only if the service actually returns an errorstatus other than E OK. if a system service executing in stan-dard mode incurs an error but does not return an error code, theErrorHook() will not be executed. Errors which occur inside theErrorHook() do not lead to recursive calls of this hook, ratherthey remain unhandled.


PreIsrHook

Please refer to Section 1.8.9, Isr Hooks

PostIsrHook

Please refer to Section 1.8.9, Isr Hooks

PreTaskHook

This hook is called by the kernel when a new task context has just been entered.

PostTaskHook

This hook is called by the kernel just before leaving the current task context. Thismay be due to preemption, task termination, or blocking of a task on an event.

StartupHook

This hook is called by the kernel at system startup after the system has been ini-tialized but before the scheduler is activated. While the hook is executing, all in-terrupts are disabled. Please note that according to the OSEK specification theStartupHook() must not be used to initiate alarms or activate tasks.

ShutDownHook

This hook is called whenever ShutdownOS() has been called either explicitly by theapplication or implicitly by the system. It can be used, for example, for reinitializationor error logging. When the hook returns, the system shuts down all its services.


NOTE

When an OSEK system is running together with an OSEKTimesystem, the hook routine ShutdownHook() must return!.

1.8.3 Debugging Support

In order not to load the final application with unnecessary overhead, OSEK pro-vides two execution modes (called status in the OSEK specification): standard andextended.

If the system is operating in standard mode, most system services do not returnany useful status information. The system only reacts to errors when it reaches aninconsistent state that causes a shutdown.

In extended mode the system is able to detect a variety of errors like invalid IDsof system objects or requests that are illegal in the current state of the system. Insuch a situation the service returns an error code which can be evaluated by theapplication. Please see the APIs described in the appendices of this document forerror codes and their semantics.

1.8.4 The OS Tracer

The OS tracer records the tasks during the running of the system. All task IDs aresaved in a buffer. The size of this buffer can be specified in the Configurator. Directaccess to the buffer is achieved using the following variables:

OSEKOS TRACE ELEMENTS This is a macro which specifies the number of ele-ments in the trace buffer.

TaskType OSEKOStraceBuffer[OSEKOS TRACE ELEMENTS ] This array is thebuffer which holds the recorded entries. The buffer is filled during startup withthe value INVALID TASK .


unsigned char/short OSEKOStraceIndex This variable is the index into the buffer.It always points to the element which is overwritten the next time. After writingthe task id into the buffer the trace handling increments this variable (possiblysetting it to zero).

1.8.5 API Interface

The API functions described later in this document are realized either as real func-tions or as C macros. The usage of C macros means that the user has to takespecial care regarding the following facts:

• The existence of a function pointer for a API function cannot be as-sumed. However you can force usage of real functions by defining IN-CLUDE RealOSEKFunctions either on the compiler command line or in”board.h”.

• API calls should not contain arguments which might be evaluated more thanonce. For example, SetRelAlarm(Alarm1,i++,0) may have unexpected re-sults.

1.8.6 Version Macros

All versions of ProOSEK R© define the following macros:

• PROOSEK is always defined as 1.

• PROOSEK VER is a positive number indicating the version number of theProOSEK R© release.

• PROOSEK REV is a positive number indicating the revision number of theProOSEK R© release.

• PROOSEK CORE BUILD is the build number of the kernel core of thisProOSEK R© release.

• PROOSEK ARCH BUILD is the build number of the architecture specificparts of the kernel of this ProOSEK R© release.


NOTE

PROOSEK CORE BUILD andPROOSEK ARCH BUILD must be the same, otherwise

reliable operation is not guaranteed

1.8.7 The Extended Runtime Checker

This feature checks for additional errors:

• At startup it checks if initialized RAM variables are correctly initialized and ifuninitialized data is correctly set to 0. In case of an initialization error Shut-downOS() is called with E OS SYS INIT

• If a task is terminated without calling TerminateTask() or ChainTask() thesystem will be shutdown with status E OS SYS CODE

• During task switch the operating system checks for correct nesting of Sus-pend...Interrupts() and Resume...Interrupts() . if this test fails the systemshuts down with status E OS SYS CODE

• When a task calls Schedule() the operating system checks if CALLSCHED-ULE was set to NO. If so ShutDownOS() is called with statusE OS SYS CONFIG

Please consult the Architecture Notes for information on additional checks .

1.8.8 The Stack Checker

The stack-check feature can be used to check if an stack over- or underflow oc-curred. For this purpose the stacks will be filled with 0xEE and the watermark 0xEDwill be used for marking the ends of the stacks. There is also a API which allows toexplore the stack usage by counting the 0xee which are not yet overwritten . Theservice includes the following functions:


unsigned char * stackStart(TaskType task) This function returns a pointer to thestart of the stack for a specific task. Note that there is no check on the argu-ment! The service can be used in tasks, ISRs and hooks.

unsigned char * stackEnd(TaskType task) This function returns a pointer to theend of the stack for a specific task. Note that there is no check on the argu-ment! The service can be used in tasks, ISRs and hooks.

signed char stackCheck() This service checks the stack of the current task. Itwill return -1 if there is a stack underflow and 1 if there is an overflow. If noover/underflow is detected a value of 0 is returned. The service can only becalled from task level and from ISR category 2.

int getUnusedTaskStack(TaskType task) This service returns the number ofbytes never used on the stack for the specified task. Returns -1 if 0xED wasoverwritten. Note: this is not the current number of bytes.

int getUsedTaskStack(TaskType task) This service returns the number of bytesalready used on the stack for the specified task. Note: this is not the currentnumber of bytes.

int getUnusedIsrStack() This service returns the number of bytes never used onthe stack for interrupt service routines. Returns -1 if 0xED was overwritten.Note: this is not the current number of bytes.

int getUsedIsrStack() This service returns the number of bytes already used onthe stack for interrupt service routines. Note: this is not the current number ofbytes.

Additionally, the system checks during every task-switch and after the terminationof an ISR category 2 if the stack is in a valid state. If this is not the case thesystem calls the ShutdownOS() service with either E OS SYS StackOverflow orE OS SYS StackUnderflow .

NOTE

Some implementations of ProOSEK R© may deviate from thisAPI. Please consult the proper ArchitectureNotes!


1.8.9 Isr Hooks

Isr hooks can be used to evaluate the time consumption of interrupt service rou-tines. This feature can be enabled globally by setting the switches PREISRHOOKand POSTISRHOOK to true in the OS object. The PreIsrHook(IsrType) is calledjust before entering the user code of the interrupt service routine and PostIs-rHook(IsrType) is called just afterwards.

The provided parameter can be used to compare it with the name of the Isr prefixedwith ”ISR ID ”.

Since this service is implemented using the ISR keyword only category 2 interruptscan be instrumented (Exception are architectures which use the ISR keyword alsofor category 1 interrupts). Counter and system interrupts are not instrumented.

The environment of the Isr hooks is the same as the environment of the Isr routineitself. Therefore the same restrictions for calling system services apply.

NOTE

Using this feature adds one level of calling depth to the ISRroutines. You may need to increase the interrupt stack size.Some implementations of ProOSEK R© may deviate from thisAPI. Please consult the proper ArchitectureNotes!

NOTE

Unlike the PreTaskHook() and the PostTaskHook() the IsrHooksare called exactly once for each invocation of an interrupt serviceroutine (i.e. at start and termination).

2Communication

2.1 Introduction

The ProOSEK R© Communication subsystem provides a standard mechanism for thetransfer of data from one task or interrupt to another task or interrupt.

The subsystem is an implementation of the ”OSEK/VDX Communication” COM Ver-sion 2.2.2. The conformance classes implemented are CCCA and CCCB. Theseconformance classes deal only with local messages.

2.2 Messages

The basic building block of the communication system is the message. A variety ofmessage types are supported which can be configured during system generation.Different message types may be handled differently by the communication subsys-tem. However, for the application, message handling is mostly type independent.This requires unique names for each message and standardized API for the com-

CHAPTER 2. COMMUNICATION 39

munication system elements.

During the run-time of a system, the messages consists of two parts:

• The Message Descriptor contains the configuration of the message. Thisinformation is static, and is held in read-only memory on the target system.

• The Message State variables contain the run-time state of the message, in-cluding data buffer where required, and so must be located in RAM.

The size of these two data structures for any message depends on the configurationof the message, as well as on the whole system configuration.

Messages are configured using the ProOSEK R© Configurator, which handles mostof the details regarding which data structures to use and what support is requiredfrom the communication system.

2.3 Message API

The following functions are available to manipulate message objects. Detailed de-scriptions of the parameters and return values are given in Appendix B.

Table 2.1: Communication API

Function Name Description of the functionStartCOM() Initializes the COM system and calls Mes-

sageInit( ) . Usually called during system start-up.

SendMessage(msg,data) Sends data using message object msg andmessage data field data .

ReceiveData(msg,data) Receives data using message object msg andmessage data field data .

GetMessageResource(msg) Sets the message object msg to BUSYReleaseMessageResource(msg) Sets the message object msg to NOT BUSYGetMessageStatus(msg) Returns current status of the message object

msg .

These API functions are implemented using the following data types:


Table 2.2: Communication data types and constants

Data type Description of the data typeSymbolicName Used for identification of user defined message

objectsAccessName The data buffers of each message (defined in

the ProOSEK R© Configurator) can be directly ad-dressed via AccessNames. For example, to ac-cess the data buffer of a message called ”Diag-nostics ”, ”Diagnostics data ” should be used.

AccessNameRef Reference to an AccessName

2.4 Semantics of API Calls

The communication APIs are mostly independent of the message type. However,the semantics do different slightly depending on the buffering scheme used.

2.4.1 Queued Messages

The queue is implemented as a circular buffer using read and write pointers. Thelength of the queue is defined (during system configuration) for each message objectusing the variable QUEUEDEPTH (Details can be found in Chapter 4, Configurator).The length of the queue cannot be changed during run-time.

SendMessage( ) copies the data into the next slot and updates the write pointer. Ifrequired, the notification action is taken to inform the receiver of incoming data.


NOTE

The notification action and the SendMessage( ) service are notatomically executed!

This means it is possible that a receiver may get the messagefrom the queue before the notification action is executed. It is upto the application to handle this.

If the queue is full, SendMessage( ) returns E COM LIMIT to indicate that the mes-sage could not be sent. In this case the data is not copied in the buffer and is thuslost.

ReceiveMessage( ) first checks the queue, if there is a message in the queue itcopies the message data from the buffer to the message data field and updates theread pointer to the buffer (i.e. queued messages are ”consumed”). If the queue isempty, ReceiveMessage( ) returns E COM NOMSG.

One queue is used for all receivers of a particular message object.

2.4.2 Unqueued Messages

Two implementations of unqueued messages are possible: WithCopy or Without-Copy. Queued messages always use the WithCopy implementation. It is possibleto set this behavior in the GUI in the TASK object under the ACCESSORs tab. Formore detailed information refer to Chapter 4, Configurator and Appendix B.

Unqueued messages are useful when there are multiple recipients, as messagesare not consumed by a call to ReceiveMessage( ) . This means that ReceiveMes-sage( ) returns E OK even if SendMessage( ) has never been called!

A call to SendMessage( ) overwrites the data area, thus destroying the old data.If configured, a notification action will take place to inform the receiver of incomingdata. Note that the notification action and the SendMessage( ) service are notatomically executed. This means that a receiver may read the message from thebuffer even before the notification action is executed.


WithCopy Messages

WithCopy messages are implemented using a fixed-length buffer. Each user of themessage object, upon a call to ReceiveMessage( ) , makes a copy of the messagedata into its own private buffer. This means that the send and receive functionsprovide a data-consistent mechanism for data exchange.

SendMessage( ) copies new data to the message buffer.

ReceiveMessage( ) copies the message buffer into a private data area. If no datahas been received in the message, ReceiveMessage( ) copies whatever is in themessage buffer upon initialization and returns E OK! If no new message has beensent since the last call to ReceiveMessage( ) then it copies the same message dataas the last call to ReceiveMessage( ) copied) and returns E OK.

NOTE

The behavior of an unqueued ”WithCopy” message is differentto a queued message with a QUEUEDEPTH of 1!.

WithoutCopy Messages

WithoutCopy messages behave like a global variable and can be accessed directlyfrom the application via the AccessName , which is defined on a per task or ISRbasis during the configuration. The AccessName is set in the TASK object underthe ACCESSORs tab. For more detailed information refer to Chapter 4, Configuratorand Appendix B.

In this case ReceiveMessage( ) returns only the service status, since the messageobject is directly accessed. SendMessage( ) can be used to trigger any notificationmechanisms defined during configuration.

Two functions are available to allow the application to lock WithoutCopy messages,namely GetMessageResource( ) and ReleaseMessageResource( ) . These func-tion by setting the message object to BUSY and NOT BUSY respectively. It is impor-tant to note that ReleaseMessageResource( ) will unconditionally set the messageobject to NOT BUSY. For this reason, it is recommended that these functions appearwithin the same function block, and that these functions are only used to support the


transfer of WithoutCopy messages. In the case that a message object is BUSY andan attempt is made to access that object through the functions SendMessage( ) orReceiveMessage( ) , they will return E COM LOCKED . To find out if the messageobject has been locked by the system or the application, the service GetMessageS-tatus( ) must be used. In this case it will return E COM LOCKED if the messageobject is locked by the system or E COM BUSY if the message is locked by theapplication

The WithoutCopy scheme is only supported for unqueued messages.

NOTE

It is the responsibility of the application to ensure consistency ofthe message data when using the WithoutCopy implementationof an unqueued message!

2.4.3 Notification Mechanisms

It is possible to implement notification mechanisms for message objects. These areactivated automatically by ProOSEK R© once SendMessage( ) has been called.

ProOSEK R© supports the following notifications mechanisms:

• Activation of a task

• Setting of an event

• Calling a user-specified function

• Setting of a flag

NOTE

Note that the notification action and the SendMessage( ) serviceare not atomically executed. This means that a receiver mayread the new message before the notification action is executed.


2.4.4 Return Values

All COM API functions return one of the following status codes:

E OK Operation completed successfully

E COM NOMSG There are no more messages in the queue (queued messagesonly)

E COM BUSY Message is locked by the application (unqueued WithoutCopy mes-sages only)

E COM LOCKED Message is locked by the system

E COM LIMIT There has been at least one overflow of the FIFO queue (queuedmessages only)

E COM ID Invalid message ID (only when OS is in EXTENDED mode)

2.5 Message setup files and macros

In order to define the messaging behavior the following files and macros are used.

2.5.1 COMUserData.h - Message data types

When defining message objects in the configurator, it is possible to choose the Cdata type (CDATATYPE ) used for the message object data (Refer to Section 4.6.10,Messages for more information). If the data type chosen is not a primitive type (forexample: int, long, char), but rather a type def inition, then this data type must bedefined in a file COMUserData.h to be placed in the include directory. This file is usedby the compiler and as such cannot be verified by the Configurator.


2.5.2 Macros

The following macros can be passed to the compiler and should be defined in theapplications makefile:

• INCLUDE NoCOMUserData - This should be defined when all of the MES-SAGE objects use CDATATYPEs that are internally defined and not requiredto be defined in COMUserData.h.

• INCLUDE COM No MessageInit - When the application does not define aMessageInit( ) function. Refer to OSEK Communications API Reference -Appendix B.

3Developing with ProOSEK

3.1 Introduction

The ProOSEK R© system consists of the graphical Configurator and a given file struc-ture which together form the ProOSEK R© solution. In order to work properly with theenvironment it is important to understand how the different tools work together.

Furthermore ProOSEK R© comes with a predefined directory structure the usershould be familiar with. On the other hand the experienced user may change thedefault settings to meet his requirements for the way the process works.

CHAPTER 3. DEVELOPING WITH PROOSEK 47

3.2 Development Workflow

The following figure gives an overview of the ProOSEK R© developing process.

Figure 3.1: ProOSEK developing process


3.3 The Configurator

The Configurator is the main tool of the developing process. It is a graphical toolwhich permits a system to be configured according to a set of demands. Configu-rations can be saved using the OIL language (Version 2.3). The Configurator canalso be used to check the consistency of a given configuration and to generate tem-plate files - which are useful when writing an application. The following list shows asummary of the Configurators features:

• system configuration

• save/load configurations

• check the correctness of a particular configuration

• kernel generation for a specific configuration

• generation of a template file from a configuration

• generation of ORTI data

• generation of a HTML summary of a particular system

• generation of RAM usage statistics

For more information about the Configurator, refer to Chapter 4, Configurator.

3.4 The File Structure

ProOSEK R© uses by default the following file structure. The structure can be modi-fied by an experienced user if needed. The base directory is always referenced asenvironment variable OSEK BASE .

OSEK BASE/bin This directory contains some executables needed for the Config-urator and the make tool used to build sample applications.


OSEK BASE/data This directory contains subdirectories which hold data files forthe Configurator.

OSEK BASE/make Some basic makefiles are placed in this directory. These arealso used to build the examples.

OSEK BASE/boards Here are the directories which hold the board-specific infor-mation.

OSEK BASE/src For some architectures additional files which may be needed tobuild the application are located here.

OSEK BASE/include The include subdirectory contains header files which are ei-ther referenced by the generated kernel or board specific files.

OSEK BASE/demos Contains some example-code. These examples are agood starting point when learning how to use (or write applications with)ProOSEK R©.

OSEK BASE/pdf Contains the manuals in PDF format.

There may be some additional directories under OSEK BASE , depending on thespecific architecture.

4Configurator

4.1 Introduction

The OSEK operating system standard specifies a static system. As there is nomeans of dynamically creating system objects, the required system resources mustbe statically assigned. Once all the required system objects have been specified,a ProOSEK R© system can be generated and linked together with the appropriateapplication.

The ProOSEK R© Graphical Configurator and System Generator are a set of toolsthat support the specification process of the ProOSEK R© system. The Configuratorprovides graphical editors for all types of system objects as well as the possibility toload and save configurations in OIL (OSEK Implementation Language) format. OILhas been specified by the OSEK/VDX committee.

The Generator offers the following functionality, based on an existing OIL configura-tion:

• Configuration verification of consistency and completeness

• Computation of system data structure RAM requirements

• Generation of a ProOSEK R© kernel based on the configuration

CHAPTER 4. CONFIGURATOR 51

• Generation of ORTI data (when supported by the debugger)

• Generation of an application template

• Generation of a HTML summary page

The Generator is integrated into the Graphical Configurator, and is also available viathe command-line interface (making it possible to integrate system generation intothe make process when desired).

4.2 The Main Window

Figure 4.1 shows the window that appears when first starting the ProOSEK R© Con-figurator.


Figure 4.1: The Configurator at Start-up

At the top of the Configurator window the menu and tool bar can be found. The menubar provides access to various elements of the Configurator and the Generator. Thetool bar provides shortcuts for the most frequently used functions.

The status bar is located at the bottom of the window. The status bar displays thetarget system currently being configured and the name of the OIL file currently beingedited.


Figure 4.2: Configurator main window - Objects view

Figure 4.2 shows the configurator window once an OIL file has been loaded or anew OIL file has been created. The window is split into two panes. The left panecan be alternated between two views - Objects and Files view. Figure 4.2 shows anexample of the Objects view, and Figure 4.3 shows an example of the Files view.

The Objects view shows all the objects available for the specified architecture. Bydouble clicking on these objects it is possible to see all the instances that havebeen defined in the OIL file being edited. If no instances presently exist then anew instance can be created by right clicking on the object. Refer to Section 4.5,Managing Objects for more information about the editing functions.


Figure 4.3: Configurator main window - Files view

Figure 4.3 shows the Files view. It is possible to split large systems into multipleOIL files, and this view displays the layout of these files. The example in Figure 4.3shows an OIL file ProOSEK Demo 0.oil which contains an OS object, and the two filesbreak.oil objects and lights.oil objects . Inside each of the OIL object files arevarious OIL objects defined. This is identical to defining all the OIL objects in oneOIL file. The OIL object files are only intended to improve the understandability of agiven system.

The right pane of the main display area is used to display and edit object attributes.This following sections will explain the various object attributes in detail.

4.3 File Management

The File menu contains the file management commands, together with the Exit com-mand.


Figure 4.4: The File Menu

The following sections describe the file management commands. Each section be-gins with a table that summarizes the buttons and keyboard shortcuts (if any) for thecommands described in that section.

4.3.1 Create a File

Button ShortCut File Menu Command

CTRL+N New

To create a new file, click New in the File menu. The target system chosen for thenew file will be that of the last file loaded or saved.

If the current file has not been modified since the last save, it will simply close whenyou click New. Otherwise a confirmation dialog box will appear so that any changesmay be saved.

4.3.2 Open a File


CTRL+O Open Projectn/a 0 0:V:\..\ProOSEK4.0\demos..n/a 1 0:H:\my oil.oil


To open an existing project, click Open in the File menu. A standard Windows filebrowser (shown in Figure 4.5) allows you to select the file you want to open. The filemenu also shows recently used files at the bottom. These files can be opened bysimply clicking on the menu item.

Figure 4.5: Opening OSEK Configuration Files

If the current file has not been modified since the last save, it will simply close whenOpen is clicked. If the current file has been modified, a confirmation dialog box willappear, providing an opportunity to save this file.

When a file is opened, the contents are parsed by the Configurator’s OIL parser.OIL is an acronym for OSEK Implementation Language, another standard of theOSEK/VDX committee.

If a file with that contains invalid OIL syntax is opened, the parser will display a dialogbox listing the parse errors. In this case the OIL file must be manually correctedbefore it can be loaded in the configurator. It is possible to open configurationssaved in OIL versions 2.2 or 2.3 or with the ProOSEK R© Configurator. Saving is onlypossible in OIL version 2.3.


Include Files

The Configurator supports the #include directive in OIL files. The syntax and se-mantics of this directive are the same as in ANSI C. In order to load a configurationcontaining #include<...> directives, the include paths must be specified. Figure 4.6shows the set include path... option from the Options menu. This is where in-clude paths can be entered. Paths may be entered either one per line or separatedby semicolons. Included files will be shown in the Files view. Refer to Section 4.5,Managing Objects for further information about adding objects to files and manipu-lating objects.

Figure 4.6: Opening OSEK Configuration Files

NOTE

If the Configurator cannot write to your home directory, includepaths will not be saved.


4.3.3 Closing a File

Button ShortCut File Menu Commandn/a n/a Close

The currently opened File can be closed by clicking Close from the File menu.

4.3.4 Saving a File


CTRL+S Save alln/a n/a Save all As ...n/a n/a Save as one file ...

To save all the currently opened files, click Save all from the File menu.

A new name can be specified for the main OIL file by selecting Save all as.... Thiswill display a file selection dialog box (similar to Figure 4.5) where the desired pathand name for the file may be entered. If an existing file is chosen, the Configuratorwill display a warning dialog box to prevent accidentally overwriting files.

Included files will keep the same name. The name of included files can be changedin the Files view as shown in the right pane of Figure 4.3

Individual include files can be saved by right-clicking on them in the Files view (seeFigure 4.8) and selecting Save.

Save as one file is used to save multiple files as one combined OIL file. It will notcontain any includes.

NOTE

If the current file does not yet have a name, clicking on Save allwill result in a Save all as... operation.


4.4 Choosing a Target System

The ProOSEK R© Configurator allows you to convert a ProOSEK R©-specific configu-ration to one which only contains standard OIL attributes. Similarly, you may loada foreign configuration and add ProOSEK R©-specific attributes. If your installationsupports multiple target architectures, you can also work on configurations for dif-ferent systems from a single Configurator. These features are accessible throughthe System menu. Figure 4.7 shows the menu for an installation which supports asingle family of target architectures, e.g. the Motorola HC12.

Figure 4.7: The System Menu

The target architecture for the current configuration is marked with a check sign onthe System menu. When loading a foreign configuration that does not correspondto one of the target systems available, the check mark disappears.

4.4.1 Moving to a Different Target Architecture

To convert a configuration to a different target architecture, select the desired archi-tecture from the System menu. This command will remove all attributes which arespecific for the previously selected architecture. Any attributes specific to the newlyselected target architecture will be automatically added by the Configurator. If thecurrent configuration has not been saved before changing then the Configurator willdisplay a dialog box offering to save it first.


NOTE

When none of the target systems are selected, it is not possibleto use the commands from the Tools menu.

4.5 Managing Objects

The left pane of the Configurator window (Figure 4.2 and Figure 4.3) shows a treerepresentation of the current configuration. Different editing operations are availabledepending on which object and which view is selected.

Figure 4.8 shows the options available when right-clicking on an object or file in theObjects or Files view respectively.

Figure 4.8: Edit Menu in Objects View (right click on objects)

Figure 4.9 shows the options available when right-clicking on a file in the Files view.


Figure 4.9: Edit Menu in Files View (right click on objects)

The following sections describe the editing commands. Each section begins witha table summarizing the buttons and keyboard shortcuts (if any) for the commandsdescribed, as well as their availability.

4.5.1 Adding/Creating a New Object

Button ShortCut Edit Menu Commandn/a n/a Newn/a n/a Add

When in the Objects view, a new object can be made by right clicking on the desiredobject and selecting New. The default is for this object to be added to the main OILfile in the Files view. It is possible to add an object to a particular file (where morethan one file defines the particular system) by right-clicking on the desired file andusing the Add menu option.


4.5.2 Editing an Object

In order to edit the attributes and references of an object, select the object to beedited in the left pane of the configurator. Once selected, details about the objectwill be displayed in the right pane. Please refer to Section 4.6, Managing Attributesand References for details regarding editing object attributes.

4.5.3 Duplicating an Object

Button ShortCut Edit Menu Commandn/a n/a Duplicate

An object can be duplicated by right clicking on it and selecting Duplicate. The newobject will be an exact copy of the original object with all its attribute values. The onlydifference between the two objects is the name (the new object will have copy ofprepended to the original objects name).

4.5.4 Deleting an Object

Button ShortCut Edit Menu Commandn/a n/a Delete

An object can be deleted by right-clicking on it and selecting Delete. A confirmationdialog will be displayed to prevent accidental deletion.

4.5.5 Moving an Object

An object can be moved to another file in the Files view by dragging and dropping itonto another file. Due to the java implementation it is necessary to select the objectat first. Do the following to perform a Drag&Drop operation:


1. Left click on an object or container to select it.

2. Release the left mouse button

3. Left click it again and drag it to the desired file

4. Drop it by releasing the left mouse button.

4.6 Managing Attributes and Refer-ences

When a new object is created or an existing object is selected in the left pane, thecorresponding object editor opens in the right pane of the Configurator. The editordisplays the attributes for the selected object.

Attributes and References

An attribute defines a property of an object. The editor represents it as a GUI item.Depending on the expected value, this can be a check box, a combo box offering achoice of possible values, or a text field.

The OIL specification defines a number of standard attributes that must be presentin any complete system specification. Additionally, OIL allows the definition ofsystem-specific attributes. ProOSEK R© makes use of specific attributes to imple-ment architecture-specific requirements, such as stacks and registers.

A reference defines the relationship between one object and another object in theconfiguration.

Lists

Single attributes or references are represented as text fields. Reference lists (e.g.EVENTs, RESOURCEs, etc.) are represented as individual cards.


The Editor

The object editors’ structure is generally the same for each object. Figure 4.10shows the task editor as an example. At the top, text fields for the object nameand a comment can be found. The central part displays a number of cards. Thefirst card usually holds the object attributes, while the second and subsequent cardshold references. Attribute lists have their own cards. In the example, you can see acard ”EVENTs” which lists all the EVENTS the TASK can wait for, and another card”RESOURCEs” which lists all the RESOURCES the TASK can occupy.

When an object is opened in the editor which has not been fully specified, the Con-figurator will fill in some default values. Where check boxes or drop-down lists areused, default settings will be applied. Default settings exist only to ensure that whatis shown in the GUI is consistent with what is stored in the file. They are not appliedto attributes which already have values assigned to them in the OIL file!

Figure 4.10: The Task Editor


NOTE

Even when the Configurator has filled in default values for someattributes, the object may still be incomplete. This is becausetext fields do not obtain default values.

Description of Attributes

The following sections describe all object groups along with their standard at-tributes. Please refer to your architecture-specific documentation for a descriptionof architecture-specific attributes.

4.6.1 The OS Object

Figure 4.11 shows the OS editor. Each OS attribute is explained below. All attributesare mandatory. The verification tool will issue an error message for each OS attributewhich conflicts with other attributes.


Card: ”General”

Figure 4.11: The OS Editor

CC This attribute is a ProOSEK R© specific attribute, but is provided for all architec-tures. CC specifies the OS conformance class used by the application. Op-timizations can be made by selecting the lowest possible conformance class.The verifier will report when an optimization can be made to this variable. Asystem specified as ECC requires more resources than a BCC system. Sim-ilarly, multiple tasks per priority and multiple activations per task increase re-source requirements.

You may choose from the following values for CC:

BCC1 For one basic task per priority and no multiple activa-tion of tasks.

BCC2 Only for basic tasks but where either multiple tasksof the same priority or multiple activation of tasks isrequired.


ECC1 For one or more extended tasks. Only one task perpriority is available and multiple activation of tasks isnot supported.

ECC2 For full support of basic and extended tasks, includ-ing multiple tasks per priority and multiple activation oftasks.

AUTO The Generator will choose the lowest applicable con-formance class for your application.

SCHEDULE This attribute is ProOSEK R© specific. SCHEDULE specifies the overallscheduling policy. The available scheduling policies are:

NONE For purely non-preemptive scheduling.This means that all tasks in the configuration must benon-preemptive. Non-preemptive tasks are not pre-empted by higher priority tasks. They only give up theCPU when they call certain system services.

FULL For fully preemptive scheduling.Fully preemptive scheduling means that all tasks arepreemptive. Tasks which are running will be pre-empted as soon as a higher priority task becomesready.

MIXED For systems containing both preemptive and non-preemptive tasks.

AUTO For the Generator to select the scheduling policy onthe basis of the SCHEDULE attributes of the tasks de-fined.

Please refer to Section 1.4.4, Task Scheduling for more information onscheduling policies and to Section 4.6.3, Tasks for further information.

STATUS This attribute specifies the debugging level of the system. Details can befound in Appendix A regarding what each function returns depending on whichstatus the OS is running in. There are two choices:

STANDARD Without debugging features.


EXTENDED With debugging features. In this mode, ProOSEK R© performs var-ious error checks when executing system services and provideserror codes on return from system services.

TRACEBUFFER This attribute specifies the size of the trace buffer and enables thetracing. If no value is placed in the field, the tracing is disabled. See Section1.8.4, The OS Tracer for details.

EXTRA RUNTIME CHECKS This boolean attribute should be set if the user wantsto have additional runtime checks. This usually includes:

• checking for initialization of variables

• checking if TerminateTask() is called at the end of a task

• ...

For a detailed description consult Section 1.8.7, The Extended RuntimeChecker and the archnotes for architecture specific tests.

USERMAIN The generated kernel will contain a main() routine by default, which iscalled from the compiler-startup. If you need your own main() routine then thisswitch must be enabled and the function must be defined in your application.

STARTUPHOOK This boolean attribute specifies whether the application containsa function StartupHook() that will be called by the system at start-up. Whenchecked the generated OS module will contain an unresolved symbol Star-tupHook which must be provided by the application modules so that the Linkercan resolve it.

ERRORHOOK This boolean attribute specifies whether the application contains afunction ErrorHook() that will be called when the system encounters an error(i.e. when a system service returns anything other than E OK). When checked,the generated OS module will contain an unresolved symbol ErrorHook whichmust be provided by the application modules so that the Linker can resolve it.

SHUTDOWNHOOK This boolean attribute specifies whether the application con-tains a function ShutdownHook() that will be called when the system is shutdown. When checked, the generated OS module will contain an unresolvedsymbol ShutdownHook which must be provided by the application modulesso that the Linker can resolve it.

PRETASKHOOK This boolean attribute specifies whether the application containsa function PreTaskHook() that will be called whenever a task becomes sched-uled. When checked, the generated OS module will contain an unresolvedsymbol PreTaskHook which must be provided by the application modules sothat the Linker can resolve it.


POSTTASKHOOK This boolean attribute specifies whether the application containsa function PostTaskHook() that will be called whenever a task is preempted.When checked, the generated OS module will contain an unresolved symbolPostTaskHook which must be provided by the application modules so that theLinker can resolve it.

PREISRHOOK This boolean attribute specifies whether the application contains afunction PreIsrHook() that will be called whenever a ISR is invoked, the gen-erated OS module will contain an unresolved symbol PreIsrHook which mustbe provided by the application modules so that the Linker can resolve it.

POSTISRHOOK This boolean attribute specifies whether the application containsa function PostIsrHook() that will be called whenever a ISR is invoked. Whenchecked, the generated OS module will contain an unresolved symbol PostIs-rHook which must be provided by the application modules so that the Linkercan resolve it.

USEGETSERVICEID This boolean attribute specifies whether the application usesthe macro OSErrorGetServiceId() that can be called in ErrorHook() .

USEPARAMETERACCESS This boolean attribute specifies whether the applica-tion uses the macros OSError x1 x2() that can be called in ErrorHook() toaccess the parameters of the system call that caused the error. x1 is the nameof the system service and x2 the name of the parameter of this particular sys-tem service.

SERVICETRACE This boolean attribute should be checked if the user wants to usethe SERVICETRACE feature in ORTI. This feature allows ORTI-aware debug-gers to trace the system calls.

USELASTERROR This boolean attribute should be checked if the user wants touse the LASTERROR feature in ORTI. This feature allows ORTI-aware debug-gers to access the last error code not equal to E OK which a system servicereturned.

This may also be used to figure out the error code manually by examining thevariable OSEKOSLastError .

It may even be used to find the reason of a Shutdown() .

USERESSCHEDULER This boolean attribute should be checked if the user wantsto use the predefined resource RES SCHEDULER. Acquisition of this re-source deactivates the scheduler.


4.6.2 Appmodes

The APPMODE editor does not yet have any standard attributes.

4.6.3 Tasks

Figure 4.12 shows the TASK editor. A detailed explanation for each TASK attributeis given below. All of these attributes are mandatory. The verification tool will issuean error message for each TASK attribute that has not been defined.

Card: ”General”

Figure 4.12: The TASK Editor


TYPE This attribute is ProOSEK R© specific. It specifies how the task behaves. Thefollowing choices are available:

BASIC For a task without the ability to wait for events

EXTENDED For a task with the ability to wait for events

PRIORITY This integer attribute defines the scheduling priority of the task. A highervalue corresponds to a higher priority. Negative values are not allowed

NOTE

Priorities define the relative ordering of tasks. They are notinterpreted as absolute values.

ACTIVATION This integer attribute defines the maximum number of recorded acti-vation requests for the task. A value of 1 means that only single activation ispermitted for the task. Negative and zero values are not allowed.

When you enter zero or a negative value or when the value is missing at all,the verification tool will create an error message.

SCHEDULE This attribute specifies the scheduling policy for this task (i.e. whetherit can be preempted or not). The following values are available:

NON For non-preemptive tasks. Non-preemptive tasks onlyleave the running state when they call certain systemservices.

FULL For preemptive tasks. A task will be preempted fromthe CPU when a higher priority task becomes ready.

Please refer to Section 1.4.4, Task Scheduling for more information onscheduling policies and to Section 4.6.1, The OS Object for the OS attributeSCHEDULE.

STACKSIZE Specifies the size of the stack (in bytes) required for this task. The sys-tem will add additional space for calling system functions like ActivateTask()and TerminateTask() . If pre- or post-task hooks are used then the stack size


should include any space required for the execution of these hooks.

CALLSCHEDULER This variable is used for optimization. It should be set accord-ing to whether the function Schedule() is called or not from this task. If it isunknown then it is possible to use the value DONT KNOW.

Card: ”ACCESSORs”

Figure 4.13: Accessor list in the task editor

The configuration of list attributes such as accessors is shown in Figure 4.13

There are three buttons, one for adding elements, one for deleting elements andone for duplicating elements. Elements of the list are selectable. Once an elementis selected, it can be modified using the attribute fields above the list.

The accessor list specifies all messages that are accessed by the task. MESSAGEspecifies the message, ACCESSOR specifies how it is accessed (either SENT orRECEIVED), WITHOUTCOPY specifies how the message is buffered, and AC-CESSNAME is used to access the message object directly in the case that it isWITHOUTCOPY. Refer to Chapter 2, Communication for further details about mes-sages.


Card: ”RESOURCEs”

This reference list defines the set of resources that are required by the task. Thelist must contain any resource(s) used by the task. This list is used to define pri-orities and therefore if the task tries to hold a resource which is not defined in itsRESOURCEs list then the behavior of the system will be undefined.

Card: ”EVENTs”

This reference list defines a set of events that are used by the task. The list mustcontain any event on which the task calls WaitEvent() . If one of these events ismissing from the list, the verification tool can not detect the error. The behavior ofthe generated system will then be undefined.

Card: ”AUTOSTART”

The boolean attribute AUTOSTART determines whether the task is started duringthe system startup procedure (box checked) or not (box not checked). When thebox is checked then it will automatically enter the ready state during startup for eachapplication mode that is listed in the AUTOSTART card.

AUTOSTART may be selected for any number of tasks in the system. When morethan one task is activated by the startup procedure, the first task to be executed isdetermined by the priority settings.

4.6.4 Resources

Card: ”RESOURCEPROPERTY”

RESOURCEPROPERTY This attribute specifies what kind of resource it is. Thefollowing choices are available:


STANDARD This resource must be assigned to tasks or ISRsand can be taken by calling the function GetRe-source() and released by calling the function Re-leaseResource() .

LINKED This resource is only required where nesting ac-quiring of resources is required. It should onlybe a copy of another resource with a resourceproperty of either STANDARD or LINKED.

INTERNAL When an internal resource is listed on the RE-SOURCEs list of a TASK or ISR then wheneverthe TASK enters the running state, or the ISR isrunning, the resource will be held by the TASK orISR until the process is finished.

Refer to Section 1.5.1, Resources and Appendix A for further details.

NOTE

The specification of a resource which is not used by anytask or ISR will result in an error message from the verifi-cation tool

4.6.5 Events

Card: ”General”

Figure 4.14 shows the EVENT editor. Below is a more detailed explanation of theonly EVENT attribute, MASK .


Figure 4.14: The EVENT Editor

MASK This integer attribute defines the event mask for the event. You may enter themask as a decimal or hexadecimal integer. Only powers of two are reasonablevalues here. If you do not select a value, the Generator will automaticallyassign a unique single bit event mask.

Negative and zero values are not allowed for this attribute and will result in anerror message from the verification tool.

NOTE

If you leave the MASK attribute empty, the Configuratorwill write the value AUTO to the OIL file when you save theconfiguration.


4.6.6 Counters

Figure 4.15 shows the COUNTER editor. All attributes detailed below are manda-tory. Together, they form the alarm base structure for associated alarms. Thestructure can be read from an application in two ways. Either by using the sys-tem service GetAlarmBase() (this function is detailed in OSEK OS API Reference- GetAlarmBase()), or by accessing the variables OSMAXALLOWEDVALUE x,OSTICKSPERBASE x or OSMINCYCLE x (where x is the name of the counter)directly. The verification tool will issue an error message for each COUNTER at-tribute that is not set.

Card: ”General”

Figure 4.15: The COUNTER Editor

HC12 TYPE (architecture dependent) This variable will change depending on thetarget architecture. It is used to choose which timer the counter will use to


increment. It is also possible to choose USERCOUNTER, which means thatthe counter is incremented by the application. Refer to the Architecture Notesfor the required target architecture for further information.

MINCYCLE Cyclic alarms expire periodically after a certain number of ticks of thecounter with which they are associated. This integer attribute serves to imposea minimum expiration period for any cyclic alarm tied to this counter. Theperiod is expressed in counter ticks.


MAXALLOWEDVALUE This integer attribute defines the maximum allowed countervalue. When the counter has reached this value it rolls over and restarts count-ing from zero.


TICKSPERBASE This integer attribute specifies the number of ticks required toreach a counter-specific value. The interpretation of this value is up to theuser. Nevertheless, TICKSPERBASE is mandatory as it is part of the alarmbase structure of associated alarms.

TIME IN NS This is a ProOSEK R© specific attribute and specifies the time innanoseconds for one tick of this counter. Note that not all system countersmay use this value, because they have a fixed period for one tick. More infor-mation can be found in the Architecture Notes.

4.6.7 Alarms

Figure 4.16 shows the ALARM editor. A detailed explanation for each ALARM at-tribute is given below. The verification tool will advise if any ALARM attributes havenot been defined.


Card: ”General”

Figure 4.16: The ALARM Editor

COUNTER This field states which counter is assigned to this alarm. Each alarmmust be associated with exactly one counter. An empty value in this field willresult in an error message from the verification tool

Card: ”AUTOSTART”

Figure 4.17 shows the AUTOSTART card.


Figure 4.17: The ALARM Editor - AUTOSTART card

AUTOSTART The boolean attribute AUTOSTART determines whether the alarm isactivated during the system startup procedure (box checked) or not (box notchecked). When the box is checked then the values ALARMTIME , CYCLE-TIME and APPMODE must be defined.

ALARMTIME The time when the alarm shall first expire.

CYCLETYIME The cycle time of a cyclic alarm. If the alarm should only be triggeredonce then this value should be set to 0.

APPMODE The application mode(s) in which the alarm should be auto-started.

Card: ”ACTION”

Figure 4.18 shows the ACTION card. The ACTION attribute specifies the action tobe performed whenever the alarm expires.


Figure 4.18: The ALARM Editor - ACTION card

ACTION The following values are available for this attribute:

ACTIVATETASK Activates the task specified by the attributeTASK .

SETEVENT Sets the event specified by the attributeEVENT.

ALARMCALLBACK Calls the callback routine specified by the vari-able ALARMCALLBACKNAME .

The action specified will be automatically performed by the ProOSEK R© uponexpiration of the alarm. The behavior is equivalent to calling the correspondingsystem service. If a particular action is defined and the corresponding attributefor that action is not defined (e.g. ACTIVATETASK without a TASK beingdefined) then the verification tool will report an error upon verification.


4.6.8 ISR

Figure 4.19 shows the ISR editor. The verification tool will issue an error message ifit is not set.

Card: ”General”

Figure 4.19: The ISR Editor

HC12 xxx These variables are architecture specific. Refer to the Application Notesfor the required architecture for further details.

STACKSIZE Specifies the size of the stack (in bytes) required by this ISR. The sys-tem will add additional space for calling system functions like ActivateTask() .This value is only used if the ISR is of category 2. Category 1 interrupts by-pass the kernel.


CATEGORY This attribute defines the category of the ISR. Categories are used forsystem optimization. The following categories are available:

1 for an ISR which does not call system services. If systemservices are called from a category 1 ISR then the systembehavior is undefined!

2 for an ISR which executes in a frame generated by the Sys-tem Generator so that it can call certain system services.Details of which system services are allowed to be calledcan be found in the appendices.

Card: ”ACCESSORs” and ”RESOURCEs”

Some architectures allow ISRs to hold resources. Check the Architecture Notes forthe desired architecture to see if it is possible. If so then the fields and interface aresimilar to those explained for TASK objects. Refer to Section 4.6.3, Tasks for furtherinformation.

4.6.9 The COM Object

The COM editor is shown in Figure 4.20.


Figure 4.20: The COM Editor

USEMESSAGERESOURCE This boolean attribute specifies whether the applica-tion uses the API GetMessageResource() and ReleaseMessageResource() .that will be called when the COM subsystem encounters an error (i.e. whena COM system service returns anything other than E OK). When checked,the generated OS module will contain an unresolved symbol COMErrorHookwhich must be provided by the application modules so that the Linker can re-solve it.

USEMESSAGESTATUS The COM object is not used for internal communicationin ProOSEK R©, but for the sake of completeness it provides the attributesUSEMESSAGESTATUS defined in OIL 2.3.

4.6.10 Messages

The MESSAGE editor is where all ProOSEK R© internal messages can be defined.The MESSAGE object consists of 3 cards: General, ACTIONs and TYPE.

The General card is shown in Figure 4.21. The attributes are as follows:.


Figure 4.21: The MESSAGE Editor

LENGTH This attribute is used to calculate the RAM requirements and is notmandatory. This attribute informs the configurator as to the length of the mes-sage data in bytes, and must be between 1 and 4095. If no length is specified,the RAM calculation will not take into account the memory needed for thismessage.

CDATATYPE The C-type of the message data can be specified here. Primitive datatypes like int or type definitions can be used. Any type definitions must bedefined in the file COMUserData.h . If a primitive type (like int, char, etc.) isused and the file COMUserData.h is not required, then either the macro IN-CLUDE NoCOMUserData should be used when compiling the OS and appli-cation, or an empty COMUserData.h should be used. Refer to Section 2.5.1,COMUserData.h - Message data types and Section 2.5.2, Macros for furtherinformation.

TYPE Two types of messages are supported: QUEUED or UNQUEUED. Forqueued messages, the attribute QUEUEDEPTH must also be defined.

QUEUEDEPTH QUEUEDEPTH specifies the length of the queue (i.e. number ofdata packets that will be buffered). This value may be between 1 and 65535.


ACTIONs Defines the notification mechanism(s) to be executed once message datafor the particular message object has changed (by a call to SendMessage( )).Supported actions are:

• Activation of a task (ACTIVATETASK)

• Setting of an event (SETEVENT)

• Execution of a user-defined callback function (CALLBACK)

• Setting of a flag variable (FLAG)

For each action the corresponding conditional value must be set. ACTIVATE-TASK requires the TASK attribute to be set. SETEVENT requires that boththe TASK and EVENT attributes are set. CALLBACK requires that the nameof the user-defined callback function in the attribute CALLBACKNAME is set(the generated OS module will contain an unresolved symbol which must beprovided by the application modules so that the Linker can resolve it) FLAGrequires that the FLAGNAME attribute be set.

NOTE

The configurator cannot verify that the specified callbackfunction (CALLBACKNAME) is valid and must be checkedby the user!

The configurator does not know about the stack usage ofthe callback. If it uses stack it may be necessary to cre-ate a dummy ISR routine on the same level as the counterinterrupt to ensure there is enough stack for the callback.

4.6.11 The NM Object

The NM object is not yet used in ProOSEK R©.


4.7 Working with a Configuration

You can start working with the configuration of the application as soon as it has beencompleted. The Tools menu from the menu bar contains the tools needed to verifya configuration and generate a customized ProOSEK R© kernel. (Figure 4.22) .

Figure 4.22: The Menu bar

The following sections describe the commands in the Tools menu bar. Each sectionbegins with a table that summarizes the button and keyboard shortcut (if any) forthe command described in that section. The generation path of the OS can be setusing the menu option ”Set generation path....”, otherwise it defaults to the HOMEdirectory.

4.7.1 Verifying a Configuration


Button ShortCut Tools Menu Command

CTRL+V Tools -> Verify

To verify the current configuration, click Verify from the Tools menu. If the config-uration is complete and consistent, an information dialog box will appear informingthat the verification was successful. In the case that the Configurator verification toolfinds some errors, these will be displayed in a dialogue window.

4.7.2 Generating a System


CTRL+G Tools -> Generate OS

To generate a ProOSEK R© system from the specified configuration, click GenerateOS from the Tools menu.

NOTE

If the destination directory has not been specified then the homedirectory will be used for generation.

Once the system has been successfully generated a popup window will appear stat-ing where the generated files can be found. was successful or not.

Generated Files

The generator will create the files os.c and os.h containing the customizedProOSEK R© kernel. Additionally, a file os.cnf will be created. This file contains astatic description of the system. It is used to generate an ORTI file used for OSEK-aware debugging by third party tools. For more information on this topic pleaseconsult the Architecture Notes.


NOTE

The generator always calls the verification tool before genera-tion. If the configuration is not complete and consistent, a popupwindow appears informing that verification/generation failed andno files are generated.

4.7.3 Generating a Template


CTRL+T Tools -> Generate Template

To generate an application template containing declarations for all objects specifiedand frames for all tasks and ISRs from the configuration, click Generate Template inthe Tools menu.

The Save File Dialog Box

The generation command will bring up the operating systems standard save filedialog box. The dialog box allows the target directory and a name for the templatefile to be specified.

Generated Files

The generator will create a file containing an application template matching the con-figured ProOSEK R© kernel.


NOTE

The verification tool is always called before system generation. Ifthe configuration is not complete and consistent, the verificationdialog box will appear and no files will be generated.

4.7.4 Generating a HTML Summary Page


n/a Tools -> Generate HTML

To generate a HTML summary page of the configuration then click on GenerateHTML. This will generate a file os.html in your generation directory (as long as theconfiguration passes verification). This file will then be opened using your standardweb browser. This can be useful to verify the system or to communicate to others thesystem composition. Should the verification tool detect any errors then the HTMLfile will not be generated.

Please refer to Section E.1, Dot for more information about image creation.

4.7.5 Generating ORTI Data


n/a Tools -> Generate ORTIx.x

When using an OSEK-aware debugger, it is useful to generate ORTI debugginginformation. For information whether the particular debugger in use supports ORTI,please refer to its manual. As with all generate functions, should the verification tooldetect any errors or inconsistencies in the system configuration then these will bereported in the verification dialogue field and the ORTI data will not be generated.


4.7.6 Getting Memory Requirements

Button ShortCut Menu Bar Commandn/a n/a Tools -> Check Size

The memory requirements of the current configuration can be determined by clickingCheck Size from the Tools menu. This command will bring up a dialog box displayingthe RAM consumption of the system in a bar chart diagram. It is also possible tokeep the current bar chart, make various changes to the system and click once moreon Check Size to see the effect of the changes on the RAM requirements.

NOTE

The size information tool always calls the verification tool beforegeneration. If the configuration is not complete and consistent,the verification popup appears and no size information is dis-played. This is because the memory requirement informationdepends on many of the settings. It is not possible to computereliable size information from an inconsistent configuration.

4.7.7 Working in Command-Line Mode

The ProOSEK R© Configurator provides a command-line interface so that it can beincorporated easily into a make process.

When run in command-line mode, the Configurator reads in a pre-defined OIL fileand runs the system verification and generation tools on it. The resulting files os.c,os.h and os.cnf are written to the current working directory. Any existing files of thesame names are overwritten.

The Configurator command-line syntax is as follows:

conf.bat [options] <oilfile>


The conf.bat command can be found under $OSEK BASE/bin (or%OSEK BASE%\bin).

The OIL file argument is mandatory. It specifies the OIL file to be used for generation.If no OIL file is given, the GUI will be opened.

Generator Command Line Options

The ProOSEK R© generator can be invoked in command line mode via: The followingoptions are available from the command line to control the behavior of the generator:

–help Display usage information-v Display version information-e<file > Load file in GUI mode-o<dir > Set the generation path-I<dir > Set include directory where OIL files will be

searched (can be a semicolon separated list)<oilfile > The name of the OIL file to be processed

Cnf2orti Command Line Options

The ProOSEK R© generator can be invoked in command line mode via:

cnf2orti.bat <options> <infile> [<outfile>]

The following options are available from the command line to control the behavior ofthe cnf2orti tool:

-html Create HTML output.-orti2 0 Create ORTI V2.0 output.-orti2 1 Create ORTI V2.1 output. This is also the default

if no output format is specified.-dot Create output feasible for the AT&T Graphviz dot

tool.<infile > The cnf file to be processed.<outfile > The name of the output file. For html output this

can be also a directory for a framed version. Ifomitted output will go to stdout.


Usage examples

The following command will generate a ProOSEK R© OS (to the directoryc:\mydemo \out ) based on the system configuration given in the file mydemo.oilusing the directories c:\mydemo \libs and c:\mydemo \headers as include direc-tories:

conf.bat -o c:\mydemo\out -I c:\mydemo\libs;c:\mydemo\headers

mydemo.oil

The following command will load the system configuration c:\mydemo \mydemo.oilin GUI mode:

conf.bat -e c:\mydemo\mydemo.oil

4.8 Plug-ins

The file menu.men in the directory $OSEK BASE/data (or %OSEK BASE%\data inDOS/Windows) defines entries which will appear in the plugin menu of the configu-rator. It can be used to run various programs or even .jar files which may be usefulduring configuration of the system. It can be used for example to modify the OILfile being edited or the generated OS files. The format of the menu.men file is asfollows:

Java plugins (.jar files)

• J <validity> <menuentry> <classname> <jarfile>

Executable file plugins

• E <validity> <menuentry> <wait> <command> [<parameters>]

Valid values for each of the parameters are as follows:

• <validity> This parameter defines when the plugin should be shown.


– A - Always shown on the menu

– E - Only available when a OIL file has been loaded into the Configurator.

– D - Only available when no OIL file has been loaded into the configurator.

• <wait> This parameter defines if the Configurator should halt and wait foroutput of the created process

– Y - Wait and show afterwards the standard output of the process

– N - Return immediately, do not collect output

• <menuentry> The name to appear on the plugin menu for this command

• <classname> The name of the class to call. This class must implement theWorkbench.ConfiguratorPlugin interface.

• <jarfile> The name of the .jar file which contains the class tobe called (and specified by classname). This file must be lo-cated in $OSEK BASE/data/plugins (or %OSEK BASE%\data\plugins forDOS/Windows).

• <command> [<parameters>} The program to be executed. If required, %Owill be substituted for the environment variable OSEK BASE.

• <parameters> is optional. Some useful options for the parameters are asfollows:

– %o - this will be substituted with the name of the OIL file currently open inthe Configurator.

– %O - this will be substituted with the currently OSEK BASE directory.

– %t - this will be substituted with the current template file.

– %c - this will be substituted with the current os.cnf file.

– %C - this will be substituted with the current os.c file.

– %h - this will be substituted with the current os.h file.

Some examples of valid entries in the menu.men file are as follows:

J A add_5_alarms AddFiveAlarms MyOILEdit.jar


This is an example of using a java plugin (J denotes that it is a java plu-gin). It will always be available on the plugins menu (denoted by A), and themenu entry on the plugin entry will be called add 5 alarms. When the menuentry add 5 alarms is ProOSEK R© UsersGuide clicked, the class AddFiveAlarmsfrom MyOILEdit.java (which resides in the directory $OSEK BASE/java/plugins or%OSEK BASE%\java\plugins) will be called. This class must implement the Work-bench.ConfiguratorPlugin interface.

E A display_oil_file more %o

This is an example of using an executable file as a plugin (denoted by the E). It will al-ways be available on the plugin menu (denoted by A). The menu entry for this pluginwill be display oil file. When the menu entry display oil file is clicked from the pluginmenu, the command .more %o. will be executed where %o will be substituted by theConfigurator with the name of the OIL file currently open in the configurator. Moreexamples can be found in the menu.men file. The Workbench.ConfiguratorPlugininterface The Workbench.ConfiguratorPlugin interface is as follows:

package dreisoft.proosek.Workbench;

public interface ConfiguratorPlugin {

public void run(dreisoft.proosek.Objects.Oil o,

dreisoft.proosek.Workbench.CfgConfigurator c);

}

All classes to be called from the plugin menu must implement this interface!

4.9 Update Packages

Often new derivates from a particular architecture are created which differ onlyslightly from a previous derivate. ProOSEK R© provides the ability to load updatepackages which provide support for these new derivates without having to installan entire new version. Similarly, update packages can also be used to add BSPs,patches and so on. Update packages can be loaded from the Options menu, usingthe command ”load update packages..”. Note that it is not possible to load an update


package whilst an OIL file is currently opened in the Configurator window. If that isthe case, close the currently opened OIL file, load the update package and re-openthe OIL file.

Syntax

• Lines starting with # are comments

• The very first line must be VERSION 1.0

• The architecture is specified using ARCH <xxx>

• COPY <infile> <outfile> : <infile> must be a path relative to the update file;<outfile> is interpreted as a filename relative to the OSEK BASE, if there aremissing directories these will be created.

• ADDOIL DERIVATE <name> inserts derivate <name> into$OSEK BASE/data/OIL/DERIVATE<arch>

• ADDOIL TIMER <name> inserts timer <name> into$OSEK BASE/data/OIL/TIMER.<arch>

• APPEND <infile> <outfile> like COPY but appends the files.

AProOSEK OS API Reference

OS

NAME OSthe ProOSEK R© operating system API

DESCRIPTION This module provides a general description of the ProOSEK R©operating system API.

APPENDIX A. PROOSEK OS API REFERENCE 97

BASIC DATATYPES

The ProOSEK R© kernel uses a number of data types which arelisted below.

AlarmBaseType A structure holding the characteristics of thecounter associated with an alarm. The fields of the struc-ture include the following:

• maxallowedvalueThe maximum count before the counter rolls over.

• ticksperbaseThe number of ticks required to reach a counter-specific unit.

• mincycleThe minimum number of ticks required for a cyclicalarm (extended mode only).

AlarmBaseRefType A reference to a variable of type Alarm-BaseType .

AlarmType An alarm identifier.

EventMaskType An event identifier.

EventMaskRefType A pointer to a variable of type EventMask-Type .

ResourceType A resource identifier.

TaskType A task identifier.

TaskRefType A pointer to a variable of type TaskType .

TaskStateType A task state descriptor. The possible values arelisted below in the section CONSTANTS.

TaskStateRefType A pointer to a variable of type TaskState-Type .

StatusType The status returned by the system calls. The statuscan either be E OK if the service was executed success-fully, or one of the error codes listed below.

TickType A counter value in ticks.

TickRefType A pointer to a variable of type TickType .


CONSTANTS The ProOSEK R© kernel uses the following constants:

Task states (type TaskStateType ):

Name DescriptionRUNNING Task is in the running stateWAITING Task is in the waiting stateREADY Task is in the ready state.SUSPENDED Task is in the suspended state.

Alarm base values of the system counter:

Name DescriptionOSMAXALLOWEDVALUE The maximum tick count before the

counter rolls over.OSTICKSPERBASE The number of system counter

ticks required to reach a specificunit

OSMINCYCLE The minimum number of ticks re-quired for a cyclic alarm.

OSTICKDURATION The duration of a system countertick in nanoseconds.

Alarm base values of other counters:(where x is the name of the counter):


Name DescriptionOSMAXALLOWEDVALUE x The maximum tick count before

counter x rolls over.OSTICKSPERBASE x The number of ticks required to

reach a specific unit.OSMINCYCLE x The minimum allowed number of

ticks required for a cyclic alarm ofcounter x.

Other Constants:

Name Type DescriptionINITIAL INTERRUPTDESCRIPTOR

IntDescriptorType The interrupt de-scriptor at startup

RES SCHEDULER ResourceType The scheduler re-source

INVALID TASK TaskType The ID of an in-valid task

OSDEFAULTAPPMODE AppModeType The default appli-cation mode


ERROR CODES When a failure occurs and debugging is enabled (extendedmode), system services can return one of the following errorcodes:

E OS ACCESS = 1E OS CALLEVEL = 2E OS ID = 3E OS LIMIT = 4E OS NOFUNC = 5E OS RESOURCE = 6E OS STATE = 7E OS VALUE = 8E OS SYS StackOverflow =

20E OS SYS StackUnderflow =

21E OS SYS INIT =

22E OS SYS CONFIG =

23E OS SYS CODE =

24E OS SYS TOOL =

25


ActivateTask()

NAMEActivateTask()activate a task

SYNTAX

StatusType ActivateTask

(

TaskType TaskID /* reference to the task */

/* to be activated */

)

DESCRIPTION This routine activates a task. If the specified task is currentlyin suspended state, its new state after activation will be ready.Otherwise, the activation will be recorded and performed aftertask termination, if permitted.

AVAILABILITY This service may be called from the task and interrupt level. Itmust not be called any longer from the StartupHook() .

RETURNS

E OS LIMIT Too many task activations of TaskID .

E OS ID Task id is invalid (Only reported in extended mode)

E OK otherwise

CONFORMANCE BCC1, BCC2, ECC1, ECC2


AdvanceCounter()

NAMEAdvanceCounter()increment the given counter by one

SYNTAX

StatusType AdvanceCounter

(

CounterName /* name of a counter */

)

DESCRIPTION This routine increments the given counter by one. There is onlyone AdvanceCounter() (or IAdvanceCounter() ) possible for acounter. The user has to take care that only one task calls thefunction for a specific counter at a given time. More calls to Ad-vanceCounter() of one counter in parallel may result in an un-predictable behavior.

AVAILABILITY This service is called only from the task level and not from theinterrupt level. For incrementing counters within an interrupt, seeIAdvanceCounter() .

RETURNS E OK



ALARMCALLBACK()

NAMEALARMCALLBACK()define an alarm-callback

SYNTAX

ALARMCALLBACK(alarmcallbackname){

/* callback code */

}

DESCRIPTION This routine defines an alarm-callback to be run by an alarm.

CAVEAT This routine is running in the context of (I)AdvanceCounter(). Itmay be necessary to increase stack sizes or even to introduce adummy ISR to increase the stack size of the counter.

RETURNS N/A



CancelAlarm()

NAMECancelAlarm()reset the expiration time of an alarm

SYNTAX

StatusType CancelAlarm

(

AlarmType AlarmID /* reference to an alarm */

)

DESCRIPTION This routine resets the expiration time of the specified alarm.

AVAILABILITY This service may be called from the task level and from the inter-rupt level.

RETURNS

E OS NOFUNC This alarm is not in use. This means that it hasnot been wound up after the last call to CancelAlarm() , ornever at all.

E OS ID only extended mode: not a valid alarm ID.

E OK otherwise



ChainTask()

NAME ChainTask()terminate a task after having activated another task

SYNTAX

StatusType ChainTask

(

TaskType TaskID /* reference to the task */

/* to be activated */

)

DESCRIPTION This routine causes the termination of the calling task, allowingthe task specified with TaskID to be activated. This service pre-vents overlapped execution of a terminating task with its succes-sor.If the calling task and its successor are identical, the chained callsare not regarded as multiple activations.A successful call to ChainTask() results in rescheduling.

AVAILABILITY This routine may be called from the task level only.

CAVEAT The calling task must have released all resources before callingChainTask() .In standard mode, however, failure to release any resources willnot stop the task from terminating even though it still holds re-sources.In extended mode, however, if the task still holds resources, anerror status value is returned which can be evaluated by the ap-plication.Returning from a task’s top level function without a call to eitherChainTask() or TerminateTask() results in an undefined state ofthe system.


RETURNS

E OS LIMIT Too many task activations of TaskID . (also reportedin standard mode).

E OS ID only extended mode: this is an invalid TaskID .

E OS RESOURCE only extended mode: this task still occupiesresources.

E OS CALLEVEL only extended mode: this routine cannot becalled from an ISR.

E OK otherwise



ClearEvent()

NAMEClearEvent()clear one or more events

SYNTAX

StatusType ClearEvent

(

EventMaskType Mask /* event mask */

)

DESCRIPTION The events of the calling extended task are cleared according tothe event mask.

AVAILABILITY This service is restricted to the extended task which owns theevent.

RETURNS

E OS ACCESS only extended mode: This is not an extendedtask.

E OS CALLEVEL only extended mode: This routine cannot becalled from an ISR.

E OK otherwise

CONFORMANCE ECC1, ECC2


DeclareAlarm()

NAME DeclareAlarm()external declaration of an alarm

SYNTAX

DeclareAlarm

(

AlarmType AlarmID /* alarm reference */

)

DESCRIPTION This routine is a macro that translates to an external declarationof an alarm. This service is to be used in the same way as theexternal declaration of variables.

AVAILABILITY This declaration may be used outside all tasks, ISRs, and func-tions.



DeclareEvent()

NAME DeclareEvent()external declaration of an event

SYNTAX

DeclareEvent

(

EventMaskType Event /* event mask */

)

DESCRIPTION This routine is a macro that translates to an external declarationof an event mask. This service is to be used in the same way asthe external declaration of variables.




DeclareResource()

NAME DeclareResource()external declaration of a resource

SYNTAX

DeclareResource

(

ResourceType ResID /* resource reference */

)

DESCRIPTION This routine is a macro that translates to an external declarationof a task. This service is to be used like the external declarationof variables.




DeclareTask()

NAME DeclareTask()external declaration of a task

SYNTAX

DeclareTask

(

TaskType TaskID /* task reference */

)

DESCRIPTION This routine is a macro that translates to an external declarationof a task. This service is to be used like the external declarationof variables.




DisableAllInterrupts()

NAME DisableAllInterrupts()disable all interrupts

SYNTAX

void DisableAllInterrupts (void)

DESCRIPTION This routine disables all interrupts and saves the previous statefor the EnableAllInterrupts() service function.

AVAILABILITY This service may be called from the task level and from the ISRlevel. It may not be called from any hook routine.

RETURNS N/A



EnableAllInterrupts()

NAME EnableAllInterrupts()enable all interrupts

SYNTAX

void EnableAllInterrupts (void)

DESCRIPTION This routine restores the interrupt state which was savedduring DisableAllInterrupts() . The exact implementation isarchitecture-dependent.

AVAILABILITY This service may be called from the task level and from the ISRlevel. It may not be called from any hook routine.

RETURNS N/A



ErrorHook()

NAMEErrorHook()a hook routine for error situations

SYNTAX

void ErrorHook

(

StatusType Error /* the error code */

)

DESCRIPTION This hook routine is called by the operating system at the endof a system service if the status returned by the service isother than E OK. It is called before the system returns to thetask level. ErrorHook is never called recursively.Further information on the cause of the error can be re-trieved by using the services OSErrorGetServiceId() and OS-Error x1 x2(). GetTaskID() can be used to get the ID of thetask which produced the error.

CAVEAT The implementation of this routine is up to the application.



GetActiveApplicationMode()

NAMEGetActiveApplicationMode()get the current application mode

SYNTAX

AppModeType GetActiveApplicationMode (void)

DESCRIPTION This routine returns the current application mode. It is used towrite mode-dependent code.

AVAILABILITY This service is called from the interrupt level, task level, andfrom all hook routines.



GetAlarm()

NAMEGetAlarm()get the remaining time to alarm expiration

SYNTAX

StatusType GetAlarm

(

AlarmType AlarmID, /* reference to */

/* an alarm */

TickRefType Tick /* relative time in */

/* ticks to expiration */

)

DESCRIPTION This routine returns the relative value in ticks until the specifiedalarm expires.

CAVEAT If the specified alarm is not in use, the value stored in Tick isnot defined.

AVAILABILITY This service may be called from the task level, interrupt level,and from the hook routines PreTaskHook() , PostTaskHook() ,and ErrorHook() .

RETURNS

E OS NOFUNC This alarm is not in use. This means thatit has not been wound up after the last call to Cance-lAlarm() , or never at all.

E OS ID only extended mode: This is not a valid alarm ID.

E OK otherwise



GetAlarmBase()

NAMEGetAlarmBase()read the information base of an alarm

SYNTAX

StatusType GetAlarmBase

(


/* an alarm */

AlarmBaseRefType Info /* reference to */

/* the alarm base */

)

DESCRIPTION This routine gets the alarm base characteristics of the spec-ified alarm. Info is a reference to the location where the re-turned information of type AlarmBaseType is stored.


RETURNS


E OK otherwise



GetEvent()

NAMEGetEvent()get event mask

SYNTAX

StatusType GetEvent

(

TaskType TaskID, /* reference to */

/* the task id */

EventMaskRefType Event /* reference to */

/* the event mask */

)

DESCRIPTION This routine gets the current state of all event bits of the spec-ified task. It does not give any information about the eventsthe task is waiting for. The current status of the event mask iscopied to the location specified by Event .


RETURNS

E OS ID only extended mode: referenced task id is invalid.

E OS ACCESS only extended mode: referenced task an ex-tended task.

E OS STATE only extended mode: referenced task is in thesuspended state.

E OK otherwise




GetResource()

NAMEGetResource()enter a critical section of code

SYNTAX

StatusType GetResource

(

ResourceType ResID /* reference to */

/* the resource */

)

DESCRIPTION This routine allows the calling task to enter a critical sectionassociated with the specified resource. Each call to GetRe-source() must be matched by a call to ReleaseResource() .

CAVEAT Nested critical sections must be strictly stacked, that is, if Re-source Y has been acquired after Resource X, then it mustbe released before Resource X. A task cannot enter the samecritical section twice without leaving it.Matching calls to GetResource() and ReleaseResource()should appear within the same function body.The services TerminateTask() , ChainTask() , and Wait-Event() must not be used in critical sections.Depending on the architecture, resources may also be used tocoordinate tasks with interrupts.

AVAILABILITY This service may be called from the task level and from theinterrupt level.


RETURNS

E OS ID only extended mode: This is an invalid resource ID.

E OS ACCESS only extended mode: Access is denied to thisresource.

E OK otherwise



GetTaskID()

NAMEGetTaskID()get the task ID of a running task

SYNTAX

StatusType GetTaskID

(

TaskRefType TaskID /* ref. to RUNNING task */

)

DESCRIPTION This routine returns the task ID of the task which is cur-rently active. The ID is returned via the parameter TaskID .If there is no currently active task, the TaskID returned is IN-VALID TASK .

AVAILABILITY This service may be called from the task level, ISR level andfrom the hook routines PreTaskHook() , PostTaskHook() , andErrorHook() .

RETURNS E OK



GetTaskState()

NAMEGetTaskState()get the state of a task

SYNTAX

StatusType GetTaskState

(

TaskType TaskID, /* reference to task */

TaskStateRefType State /* reference to */

/* task state */

)

DESCRIPTION This routine returns the scheduling state of a task (running,ready, waiting, suspended) into the variable State at the timeGetTaskState() was called.The ID of the task to be queried is given as the parameterTaskID .

AVAILABILITY This service may be called from the task level, the inter-rupt level, and from the hook routines PreTaskHook() , Post-TaskHook() , and ErrorHook() .

CAVEAT In a fully preemptive system, the result may already be out-dated by the time it is evaluated. Moreover, in such a system,the result can only be meaningful if the task runs with inter-rupts disabled.

RETURNS

E OS ID only extended mode: An invalid Task ID was passedto the function. In this case State will be undefined.

E OK otherwise




IAdvanceCounter()

NAMEIAdvanceCounter()increment the given counter by one from interrupt routine

SYNTAX

StatusType IAdvanceCounter

(

CounterName /* name of a counter*/

)

DESCRIPTION This routine increments the given counter by one. There isonly one IAdvanceCounter() (or AdvanceCounter() ) possi-ble for a counter. The user has to take care that only one ISRcalls the function for a specific counter at a given time. Morecalls to IAdvanceCounter() of one counter in parallel may re-sult in an unpredictable behavior.

AVAILABILITY This service may be called only from the interrupt level andnot from the task level. For incrementing counters within atask, see AdvanceCounter() .

RETURNS E OK



OSErrorGetServiceId()

NAMEOSErrorGetServiceId()a macro providing the service identifier where the error hasrisen

SYNTAX

OSServiceIdType OSErrorGetSercviceId()

DESCRIPTION This macro returns the service identifier of the system ser-vice which called ErrorHook() . Possible values are OSServi-ceId xx where xx is the name of the system service.

CAVEAT This macro must only be called inside ErrorHook() . This ser-vice is only available if USEGETSERVICEID was chosen inthe oil file.

RETURNS OSServiceID xx where xx is the name of the service.



OSError x1 x2()

NAMEOSError x1 x2macros providing the parameters of the service where the er-ror has risen

SYNTAX

OSError_x1_x2()

DESCRIPTION This macro returns the parameters x2 of the sys-tem call x1 which called ErrorHook() . E.g. OSEr-ror ActivateTask TaskID() will return the task ID of the taskfor which ActivateTask() was called.


INCARNATIONS

• OSError ActivateTask TaskID()

• OSError CancelAlarm AlarmID()

• OSError ChainTask TaskID()

• OSError ClearEvent Mask()

• OSError GetAlarmBase AlarmID()

• OSError GetAlarmBase Info()

• OSError GetAlarm AlarmID()

• OSError GetAlarm Tick()

• OSError GetEvent Event()

• OSError GetEvent TaskID()

• OSError GetResource ResID()

• OSError GetTaskID TaskID()

• OSError GetTaskState State()

• OSError GetTaskState TaskID()

• OSError ReleaseResource ResID()

• OSError SetAbsAlarm AlarmID()

• OSError SetAbsAlarm cycle()

• OSError SetAbsAlarm start()

• OSError SetEvent Mask()

• OSError SetEvent TaskID()

• OSError SetRelAlarm AlarmID()

• OSError SetRelAlarm cycle()

• OSError SetRelAlarm increment()

• OSError WaitEvent Mask()


CAVEAT This macro may only be called inside ErrorHook() . Prior tocalling this function OSErrorGetServiceId() must be called todetermine the service x1. Otherwise arbitrary values will bereturned. This service is only available if USEPARAMETER-ACCESS was set to true in the OS object.

RETURNS the parameter of the system call.



PostTaskHook()

NAMEPostTaskHook()a hook routine for tasks leaving the running state

SYNTAX

void PostTaskHook (void)

DESCRIPTION This hook routine is called by the operating system when atask is terminated or preempted. When the hook is called, thetask is in the running state.

CAVEAT The implementation of this routine is the responsibility of theapplication.

RETURNS N/A



PreTaskHook()

NAMEPreTaskHook()a hook routine for tasks entering the running state

SYNTAX

void PreTaskHook (void)

DESCRIPTION This hook routine is called by the operating system when thescheduler switches to a new task. When the hook is called,the task is in the running state.

CAVEAT The implementation of this routine is the responsibility of theapplication.

RETURNS N/A



ReleaseResource()

NAMEReleaseResource()leave a critical section

SYNTAX

StatusType ReleaseResource

(

ResourceType ResID /* reference to */

/* the resource */

)

DESCRIPTION This routine allows the calling task to leave a critical sec-tion associated with the specified resource. It is the counter-part of GetResource() . Each call to GetResource() must bematched by a call to ReleaseResource() .

AVAILABILITY This service may be called from the task level and from theinterrupt level.

RETURNS

E OS ID only extended mode: This is an invalid resource ID.

E OS ACCESS only extended mode: Access is denied to thisresource.

E OS NOFUNC only extended mode: This resource cannotbe released at this point. This is the case either becausethe task does not hold the resource or because the nest-ing rules require that the task releases another resourcefirst.

E OK otherwise




ResumeAllInterrupts()

NAMEResumeAllInterrupts()enable all interrupts

SYNTAX

void ResumeAllInterrupts (void)

DESCRIPTION This routine is the counterpart of SuspendAllInterrupts() andrestores the previous state. Nesting is allowed, the real restor-ing is done on the outermost release call.The exact implementation is architecture-dependent.

AVAILABILITY This service may be called from the task level, from ISR level,from alarmcallbacks and the hook routines ErrorHook() , Pre-TaskHook() , PostTaskHook() . It must not be called fromStartupHook() and ShutdownHook() .

RETURNS N/A



ResumeOSInterrupts()

NAMEResumeOSInterrupts()enable all category 2 and 3 interrupts

SYNTAX

void ResumeOSInterrupts (void)

DESCRIPTION This routine is the counterpart of SuspendOSInterrupts() andrestores the previous state. Nesting is allowed, the real restor-ing is done on the outermost release call.The exact implementation is architecture-dependent.

AVAILABILITY This service may be called from the task level and from ISRlevel. It must not be called from any hook routine.

RETURNS N/A



Schedule()

NAMESchedule()one task should yield to another task

SYNTAX

StatusType Schedule (void)

DESCRIPTION This routine causes the calling task to yield its execution infavor of a task with higher priority. If no such task is in theready state, the calling task is continued.

REMARKS This service has no effect on fully preemptive tasks.

RETURNS

E OS CALLEVEL only extended mode: This routine cannotbe called from an ISR.

E OK otherwise



SetEvent()

NAMESetEvent()set one or more events in the event mask of a task

SYNTAX

StatusType SetEvent

(

TaskType TaskID, /* reference to */

/* the task ID */

EventMaskType Mask /* reference to */

/* the event mask */

)

DESCRIPTION This routine sets the events in the event mask of the speci-fied task according to the specified event mask. If the taskhas been waiting for at least one of the events specified in themask, it enters the ready state. Any events not set in the eventmask remain unchanged.

AVAILABILITY This service is called from the task level and from the interruptlevel.

RETURNS

E OS ID only extended mode: This is an invalid task ID.


E OS STATE only extended mode: This task is in the sus-pended state.

E OK otherwise




SetAbsAlarm()

NAMESetAbsAlarm()set the absolute expiration time of the specified alarm

SYNTAX

StatusType SetAbsAlarm

(


/* the alarm element */

TickType start, /* absolute expiration */

/* time in ticks */

TickType cycle /* cycle value */

)


DESCRIPTION This routine sets the absolute expiration time of the specifiedalarm to start ticks. When the counter associated with thisalarm has reached the specified number of ticks, an actionassociated with the alarm is triggered. Two types of actionsare possible, depending on the configuration of the alarm:

• a user-defined task is activated

• a user-defined event is set for a user-defined task (ex-tended tasks only).

If cycle is greater than zero the alarm element is wound upcyclically each time it expires; the relative expiration time is setto cycle .The specified alarm must not be in use when SetAbsAlarm()is called. Use CancelAlarm() to cancel the current expirationtime before you set a new one.The system service occupies the alarm AlarmID .When startticks are reached, the task assigned to the alarm AlarmID isactivated or the assigned event (only for extended tasks) is set.

CAVEAT If start is very close to the current value of the counter, thealarm may expire immediately and the task associated withthe alarm may become ready.If the counter has reached the value start before the call toSetAbsAlarm() , the alarm will only expire when the value isreached again, that is after the counter has rolled over.

AVAILABILITY This service may be called from the task level and the interruptlevel.


RETURNS

E OS STATE This alarm is already in use.


E OS VALUE only extended mode:

The value of start is out of range, i.e. lower than zero orhigher than MAXALLOWEDVALUE .

The value of cycle is out of range, i.e. lower than MIN-CYCLE or higher than MAXALLOWEDVALUE .

E OK otherwise

CONFORMANCE If action on expiration is activate task : BCC1, BCC2;always: ECC1, ECC2.


SetRelAlarm()

NAMESetRelAlarm()set an alarm relative to the current time

SYNTAX

StatusType SetRelAlarm

(


/* an alarm */

TickType increment, /* relative expiration */

*/ time in ticks */

TickType cycle /* cyclic relative */

/* expiration time */

)


DESCRIPTION This routine sets the relative expiration time of the specifiedalarm to increment ticks from the current value of the counterassociated with this alarm. When the specified number of tickshas elapsed, an action associated with the alarm will be trig-gered. Two types of actions are possible, depending on theconfiguration of the alarm:

• a certain task is activated

• a certain event is set for a certain task (extended tasksonly).

If cycle is greater than zero the alarm element is wound upcyclically each time it expires; the relative expiration time is setto cycle .The specified alarm must not be in use when SetRelAlarm()is called. Use CancelAlarm() to cancel the current expirationtime before you set a new expiration time.

CAVEAT If increment is very small, the alarm may expire immediatelyand the task associated with the alarm may become ready.The expiration time for an increment of 1 is between 0 and thetime in nanoseconds specified for the counter. (not countinginterrupt locks)If increment is zero the alarm will expire after a full round ofthe counter. Since the result of using an increment of zerois up to the implementation, the use of this feature makes theapplication code harder to port to other platforms.

AVAILABILITY This service may be called from the task level and the interruptlevel.


RETURNS

E OS STATE This alarm is already in use.


E OS VALUE only extended mode:

The value of increment is out of range, i.e. lower thanzero or higher than MAXALLOWEDVALUE .

The value of cycle is out of range, i.e. lower than MIN-CYCLE or higher than MAXALLOWEDVALUE .

E OK otherwise

CONFORMANCE If action on expiration is activate task : BCC1, BCC2;always: ECC1, ECC2.


ShutdownHook()

NAMEShutdownHook()a hook for the shutdown

SYNTAX

void ShutdownHook

(

StatusType Error /* the error that caused */

/* the shutdown */

)

DESCRIPTION This hook routine is called by the operating system when theOS service ShutdownOS() has been called. This hook iscalled after the operating system shutdown.



ShutdownOS()

NAMEShutdownOS()shut down the operating system

SYNTAX

void ShutdownOS

(

StatusType Error /* the error that causes */

/* the shutdown */

)

DESCRIPTION This routine shuts down the operating system. The user cancall this system service, for example, to halt the system in anemergency. The operating system calls this function internallywhen it reaches an undefined internal state that prevents itfrom operating correctly.This service always calls the ShutdownHook() before shuttingdown the operating system.

AVAILABILITY This service can be called from the interrupt level, task level,from the hook routines ErrorHook() , StartupHook() and inter-nally by the operating system.



StartOS()

NAMEStartOS()start the operating system in a specific mode

SYNTAX

void StartOS

(

AppModeType Mode /* application mode */

)

DESCRIPTION This routine starts the operating system in the specified ap-plication mode. The application modes are specified in OIL.Depending on it tasks and alarms are started automatically.

AVAILABILITY This service may only be called from outside the operatingsystem.



StartupHook()

NAMEStartupHook()a hook routine for system startup

SYNTAX

void StartupHook (void)

DESCRIPTION This hook routine is called by the operating system betweensystem initialization and scheduler startup. The applicationcan use the hook to initialize device drivers and system ob-jects such as counters and alarms or to activate tasks.

RETURNS N/A



SuspendAllInterrupts()

NAMESuspendAllInterrupts()disable all interrupts

SYNTAX

void SuspendAllInterrupts (void)

DESCRIPTION This routine disables all interrupts and saves the previousstate. Nested calls to this function are allowed. The exactimplementation is architecture-dependent.

AVAILABILITY This service may be called from the task level, from ISR level,from alarmcallbacks and the hook routines ErrorHook() , Pre-TaskHook() , PostTaskHook() . It must not be called fromStartupHook() and ShutdownHook() .

RETURNS N/A



SuspendOSInterrupts()

NAMESuspendOSInterrupts()disable all category 2 and 3 interrupts

SYNTAX

void SuspendOSInterrupts (void)

DESCRIPTION This routine disables all category 2 and 3 interrupts and savesthe previous state. Nested calls to this function are allowed.The exact implementation is architecture-dependent.

AVAILABILITY This service may be called from the task level and from theISR level. It must not be called from any hook routine.

RETURNS N/A



TerminateTask()

NAMETerminateTask()terminate the execution of a task

SYNTAX

StatusType TerminateTask (void)

DESCRIPTION This service causes the termination of the calling task. Thecalling task is transferred from the running state into the sus-pended state.A successful call to TerminateTask() results in rescheduling.

AVAILABILITY This routine may be called from the task level only.

CAVEAT The task must have released all resources before calling Ter-minateTask() .In standard mode, the task will be terminated even if it stillholds resources. In extended mode, the service returns anerror and delivers a status value which can be evaluated bythe application.If the call was successful, TerminateTask() does not return tothe call level and the status cannot be evaluated.Returning from a tasks top level function without a call to eitherTerminateTask() or ChainTask() results in an undefined stateof the system.

RETURNS In standard mode, there is no return to call level. In extendedmode, there is no return on successful completion, otherwiseerror.


ERRNO E OS RESOURCEThis task still occupies resources.E OS CALLEVELThis routine cannot be called from an ISR.



WaitEvent()

NAMEWaitEvent()set the calling task to the waiting state

SYNTAX

StatusType WaitEvent

(

EventMaskType Mask /* reference to */

/* an event mask */

)

DESCRIPTION This routine sets the calling task to the waiting state unless atleast one of the events specified in the task’s event mask isset.When at least one of the events is set in the task’s event mask,the task is put back to the ready state and rescheduling isenforced.

AVAILABILITY This service may be called only by an extended task owningthe event.

RETURNS


E OS RESOURCE only extended mode: This task occupiesresources.

E OS CALLEVEL only extended mode: This routine cannotbe called from an ISR.

E OK otherwise



BOSEK Communications API

Reference

COM

NAME COMthe OSEK communication API

DESCRIPTION This module provides a general description of the OSEK commu-nication API.

BASIC DATATYPES

OSEK uses the status types for all status information that APIservices offer.

NAMINGCONVENTIONS

All return values of OSEK application API services start with EOSEKCOM services begin with E COM

APPENDIX B. OSEK COMMUNICATIONS API REFERENCE 156

ERROR CODES The following are OSEK COM defined error codes:

Error Code Description of Error CodeE OK No error, service call was successfulE COM BUSY Message locked by application (unqueued

WithoutCopy messages only)E COM ID Invalid message name passed as parame-

terE COM LIMIT Overflow of FIFO buffer (queued messages

only)E COM LOCKED Service call rejected as message object

locked by systemE COM NOMSG No message available (queued messages

only)


StartCOM()

NAME StartCOM()start the communication module

SYNTAX

StatusType StartCOM (void)

DESCRIPTION The StartCOM( ) service starts the OSEK communicationmodule. This routine performs the initialization of OSEK COMimplementation-specific internal states and variables. It alsoinitializes the communication hardware by calling a setup func-tion typically provided by the vendor of the respective devicedriver. To initialize the application-specific messages, Start-COM( ) calls the MessageInit( ) function provided by the appli-cation programmer. If StartCOM( ) succeeds it returns E OK,otherwise it returns an error code indicating the nature of thefailure.

RETURNS E OK, if there is no error; otherwise, E COM XXX forapplication- or driver-specific error codes.


MessageInit()

NAME MessageInit()initialize all message objects

SYNTAX

StatusType MessageInit (void)

DESCRIPTION This routine initializes all application specific message objects.This function has to be provided by the application program-mer (either manually or via an off-line-tool) and can only becalled by the StartCOM( ) routine. If MessageInit( ) returnsany code other than E OK the initialization of application spe-cific messages has failed. StartCOM( ) returns the returnvalue of MessageInit( ) .

RETURNS E OK, if there is no error; otherwise, E COM XXX forapplication-specific error codes.


SendMessage()

NAME SendMessage()send a message

SYNTAX

StatusType SendMessage

(

SymbolicName Message, /* Symbolic Name */

/* of Message Object */

AccessNameRef Data /* Message Data */

)

DESCRIPTION This service updates the message object Message dependingon the copying and queuing configuration. If the message isqueued then this service will try to add Data to the queue andupdate the write pointer of the queue. If the message is un-queued and WithCopy it will overwrite the message buffer withthe new Data. If the message is unqueued and WithoutCopythen no update to the message object is performed since nobuffer is used to interface with Message . Only the status isupdated.If a notification mechanism has been associated with the mes-sage object Message then it will be triggered.

NOTE

This is NOT an atomic action!

The message may be received beforethe notification mechanism has been exe-cuted.


RETURNS

E OK if there is no error.

E COM LOCKED if the message object is locked, or if a With-Copy message is set to BUSY.

E COM ID if the parameter Message is invalid and the OS isrunning in extended mode.


ReceiveMessage()

NAME ReceiveMessage()receive a message

SYNTAX

StatusType ReceiveMessage

(



AccessNameRef Data /* Message Data */

)

DESCRIPTION This service delivers the message data associated with themessage object Message depending on the copying andqueuing configuration. If the message is queued then this ser-vice will try to update the message data referenced by Datawith the oldest message and if successful, update the readpointer to the queue. If the message is unqueued and With-Copy it will update the message referenced by Data with what-ever is in the message buffer of the message object Message .If the message is unqueued and WithoutCopy then only a ser-vice status is returned since the application accesses the mes-sage object directly.


RETURNS

E OK if there is no error.

E COM LOCKED if the message object is locked, or if a With-Copy message is set to BUSY.

E COM NOMSG if the FIFO queue of a queued message isempty (queued messages only).

E COM LIMIT if the FIFO queue of a queued message isfull (indicates that at least one message has been lost,queued messages only).



GetMessageStatus()

NAME GetMessageStatus()get the status of a message

SYNTAX

StatusType GetMessageStatus

(

SymbolicName Message /* Symbolic Name */


)

DESCRIPTION The service returns the current status of the message ob-ject Message . If this service call fails, it has to return animplementation-specific error code that can be distinguishedfrom all other return values.

RETURNS This service call can return the following values (where theprecedence follows the order of the list, i.e. E COM LOCKEDhas highest precedence):

E COM LOCKED if the message object is locked by the sys-tem.

E COM BUSY if the message is currently set to BUSY (i.e.locked by the application).

E COM NOMSG if the FIFO queue of a queued message iscurrently empty (queued messages only).

E COM LIMIT if an overflow of the FIFO queue occurred.


E OK if none of the above error conditions were met.


GetMessageResource()

NAME GetMessageResource()lock a message object

SYNTAX

StatusType GetMessageResource

(



)

DESCRIPTION This service sets the status of the message object Messageto BUSY. It should be used to support the transfer of Without-Copy messages.

RETURNS

E COM LOCKED if the message object is locked.

E COM BUSY if the message Message is already set toBUSY.


E COM OK if Message is successfully set to BUSY.


ReleaseMessageResource()

NAME ReleaseMessageResource()unlock a message object

SYNTAX

StatusType ReleaseMessageResource

(



)

DESCRIPTION This service unconditionally sets the status of the messageobject Message to NOT BUSY. It should be used togetherwith GetMessageResource() to support the transfer of With-outCopy messages.

RETURNS


E COM OK after Message has been set to NOT BUSY.


ReadFlag()

NAME ReadFlag()get the status of a flag

SYNTAX

FlagValue ReadFlag

(

FlagType FlagName, /* Message Flag Name */

)

DESCRIPTION This service returns the value of the specified notification flag.

RETURNS

TRUE if the associated message was sent.

FALSE otherwise.


ResetFlag()

NAME ResetFlag()reset the status of a flag

SYNTAX

StatusType ResetFlag

(

FlagType FlagName, /* Message Flag Name */

)

DESCRIPTION This service sets the value of the specified notification flag toFALSE .

RETURNS

E OK

COSEK Error Codes

When generating or verifying a ProOSEK R© configuration the code generator mayissue the following errors. The error is printed in the Message Window of the Gener-ator or to the standard output in command line mode with the following information:

Code The ErrorCode

Short Description A short description of the error (printed in italic in the followingtables

Architecture specific codes can be found in the architecture notes for the corre-sponding hardware architecture.

APPENDIX C. OSEK ERROR CODES 169

Errors

Code DescriptionE CHECK 0001 More than <number> resources configured!

You have specified too many resources. Refer to the User’sGuide to find out the maximum number supported by the kernelin your configuration (conformance class etc.).

E CHECK 0002 Resource is missing a name!Every resource must have a name. The name is used when call-ing GetResource() or ReleaseResource().

E CHECK 0003 Interrupt <name>: CATEGORY is invalid. Must be 1 or 2.According to the OSEK standard, interupts must be of category 1or category 2. Category 3 interrupts are no longer supported andshould be changed to category 2. Category 1 interrupts shouldbe used when no system services are called from the ISR. (ex-cept for the disable and enable interrupt functions. Refer to theUser’s Guide for details). Category 2 interrupts should be usedwhen system services are called from the ISR. when defining aninterrupt with the ISR macro.

E CHECK 0004 More than <number> alarms configured!The number of alarms exceeds the maximum allowed number.You must reduce the number of alarms.

E CHECK 0005 Alarm is missing a name!Every alarm needs a name. The name is used when calling thefunction SetRelAlarm(), etc.

E CHECK 0006 Alarm <name> specifies no counterEvery alarm needs a counter where the alarm is bound. A alarmwithout a counter cannot be triggered and is therefore useless.

E CHECK 0007 Alarm <name> specifies an invalid counter <name>The counter argument of the alarm is invalid. Maybe the counter-name has changed or the counter does not exists any more.


E CHECK 0008 Alarm <name> does not specify a taskThe alarm has no defined task for the alarm-action. You mustdefine a task which is either activated or gets a specified event ifthe alarm expires.

E CHECK 0009 Alarm <name> specifies an invalid task <name>The task to be activated or to get an event from the alarm doesnot exist. Maybe the name of the task has changed or the taskwas removed from the current configuration.

E CHECK 0010 Alarm <name> uses SetEvent with a BASIC taskIf the alarm does a SetEvent, then the specified task must be anextended task.

E CHECK 0011 Alarm <name> uses SetEvent, but does not specify an eventThe alarm uses SetEvent as the action, but no event is specifiedto be used.

E CHECK 0012 Alarm <name> specifies an invalid event <name>The alarm specifies an event which is not defined as an eventin the current configuration. Maybe there is a misspelling, or theevent was renamed or removed.

E CHECK 0013 Alarm <name> specifies an event which is not used by the spec-ified taskThe alarm specifies an event which is not used by the given task.Maybe the name is wrong or the task should mark this event asused.

E CHECK 0014 Alarm <name> does not specify a valid actionThe alarm does not specify an action. This means that neither anactivate task nor an event setting is defined in the ACTION field.An alarm without an action is useless.

E CHECK 0015 More than <number> counters configured!The maximum number of counters allowed has been exceeded.One or more of the defined counters must be removed.

E CHECK 0016 Counter is missing a name!Every counter needs a unique name. Counters without a namecannot be used.


E CHECK 0017 Counter <name>: MAXALLOWEDVALUE is invalid or not de-finedEvery counter needs a maximum counter value (MAXALLOWED-VALUE). The counter counts from zero to this value and thenstarts counting again from zero.

E CHECK 0018 Counter <name>: TICKSPERBASE is invalid or not definedEvery counter needs a TICKSPERBASE value, which is a param-eter where the user can define how many ticks occur in a specifictime interval.

E CHECK 0019 Counter <name>: MINCYCLE is invalid or not definedEvery counter needs a minimum cycle. It is used by the systemto check that there is at least some interval between two taskactivations.

E CHECK 0020 Interrupt is missing a name!Every interrupt needs a name. Interrupts without a name makeno sense. The name is also used when defining an interrupt withthe ISR macro.

E CHECK 0021 Event is missing a name!Every event needs a name. Events without a name cannot beused.

E CHECK 0022 Event <name> specifies a mask with multiple bitsIf you specify a mask for an event, there must only be one bit setin the mask.

E CHECK 0023 Event <name> and event <name> use overlapping masksTwo given events are using the same mask and are both usedby one task. Therefore the mask must be different otherwise thetask cannot distinguish between the events.

E CHECK 0024 Event <name>: A valid mask could not be assignedThe event could not be assinged to a mask because too manytasks use this event and there are no more vacant positions inthe eventmask.

E CHECK 0025 Tasks: More than <number> tasks configured!The maximum number of tasks is exceeded. Some tasks mustbe removed.


E CHECK 0026 Task is missing a name!Every task must have a name. The name is used when callingActivateTask() or ChainTask().

E CHECK 0027 Task <name>: BASIC tasks may not specify eventsA basic task cannot use events. Either remove the events fromthe basic task or make the task an extended one.

E CHECK 0028 Task <name>: Specified event <name> does not existThe event specified by the task does not exist. Either the eventwas misspelt, removed or renamed.

E CHECK 0029 Task <name>: Specifies an unknown task type (choose BASICor EXTENDED or AUTO)The type of the task is not known. Choose one of the supportedtypes.

E CHECK 0030 Task <name>: Specified resource <name> does not existThe task uses a resource which does not exists. Maybe the re-source was misspelt, removed or renamed.

E CHECK 0031 Task <name>: Priority out of range (min 0; max <n>)The priority specified in the task is invalid.

E CHECK 0032 Task <name>: Invalid scheduling policy (choose FULL or NON)The task has an unknown scheduling parameter. Every task mustbe either preemptive or non-preemptive. Choose one of FULL orNON depending on the desired behaviour.

E CHECK 0033 Task <name>: ACTIVATION invalid, must be at least 1 activationA task must have at least one activation. Ensure the value isgreater than 0.

E CHECK 0034 Task <name>: Extended tasks may not have more than 1 acti-vationMultiple activation of a task is only allowed for basic tasks.Change the value of ACTIVATION in the Task object.

E CHECK 0035 Task <name>: STACKSIZE invalid or not definedEvery task must have a stack. Since the kernel manages andallocated the stack, it must know how much space to allocated foreach task. Ensure a value is defined for the task’s STACKSIZEparameter.


E CHECK 0036 Number of activations is too big! (maximum=<n>)The number of all activations is too big. The maximum allowedvalue is <n>.

E CHECK 0037 OS: Scheduling must be non-preemptiveThe scheduling of the whole configuration should be non-preemptive. This can be changed in the OS object.

E CHECK 0038 OS: Scheduling must be mixedThe scheduling of the whole configuration should be mixed pre-emptive. This can be changed in the OS object.

E CHECK 0039 OS: Scheduling must be fully preemptiveThe scheduling of the whole configuration should be fully pre-emptive. This can be changed in the OS object.

E CHECK 0040 OS: Conformance class ECC1 does not fit. Reason: MultipleactivationsThe conformance class ECC1 does not fit to your configuration.This is because ECC1 does not allow multiple activations!

E CHECK 0041 OS: Conformance class ECC1 does not fit. Reason: Multipletasks per priorityThe conformance class ECC1 does not fit to your configuration.This is because there are some tasks which share the same pri-ority. Either change the conformance class to ECC2 or assign aunique priority to each task.

E CHECK 0042 Conformance class BCC2 does not fit. Reason: There are<number> EXTENDED tasksThe conformance class BCC2 does not allow EXTENDED tasks.Either change the tasks to BASIC tasks or choose one of theconformance classes ECC1 or ECC2.

E CHECK 0043 Conformance class BCC1 does not fit. Reason: Multiple activa-tionsIn BCC1 no multiple activations are allowed. Either remove themultiple activations from the tasks or change the conformanceclass to BCC2.


E CHECK 0044 Conformance class BCC1 does not fit. Reason: Multiple tasksper priorityBCC1 does not support more than one task per priorty. Eithergive each task a unique priority or change the conformance classto BCC2.

E CHECK 0045 Conformance class BCC1 does not fit. Reason: There are<number> extended tasksBCC1 does not allow any number of extended tasks. Eitherchange the tasks to BASIC tasks or choose conformance classECC1.

E CHECK 0046 ttOS: Only one ttOS object is allowedYou may only define one ttOS object.

E CHECK 0047 OSEKtime requires at least one ttTask to be definedA time-triggered system without any time-triggered tasks (tt-Tasks) is useless.

E CHECK 0048 ttTask: More than 127 ttTasks definedThe maximum number of time-triggered tasks in an OSEKTimesystem is 127

E CHECK 0049 ttOS: Invalid OSEKtime STACKSIZEThe STACKSIZE must be specified in the ttOS object. Ensurethat it contains a valid value.

E CHECK 0052 Alarm <name> does not specify an actionThe alarm has no defined action. Actions can be task activations,the setting of an event or a alarmcallback. Without an action thealarm is useless.

E CHECK 0069 ttOS: Synchronization method is undefinedThe synchronization method of the OSEKTime system needs tobe specified. You may choose either HARD, SMOOTH or NONEdepending on your system configuration. This variable is locatedin the ttOS object under SYNC.

E CHECK 0070 ttOS: Synchronization method is invalidThe synchronization method of the OSEKTime system needs tobe specified. You may choose either HARD, SMOOTH or NONEdepending on your system configuration. This variable is locatedin the ttOS object under SYNC.


E CHECK 0071 ttOS: DISPATCHER ROUND is invalid or undefinedThe length of the dispatcher round must be defined in the ttOSobject. Ensure that this value is greater than 0.

E CHECK 0072 ttOS: MAX DECREASE is invalidWhen using HARD synchronization you have to specify by howmuch the dispatcher round can be shortened in order to regainsychronization to a global time source. This is specified in theMAX DECREASE field of the ttOS object. Ensure that this valueis 0 or positive.

E CHECK 0073 ttOS: Effective length of dispatcher round is invalidWhen using HARD synchronization the effective length of thedispatcher round is: DISPATCHER ROUND - MAX DECREASE.This value must be positive. Ensure that MAX DECREASE is notgreater than DISPATCHER ROUND.

E CHECK 0074 ttOS: MAX INCREASE and/or MAX DECREASE are invalidWhen using SMOOTH synchronization the valuesMAX INCREASE and MAX DECREASE specify by how muchthe dispatcher round can be increased or decreased respectively(per dispatcher round) in order to achieve synchronization to aglobal time source. Ensure that these values are 0 or a positivevalue.

E CHECK 0075 ttOS: MAX INCREASE is invalid (>= DISPATCHER ROUND)When using SMOOTH synchronization the value ofMAX INCREASE defines by how much the dispatcher roundcan be increased (per dispatcher round) in order to achievesynchronization to a global time source. This value may not belarger than DISPATCHER ROUND.

E CHECK 0076 ttOS: Effective length of dispatcher round is invalidWhen using SMOOTH synchronization the effective length of thedispatcher round is: DISPATCHER ROUND - MAX DECREASE.This value must be positive. Ensure that MAX DECREASE is notgreater than DISPATCHER ROUND.

E CHECK 0077 ttOS: MIN INTERVAL is invalid. In this version must be at least2usMIN INTERVAL specifies the minimum time between 2 dis-patcher table events. Due to microprocessor constraints thismust be at least 2us (2000ns).


E CHECK 0078 ttOS: MIN INTERVAL must be smaller than the effective dis-patcher roundMIN INTERVAL specifies the minimum time between 2 dis-patcher table events. This value must be smaller thanthe effective dispatcher round otherwise the system is use-less. The effective dispatcher round for SMOOTH sync is:DISPATCHER ROUND - MAX DECREASE The effective dis-patcher round for HARD sync is: DISPATCHER ROUND -MAX DECREASE The effective dispatcher round for NONE syncis: DISPATCHER ROUND

E CHECK 0079 ttAPPMODE <name>: TIME is invalid or undefinedEach entry in the dispatcher table (ttAPPMODE) needs to have aTIME associated with it. Check that the TIME variable is defined.

E CHECK 0080 ttAPPMODE <name>: MIN INTERVAL violatedThere is not enough time between two dispatcher table events.This includes the start of the round.

E CHECK 0081 ttAPPMODE <name>: Effective length of DIS-PATCHER ROUND violatedThere are dispatcher events that occur outside the valid dispatchround. Note that for SMOOTH and HARD synchronization, theeffective length of the dispatcher round is DISPATCHER ROUND- MAX DECREASE - MIN INTERVAL!

E CHECK 0082 ttAPPMODE <name>: Dispatcher table has no entriesThere is a disptacher table (ttAPPMODE object) that has no en-tries defined. Either place some entries in the table or removeit.

E CHECK 0083 ttAPPMODE <name>: TASK field for ACTIVATETASK is unde-finedIn the dispatcher table there is an ACTIVATETASK defined butthe TASK to be activated is undefined.

E CHECK 0084 ttAPPMODE <name>: TASK field for ACTIVATETASK is invalidIn the dispatcher table there is an ACTIVATETASK defined butthe ttTASK to be activated is invalid. Check that it has not berename or misspelt.


E CHECK 0085 ttAPPMODE <name>: ISR field for ENABLEISR is undefinedIn the dispatcher table there is an ENABLEISR entry but the ISRto be enabled is undefined. Enter the ISR that you want to beenabled.

E CHECK 0086 ttAPPMODE <name>: ISR field for ENABLEISR is invalidIn the dispatcher table there is an ENABLEISR entry but the ISRto be enabled is invalid. Enter the ttISR that you want to be en-abled. Check that the ttISR was not deleted or misspelt.

E CHECK 0087 ttAPPMODE <name>: Invalid action definedThere is an invalid action defined in the dispatcher table. Changeit to one of ENABLEISR, ACTIVATETASK or DEADLINE.

E CHECK 0088 ttAPPMODE: No application modes defined!Time-triggered objects have been defined but there are no appli-cation modes (dispatcher tables) defined. An OSEKTime systemis useless without application modes. Create a new ttAPPMODEobject or remove the ttOS object and use a standard OSEK sys-tem.

E CHECK 0089 ttMESSAGE: Name field is undefined!Every ttMESSAGE needs a name. ttMESSAGESs withouta name make no sense. The name is used when callingttSendMessage and ttReceiveMessage.

E CHECK 0090 ttMESSAGE: LENGTH field is invalidEvery ttMESSAGE needs a length in bits. Check that it is greaterthan 0. A message with no LENGTH makes no sense.

E CHECK 0091 ttTASK: Name field is undefined!Every ttTASK needs a name. ttTASKs without a name make nosense. The name is used when performing ACTIVATETASK anddefining ttTASKS in the source code.

E CHECK 0092 ttISR: Name field is undefined!Every ttISR needs a name. ttTASKs without a name make nosense. The name is used when performing ENABLEISR anddefining ttISRs in the source code.

E CHECK 0093 ttAPPMODE: Name field is undefined!Every ttAPPMODE needs a name. The name is used when call-ing ttSwitchAppMode.


E CHECK 0094 Alarm <name> does not specify a valid ALARMCALLBACK-NAMEThe alarms ACTION is set to ALARMCALLBACK, but there is novalid ALARMCALLBACKNAME specified.

E CHECK 0095 Alarm <name> is set to AUTOSTART but doesn’t specify aALARMTIME or CYCLETIMEEvery alarm which is to be automatically started must specify aALARMTIME and a CYCLETIME. An alarm without those valuescannot be started automatically.

E CHECK 0096 Task <name>: Uses more than one internal resourceAccording to the OSEK standard only one internal resource maybe defined per task. Ensure that the task specified does not havemore than one internal resource defined in the RESOURCEs tab.

E CHECK 0097 Resource <name>: Linked resources cannot link to INTERNALresourcesA linked resource has been defined that links to an INTERNALresource. According to the OSEK standard this is not allowed.Linked resource may only link to STANDARD or LINKED re-sources.

E CHECK 0098 Resource <name>: LINKEDRESOURCE is invalidThe resource has been defined as a LINKED resource but thefield LINKEDRESOURCE has either not been filled in or pointsto a non-existing resource.

E CHECK 0099 Resource <name>: A linked resource cannot link to itself!The resource property LINKEDRESOURCE of the linked re-source points to itself.

E CHECK 0100 ttOS: Startup method is invalid (sync startup in an asynchronoussystem)When using an asynchronous system it is not possible to startupsynchronus


E CHECK 0105 Interrupt <int name>: Only category 2 interrupts may hold re-sources!The interrupt has a resource defined in the RESOURCEs cardbut is not of Category 2. The OSEK-OS standard states thatonly interrupts of category 2 may have resources associated tothem. Either remove the resources from the RESOURCEs cardor change the interrupt to category 2.

E CHECK 0107 Trace support is limited to 0xffff elementsThe tracing support of the kernel only allows up to 0xffff element.

E CHECK 0108 More than one OS object definedIn this OIL file more than one OS object is defined but only oneinstance is allowed.

E CHECK 0109 Interrupt <int name>: Interrupts must not use internal resources!The interrupt has a resource defined in the RESOURCEs cardwhich is of type INTERNAL. This is not supported in ProOSEK.

E CHECK 0111 ALARM <name> is set to AUTOSTART but doesn’t specifies anunknown APPMODEEvery alarm which is to be automatically started must specify avalid APPMODE.

E CHECK 0112 TASK <name> is set to AUTOSTART but specifies an unknownAPPMODEEvery task which is to be automatically started must specify avalid APPMODE.

E CHECK 0113 More than <number> appmodes configured!The number of application modes exceeds the maximum allowednumber. You must reduce the number of appmodes.

E CHECK 0114 You need to define an OS object.When defining resources such as tasks, alarms, etc. you alsomust define an OS object.

E CHECK 0114 ttOS and OS Must be the same Derivate !It is not possible to use a different Derivate for OSEK and OSEK-Time


E CHECK 0115 You need to define an ttOS object.When defining resources such as ttTasks, etc. you also mustdefine an ttOS object.

E CHECK 0116 You need to define either an OS or ttOS object.You need to define either an OS or ttOS object. Generation wouldnot make any sense.

E CHECK 0117 Demo limitations are exceededThis is a demo version. The operating system objects are limited.

E CHECK 0117 Demo limitations are exceededThis is a demo version. The operating system objects are limited.

E CHECK 0118 RES SCHEDULER is defined but USERESSCHEDULER is setto FALSERES SCHEDULER is defined but USERESSCHEDULER is setto FALSE. RES SCHEDULER must not be used if USERESS-CHEDULER is set to FALSE.

E COM222 0001 Message <message>: Unknown message type (chooseQUEUED or UNQUEUED)There is a unknown type for the message. A message has to beeither queued or unqueued.

E COM222 0002 Message <message>: QUEUEDEPTH invalid or undefinedFor a queued message you must specify the length of the mes-sage queue. This value must be greater than 0.

E COM222 0003 Message <message>: QUEUEDEPTH exceeds maximum al-lowable lengthFor a queued message, the depth of the message queue mustbe specified. The specified value exceeds the maximum allowedvalue. Note that for some architectures, the limit is even lowerbecause of architectural restrictions.

E COM222 0004 Message <message>: The C data type (CDATATYPE) is unde-finedThe COM subsystem needs the C data type of the message toallocate a buffer. This information is missing, either because novalue for the type is present or the value is empty.


E COM222 0005 Interrupt <int name>: Only category 2 interrupts may use mes-sagesThe interrupt has a message defined on the ACCESSORs cardbut is not of Category 2. The OSEK-OS standard states that onlyinterrupts of category 2 may use kernal functions/functionality.Either remove the message(s) from the MESSAGEs card orchange the interrupt to category 2.

E COM222 0006 Message <message>: ACTIVATETASK refers to an invalid taskYou specified ACTIVATETASK as the message action, but thetask is either not available or not defined.

E COM222 0007 Message <message>: No task or event for action specifiedYou specified SETEVENT as the message action, but the task orevent is either not available or not defined.

E COM222 0008 Message <message>: CALLBACKNAME is invalidYou specified a callback function as the action, but the argumentfor the function is either missing or incorrect. Check the CALL-BACKNAME in the Message object.

E COM222 0009 Message <message>: FLAGNAME is undefinedThe notification method of setting a flag has been selected, butthe attributed FLAGNAME has not been set.

E COM222 0010 Message <message>: ACTION field is invalidAn ACTION has been defined that is not part of the OIL standardand therefore not understood by the Configurator. Valid optionsare: ACTIVATETASK, SETEVENT, CALLBACK, FLAG or NONE.

E COM222 0011 Message <message>: ACTION is undefined! Select NONE forno actionAccording to the oil standard an ACTION must be defined forall MESSAGE objects. Valid actions are: ACTIVATETASK,SETEVENT, CALLBACK, FLAG or NONE.

E COM222 0012 More than one COM object defined.There is more than one COM object defined but only one is al-lowed!


E COM222 0013 Task <task>: WITHOUTCOPY only valid for unqueued mes-sagesThe WITHOUTCOPY method is only applicable to unqueuedmessages. Either make the message UNQUEUED or deselectthe WITHOUTCOPY checkbox.

E COM222 0014 Task <task>: ACCESSNAME is undefinedACCESSNAME is undefined in the task object when definingmessage actions performed by the task.

E COM222 0015 Task <task>: MESSAGE invalid in ACCESSOR listThe task specifies an accessor, but the name of the message(MESSAGE field) is undefined or there is no message definedfor the given name.

E COM222 0016 ISR: <isr>: ISRs can only use unqueued messagesWithin ISRs only unqueued messages can be accessed

E COM222 0017 ISR <isr>: MESSAGE in ACCESSORs does not existThe ISR specifies an accessor, but the MESSAGE name givendoes not correspond to a MESSAGE object defined in this OILfile.

E COM222 0018 ISR <isr>: MESSAGE undefined in ACCESSOR listThe ISR specifies an accessor, but the name of the message(MESSSAGE) is either missing or there is no message of thegiven name.

E COM222 0019 Event <name>: Too many flags used by the messages!Too many flags used by the messages, the flagmask can onlyhold 32 different flags!


Warnings

Code DescriptionW CHECK 0001 Task <name>: STACKSIZE == 0

The task has a stack size of zero. Ensure that the task does notrequire any stack (this includes local variables or function calls).

W CHECK 0002 OS optimization: It is possible to use non-preemptive schedulingThe scheduling of the system can be non-preemptive. This couldmake the system more efficient than the current configuration.

W CHECK 0003 OS optimization: It is possible to use fully preemptive schedulingThe scheduling of the system can be fully preemptive instead ifmixed. This would probably make the system more efficient thanthe current configuration

W CHECK 0007 ttOS: The MAX INCREASE/MAX DECREASE value will be ig-nored as SYNC is NONEWith sychronization method NONE the values MAX INCREASEand MAX DECREASE are not used as the system is never sy-chronized with a global time source. Because of this the valueswill be ignored and not checked for correctness.

W CHECK 0008 ttOS: The MAX INCREASE value will be ignored as SYNC isHARDWhen using HARD synchronization MAX INCREASE is notused. Only MAX DECREASE is used to specify by how muchthe dispatcher round can be shortened.

W CHECK 0009 TASK <name> is set to AUTOSTART but doesn’t specify anAPPMODE, using OSDEFAULTAPPMODEEvery task which is to be automatically started should specifyan APPMODE. Without an APPMODE specified we will assumeOSDEFAULTAPPMODE

W CHECK 0010 ALARM <name> is set to AUTOSTART but doesn’t specify anAPPMODE, using OSDEFAULTAPPMODEEvery alarm which is to be automatically started should specifyan APPMODE. Without an APPMODE specified we will assumeOSDEFAULTAPPMODE


W CHECK 0011 Resource <name> is defined but not usedA resource must be used by one or more tasks. A resource notused by any task can not be allocated by anyone and is thereforesenseless.

W CHECK 0012 Resource <name> has no effect on the ceiling priority calculationThe resource has no effect on the ceiling priority calculation.Resources should be used to prevent TASKs and/or ISRs withdifferent priorities from acccessing the same shared resource(s)Check that the resource is being used by more than one task orISR and if not then the resource can be removed from the sys-tem.

W CHECK 0016 Resource <name>: RESOURCEPROPERTY was not set, as-suming to be STANDARDThe resource property was not defined. This should be definedin OS 2.2 and OIL 2.3 according to the standards. ProOSEK willassume this is a STANDARD resource.

W CHECK 0017 Event not used!Event is not used. To use events they must be assigned to atleast one task.

W CHECK 0018 No tasks will be started at system startup!The system does not have a user main() and is not using theOSDEFAULTAPPMODE. No tasks will be activated!

W COM222 0001 Message <message>: Size information may be incorrect asLENGTH is undefinedThe length of the message buffer is not specified. This meansthat the RAM usage calculations may be incorrect.

W COM222 0002 Message <name> is defined but not usedA message has been defined but has not be assigned to a taskor ISR object. Your system can be optimized by removing themessage object

W COM222 0003 Message <message>: Action NONE is ignored!The action NONE is ignored because other actions are listed forthis message object.


W COM222 0004 More than one receiver for a queued message!Queued messages have only one queue (compare COM V2.2.2section 2.2.4.1.2). Therefore it doesn’t make sense to have mul-tiple internal receivers for a queued message!

DProOSEK Release Notes

Release Notes Configurator

Date: 2005-06-23

Version: 4.1

Overview

Standalone ProOSEK Configurator with support for OIL files splitted into includedfiles.

Features

Changes to version 4.0:

• improved GUI

APPENDIX D. PROOSEK RELEASE NOTES 187

Differences to previous versions

to 2004-10-01

• none

to 2004-09-20

• Rt-Id #4307: ProOSEK Configurator does not hang anymore when installingupdate packages.

to 2004-08-31

• none

to 2004-06-25

• none

to 2003-11-26

• updated to jre1.4.2 04, fixes sporadic crashes at GUI startup

• updated to new licenses

• new OIL structure, change should be done automatically.

to 2003-11-26:

Known Problems

none

ETools

E.1 Dot

In the HTML pages may appear images if dot from AT&T is available. Youcan download the graphviz package from http://www.graphviz.org or http://-

www.research.att.com/sw/tools/graphviz/. It must be installed such that it canbe found in the path. To test this just open up a command window and call the dotprogram:

C:\>dot -V

dot version 1.7.6 (Fri May 18 11:10:50 EDT 2001)

C:\>

The dot version should not be to old otherwise the image maps will be garbled.

http://www.graphviz.org

http://www.research.att.com/sw/tools/graphviz/

http://www.research.att.com/sw/tools/graphviz/

Documents

ProOSEK UsersGuide · Removed duplicate sect1 1.18 30.09.2004 haberstu Fixed typos 1.17 03.08.2004 haberstu Fixed typos 1.16 03.08.2004 haberstu Removed Version Number Documented